Aiaag Oracle Fusion Middleware Administrator Guide For Access Management 11.1.2.3

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 1662 [warning: Documents this large are best viewed by clicking the View PDF Link!]

[1]
Oracle® Fusion Middleware
Administrator's Guide for Oracle Access Management
11g Release 2 (11.1.2.3) for All Platforms
E54424-04
September 2015
Oracle Fusion Middleware Administrator's Guide for Oracle Access Management, 11g Release 2 (11.1.2.3) for
All Platforms
E54424-04
Copyright © 2000, 2015 Oracle and/or its affiliates. All rights reserved.
Primary Author: Michael Teger
Contributing Author: Vinaye Misra, Kevin Kessler, Cathy Tenga, Serge Pomorski
Contributor: Vadim Lander, Vamsi Motokuru, Damien Carru, Peter Povinec, Weifang Xie, Satish
Madawand, Neelima Jadhav, Charles Wesley, Harshal X Shaw, Jeremy Banford, Rey Ong, Ramana Turlapati,
Deepak Ramakrishnan, David Goldsmith, Vishal Parashar, Carlos Subi, Patricia Fuzesy
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users
are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on
the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to
the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to third-party content, products, and services
unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services, except as set forth in an applicable agreement between you and
Oracle.
iii
Content
Preface ............................................................................................................................................................... lvii
What's New in This Guide?.................................................................................................................... lix
Part I Introduction to Oracle Access Management
1 Introducing Oracle Access Management
1.1 Understanding Oracle Access Management Services ........................................................... 1-1
1.2 Understanding Oracle Access Management Access Manager............................................. 1-3
1.2.1 About Components in Access Manager ........................................................................... 1-4
1.2.2 Understanding Access Manager Deployments............................................................... 1-5
1.3 About Access Manager 11.1.2.3.0 ............................................................................................. 1-7
1.3.1 About the Features Of Access Manager 11.1.2.3.0 .......................................................... 1-7
1.3.2 About Features Not In Access Manager 11.1.2.3.0.......................................................... 1-9
1.4 About System Requirements and Certification...................................................................... 1-9
1.5 Understanding Oracle Access Management Installation................................................... 1-10
1.5.1 About Oracle Access Management Installation .......................................................... 1-10
1.5.2 About Oracle Access Management and WebGates ..................................................... 1-10
1.5.3 About Oracle Access Management Post-Installation Tasks ....................................... 1-10
2 Getting Started with Oracle Access Management
2.1 Starting and Stopping Servers in Your Deployment ............................................................. 2-1
2.1.1 Starting Node Manager....................................................................................................... 2-1
2.1.2 Starting and Stopping WebLogic AdminServer.............................................................. 2-2
2.1.3 Starting and Stopping Managed WebLogic Servers and Access Manager Servers ... 2-2
2.2 About Oracle Access Management Administrators .............................................................. 2-3
2.3 About the Oracle Access Management Console and the Policy Manager Console .......... 2-4
2.4 Understanding the Oracle Access Management Console..................................................... 2-5
2.4.1 About the System Launch Pad........................................................................................... 2-5
2.4.2 Accessing the Access Manager Launch Pad .................................................................... 2-6
2.4.3 Accessing the Agents Launch Pad .................................................................................... 2-6
2.4.4 Accessing the Help Desk Launch Pad .............................................................................. 2-7
2.4.5 Accessing the Self Service Launch Pad............................................................................. 2-7
2.5 Logging Into the Oracle Access Management Console......................................................... 2-7
2.5.1 Logging Into The Oracle Access Management Console ................................................ 2-8
iv
2.5.2 Logging Into the Secure Oracle Access Management Console (HTTPS) .................... 2-8
2.6 Using the Oracle Access Management Console ..................................................................... 2-9
2.6.1 Signing Out........................................................................................................................... 2-9
2.6.2 Accessing Online Help..................................................................................................... 2-10
2.6.3 Conducting A Search ....................................................................................................... 2-10
2.7 Configuring with the Command-Line Tools ....................................................................... 2-11
2.8 Logging, Auditing, Reporting and Monitoring Performance ........................................... 2-11
2.9 Configuring Oracle Access Management Login Options .................................................. 2-12
2.9.1 Administering the Forgot Password URL .................................................................... 2-12
2.9.2 Choosing a User Login Language .................................................................................. 2-13
2.9.3 Understanding Persistent Login..................................................................................... 2-16
Part II Managing Common and System Configurations
3 Managing Common Services and Certificate Validation
3.1 Configuring Oracle Access Management................................................................................ 3-1
3.2 Enabling or Disabling Available Services ............................................................................... 3-3
3.3 Managing Common Settings..................................................................................................... 3-5
3.3.1 Managing Common Settings ............................................................................................. 3-6
3.3.2 Viewing Common Coherence Settings............................................................................. 3-7
3.4 Managing Certificate Validation and Revocation.................................................................. 3-7
3.4.1 Enabling the Certificate Revocation List Functionality.................................................. 3-8
3.4.2 Enabling OCSP Certificate Validation ............................................................................. 3-9
3.4.3 Enabling CRL Distribution Point Extensions .................................................................. 3-9
3.4.4 Additional OCSP Configurations................................................................................... 3-10
4 Delegating Administration
4.1 Understanding Administrator Roles........................................................................................ 4-1
4.2 Delegating the Identity Store .................................................................................................... 4-2
4.3 Assigning Roles Using the Administration Console ............................................................. 4-3
4.4 Using the Container Security Framework and MBeans........................................................ 4-3
4.5 Using the Remote Registration Utility..................................................................................... 4-4
4.6 Auditing Reports......................................................................................................................... 4-4
5 Managing Data Sources
5.1 About the Data Sources ............................................................................................................. 5-1
5.1.1 About the oam-config.xml Configuration Data File....................................................... 5-3
5.1.2 About the Default LDAP Group........................................................................................ 5-4
5.2 Registering and Managing User Identity Stores ................................................................... 5-4
5.2.1 Understanding User Identity Stores ................................................................................. 5-4
5.2.2 Using the System Store for User Identities ...................................................................... 5-5
5.2.3 Using Multiple Identity Stores........................................................................................... 5-6
5.2.4 Defining the User Identity Store Registration Settings .................................................. 5-8
5.2.5 Registering a New User Identity Store .......................................................................... 5-12
5.2.6 Viewing or Editing a User Identity Store Registration ............................................... 5-13
5.2.7 Deleting a User Identity Store Registration .................................................................. 5-14
v
5.3 Managing the Identity Directory Service User Identity Stores ......................................... 5-14
5.3.1 Using Identity Directory Services .................................................................................. 5-15
5.3.2 Creating an Identity Directory Service Profile ............................................................. 5-17
5.3.3 Editing or Deleting an Identity Directory Service Profile........................................... 5-21
5.3.4 Creating a Form-fill Application Identity Directory Service Profile......................... 5-24
5.3.5 Understanding the Pre-Configured Identity Directory Service Profile.................... 5-25
5.3.6 Creating an Identity Directory Service Repository...................................................... 5-25
5.4 Understanding Administrator Roles..................................................................................... 5-26
5.4.1 Adding Administrator Roles........................................................................................... 5-27
5.4.2 Managing Administrator Roles ...................................................................................... 5-27
5.5 Managing the Policy and Session Database ........................................................................ 5-29
5.5.1 About the Database Store for Policy, Password Management, and Sessions.......... 5-29
5.5.2 About Database Deployment.......................................................................................... 5-29
5.5.3 Configuring a Separate Database for Access Manager Sessions ............................... 5-30
5.6 Introduction to Oracle Access Management Keystores ..................................................... 5-31
5.6.1 About Access Manager Security Keys and the Embedded Java Keystore ............... 5-31
5.6.2 About Access Manager Keystores.................................................................................. 5-32
5.6.3 About Identity Federation Keystore .............................................................................. 5-34
5.7 Integrating a Supported LDAP Directory with Oracle Access Manager ........................ 5-34
6 Managing Server Registration
6.1 Before You Register .................................................................................................................... 6-1
6.2 Understanding OAM Server Registration and Management............................................... 6-1
6.2.1 About Individual OAM Server Registrations ................................................................. 6-2
6.2.2 About the Embedded Proxy Server and Backward Compatibility .............................. 6-3
6.2.3 About 11g SSO, Legacy 10g SSO in Combination with OSSO 10g............................... 6-3
6.2.4 About Communication Between OAM Servers and WebGates ................................... 6-4
6.2.5 About Restarting Servers After Configuration Changes ............................................... 6-4
6.3 Managing Individual OAM Server Registrations ................................................................. 6-5
6.3.1 About the OAM Server Registration Page ...................................................................... 6-5
6.3.2 Registering a Fresh OAM Server Instance ....................................................................... 6-8
6.3.3 Viewing or Editing Individual OAM Server Registrations and Proxy Settings ........ 6-9
6.3.4 Deleting an Individual Server Registration ..................................................................... 6-9
Part III Logging, Auditing, Reporting and Monitoring Performance
7 Logging Component Event Messages
7.1 About Oracle Access Management Logging........................................................................... 7-1
7.2 Logging Component Event Messages ..................................................................................... 7-1
7.2.1 About Component Loggers................................................................................................ 7-3
7.2.2 Sample Logger and Log Handler Definition ................................................................... 7-4
7.2.3 About Logging Levels......................................................................................................... 7-5
7.3 Configuring Logging for Access Manager ............................................................................. 7-5
7.3.1 Modifying the Logger Level for Access Manager........................................................... 7-6
7.3.2 Adding an Access Manager-Specific Logger and Log Handler ................................... 7-7
7.4 Configuring Logging for Security Token Service and Identity Federation........................ 7-8
vi
7.4.1 Configuring Logging for Security Token Service or Identity Federation ................... 7-9
7.4.2 Defining Log Level and Log Details for Security Token Service or Identity Federation..
7-10
7.5 About Mobile and Social Logging......................................................................................... 7-11
7.6 Understanding Logging for the Access Portal Service....................................................... 7-11
7.7 Validating Run-time Event Logging Configuration ........................................................... 7-11
8 Auditing Administrative and Run-time Events
8.1 Introduction to Oracle Fusion Middleware Auditing ........................................................... 8-1
8.2 Understanding Oracle Access Management Auditing ......................................................... 8-2
8.2.1 About Oracle Access Management Auditing Configuration ....................................... 8-2
8.2.2 About Audit Record Storage.............................................................................................. 8-3
8.2.3 About Audit Reports and Oracle Business Intelligence Publisher............................... 8-4
8.2.4 About the Audit Log and Data .......................................................................................... 8-5
8.3 Access Manager Events You Can Audit.................................................................................. 8-6
8.3.1 Access Manager Administrative Events You Can Audit............................................... 8-6
8.3.2 Access Manager Run-time Events You Can Audit ......................................................... 8-8
8.3.3 Auditing Authentication Events..................................................................................... 8-11
8.4 Mobile and Social Events You Can Audit ............................................................................ 8-11
8.4.1 REST Run-Time Audit Events ........................................................................................ 8-11
8.4.2 Mobile and Social Audit Events ..................................................................................... 8-12
8.5 Identity Federation Events You Can Audit.......................................................................... 8-14
8.5.1 Session Management Events for Identity Federation.................................................. 8-14
8.5.2 Protocol Flow Events for Identity Federation .............................................................. 8-15
8.5.3 Server Configuration Events for Identity Federation.................................................. 8-15
8.5.4 Security Events for Identity Federation......................................................................... 8-16
8.6 Security Token Service Events You Can Audit ................................................................... 8-16
8.6.1 About Audit Record Content Common to All Events ................................................ 8-17
8.6.2 Security Token Service Administrative Events You Can Audit ................................ 8-17
8.6.3 Security Token Service Run-time Events You Can Audit........................................... 8-19
8.7 Setting Up Auditing for Oracle Access Management ........................................................ 8-20
8.7.1 Setting Up the Audit Database Store ............................................................................. 8-21
8.7.2 Preparing Oracle Business Intelligence Publisher EE ................................................. 8-21
8.7.3 Using the Oracle Access Management Console for Audit Configuration .............. 8-22
8.7.4 Adding, Viewing, or Editing Audit Settings ............................................................... 8-24
8.8 Validating Auditing and Reports ......................................................................................... 8-25
9 Logging WebGate Event Messages
9.1 About Logging, Log Levels, and Log Output......................................................................... 9-1
9.1.1 About Log Levels................................................................................................................. 9-2
9.1.2 About Log Output ............................................................................................................... 9-3
9.2 About Log Configuration File Paths and Contents ............................................................... 9-4
9.2.1 Log Configuration File Paths and Names........................................................................ 9-4
9.2.2 Log Configuration File Contents....................................................................................... 9-5
9.3 About Directing Log Output to a File or the System File ..................................................... 9-9
9.4 Structure and Parameters of the Log Configuration File................................................... 9-10
9.4.1 About The Log Configuration File Header................................................................... 9-11
vii
9.4.2 About The Initial Compound List.................................................................................. 9-11
9.4.3 About The Simple List and Logging Threshold........................................................... 9-11
9.4.4 About The Second Compound List and Log Handlers............................................... 9-13
9.4.5 About The List for Per-Module Logging....................................................................... 9-14
9.4.6 About The Filter List ........................................................................................................ 9-14
9.4.7 About XML Element Order............................................................................................. 9-15
9.5 About Activating and Suppressing Logging Levels........................................................... 9-16
9.5.1 About Log Handler Precedence ..................................................................................... 9-16
9.6 Understanding the Mandatory Log-Handler Configuration Parameters ....................... 9-17
9.6.1 Settings in the Default Log Configuration File ............................................................ 9-18
9.6.2 Description of the Settings in the Default Log Configuration File............................ 9-20
9.7 Configuring Different Threshold Levels for Different Types of Data.............................. 9-22
9.7.1 About the MODULE_CONFIG Section......................................................................... 9-22
9.7.2 Configuring a Log Level Threshold for a Function or Module ................................. 9-25
9.8 Filtering Sensitive Attributes.................................................................................................. 9-26
10 Reporting
10.1 About the Reports.................................................................................................................... 10-1
10.2 Accessing Oracle Access Management Reports .................................................................. 10-2
10.3 Supported Output Formats .................................................................................................... 10-2
10.4 Reports for Access Manager................................................................................................... 10-3
10.4.1 Account Management Reports ....................................................................................... 10-3
10.4.2 Authentication Reports.................................................................................................... 10-3
10.4.3 Errors and Exceptions ...................................................................................................... 10-4
10.5 Creating Reports Using Third-Party Software .................................................................... 10-6
11 Monitoring Performance and Health
11.1 Introduction to Performance Monitoring............................................................................. 11-1
11.2 Monitoring Server Metrics Using Oracle Access Management Console......................... 11-2
11.2.1 Monitoring Server Instance Performance ..................................................................... 11-2
11.2.2 Reviewing Server Metrics................................................................................................ 11-2
11.3 Monitoring SSO Agent Metrics Using Oracle Access Management Console ................. 11-6
11.3.1 Reviewing WebGate Metrics .......................................................................................... 11-6
11.3.2 Reviewing OSSO Agent Metrics..................................................................................... 11-8
11.4 Introduction to OAM Proxy Metrics and Tuning ............................................................. 11-10
11.4.1 About OAM Proxy Metrics ........................................................................................... 11-10
11.4.2 OAM Proxy Server Tuning Parameters....................................................................... 11-10
11.5 Monitoring Metrics Using the DMS Console .................................................................... 11-11
11.5.1 Monitoring OAM Metrics.............................................................................................. 11-11
11.5.2 Monitoring Coherence Caches...................................................................................... 11-12
11.5.3 Monitoring OpenSSO Proxy Metrics ........................................................................... 11-12
11.6 Monitoring the Health of an Access Manager Server....................................................... 11-14
11.6.1 Understanding WebGate and Access Manager Communications .......................... 11-15
11.6.2 Monitoring Access Manager Server Health................................................................ 11-15
viii
12 Monitoring Performance and Logs with Fusion Middleware Control
12.1 Introduction to Fusion Middleware Control ...................................................................... 12-1
12.2 Logging In to and Out of Fusion Middleware Control ...................................................... 12-2
12.2.1 Logging In To Fusion Middleware Control.................................................................. 12-3
12.2.2 Logging Out of Fusion Middleware Control................................................................ 12-3
12.3 Displaying Menus and Pages in Fusion Middleware Control ......................................... 12-3
12.3.1 About the Farm Page in Fusion Middleware Control................................................. 12-3
12.3.2 About Context Menus and Pages in Fusion Middleware Control ............................ 12-5
12.3.3 Displaying Context Menus and Target Details in Fusion Middleware Control ..... 12-7
12.4 Viewing Performance in Fusion Middleware Control ....................................................... 12-8
12.4.1 About Performance Overview Pages in Fusion Middleware Control ..................... 12-9
12.4.2 About the Metrics Palette and the Performance Summary Page ............................ 12-15
12.4.3 Displaying Performance Metrics in Fusion Middleware Control ........................... 12-17
12.4.4 Displaying Component-Specific Performance Details.............................................. 12-19
12.5 Managing Log Level Changes in Fusion Middleware Control....................................... 12-19
12.5.1 About Dynamic Log Level Changes ............................................................................ 12-20
12.5.2 Setting Log Levels Dynamically Using Fusion Middleware Control ..................... 12-24
12.6 Managing Log File Configuration from Fusion Middleware Control ........................... 12-24
12.6.1 About Log File Configuration....................................................................................... 12-24
12.6.2 Managing Log Files with Fusion Middleware Control............................................. 12-27
12.7 Viewing Log Messages in Fusion Middleware Control................................................... 12-28
12.7.1 About Finding, Viewing, and Exporting Log Messages........................................... 12-28
12.7.2 Viewing Logged Messages With Fusion Middleware Control................................ 12-32
12.8 Displaying MBeans in Fusion Middleware Control......................................................... 12-33
12.8.1 About the System MBean Browser............................................................................... 12-34
12.8.2 Managing Mbeans .......................................................................................................... 12-36
Part IV Managing Access Manager Settings and Agents
13 Configuring Access Manager Settings
13.1 Oracle Access Management Overview................................................................................. 13-1
13.2 Managing Load Balancing ..................................................................................................... 13-1
13.2.1 About Common Load Balancing Settings .................................................................... 13-1
13.2.2 Managing OAM Server Load Balancing Settings ........................................................ 13-2
13.3 Managing Secure Error Modes ............................................................................................. 13-3
13.3.1 About OAM Server Error Modes ................................................................................... 13-3
13.3.2 Managing OAM Server Secure Error Modes................................................................ 13-5
13.4 Managing SSO Tokens and IP Validation ............................................................................ 13-5
13.4.1 About Access Manager SSO Tokens and IP Validation Settings............................... 13-5
13.4.2 Managing SSO Tokens and IP Validation..................................................................... 13-6
13.5 Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security .......... 13-6
13.5.1 About Simple and Cert Mode Transport Security....................................................... 13-7
13.5.2 About the Common OAM Proxy Page for Secure Server Communications ........... 13-8
13.5.3 Viewing or Editing Simple or Cert Settings for OAM Proxy .................................... 13-8
13.5.4 Configuring 64-bit WebGate in Cert Mode................................................................... 13-9
13.5.5 Tuning the Simple Mode WebGate................................................................................ 13-9
ix
13.6 Managing Run Time Policy Evaluation Caches .................................................................. 13-9
13.6.1 About Run Time Policy Evaluation Caches.................................................................. 13-9
13.6.2 Managing Run Time Policy Evaluation Caches......................................................... 13-10
14 Introduction to Agents and Registration
14.1 Introduction to Policy Enforcement Agents ........................................................................ 14-1
14.1.1 About Agent Types and Runtime Processing ........................................................... 14-1
14.1.2 About 11g WebGate Configured as a Detached Credential Collector...................... 14-4
14.1.3 About 11g WebGate Functionality for Mobile and Social ......................................... 14-5
14.1.4 About the Pre-Registered 10g WebGate IAMSuiteAgent .......................................... 14-5
14.2 Introduction to Agent Registration ....................................................................................... 14-5
14.2.1 About Agent Registration, Keys, and Policies ............................................................. 14-6
14.2.2 About File System Changes and Artifacts for Registered Agents............................. 14-7
14.3 Introduction to Remote Registration..................................................................................... 14-8
14.3.1 Performing In-Band Remote Registration .................................................................... 14-8
14.3.2 Performing Out-of-Band Remote Registration ............................................................ 14-9
14.3.3 Updating Agent Configuration Files ........................................................................... 14-10
15 Registering and Managing OAM 11g Agents
15.1 Before Registering and Managing Agents............................................................................ 15-1
15.2 Understanding OAM Agent Registration Parameters in the Console............................. 15-2
15.2.1 About Create OAM WebGate Page and Parameters................................................... 15-2
15.2.2 About User-Defined WebGate Parameters................................................................... 15-5
15.2.3 About IP Address Validation for WebGates............................................................... 15-10
15.3 Registering an OAM Agent Using the Console................................................................. 15-13
15.4 Configuring and Managing Registered OAM Agents Using the Console.................... 15-14
15.4.1 Understanding Registered OAM Agent Configuration Parameters in the Console .........
15-14
15.4.2 Searching for an OAM Agent Registration................................................................. 15-20
15.4.3 Viewing or Editing an OAM Agent Registration Page in the Console................... 15-22
15.4.4 Deleting OAM Agent Registration Using the Console ............................................. 15-23
15.5 Understanding the Remote Registration Tool, Modes, and Process.............................. 15-24
15.5.1 About Remote Registration Command Arguments and Modes ............................. 15-25
15.5.2 Common Elements within Remote Registration Request Templates ..................... 15-26
15.5.3 About Key Use, Generation, Provisioning, and Storage........................................... 15-27
15.6 Understanding Remote Registration Templates: OAM Agents...................................... 15-29
15.6.1 OAM Agent Parameters for Remote Registration ..................................................... 15-29
15.7 Performing Remote Registration for OAM Agents .......................................................... 15-32
15.7.1 Acquiring and Setting Up the Remote Registration Tool ........................................ 15-33
15.7.2 Creating Your Remote Registration Request.............................................................. 15-34
15.7.3 Performing In-Band Remote Registration .................................................................. 15-34
15.7.4 Performing Out-of-Band Remote Registration .......................................................... 15-35
15.8 Introduction to Updating Agents Remotely ...................................................................... 15-37
15.8.1 About Remote Agent Update Modes ......................................................................... 15-37
15.8.2 About Remote 11g OAM Agent Updates Template.................................................. 15-37
15.9 Updating Agents Remotely ................................................................................................. 15-38
x
15.9.1 Updating Agent Registrations Remotely .................................................................... 15-38
15.9.2 Validating an Agent Registration Remotely............................................................... 15-39
15.9.3 Removing an Agent Registration Remotely ............................................................... 15-39
15.10 Validating Remote Registration and Resource Protection............................................... 15-40
15.10.1 Validating Agent Registration using the Oracle Access Management Console.... 15-40
15.10.2 Verifying Authentication and Access After Remote Registration .......................... 15-40
15.11 Replacing the IAMSuiteAgent with an 11g WebGate ...................................................... 15-42
15.11.1 Registering a Replacement 11g WebGate for IAMSuiteAgent ................................ 15-43
15.11.2 Installing the Replacement 11g WebGate for IAMSuiteAgent ................................ 15-45
15.11.3 Updating the WebLogic Server Plug-in Configuration ............................................ 15-45
15.11.4 Confirming the AutoLogin Host Identifier for an OAM / OIM Integration......... 15-46
15.11.5 Configuring OAM Security Providers for WebLogic................................................ 15-46
15.11.6 Disabling IAMSuiteAgent ............................................................................................. 15-50
15.11.7 Verifying the Webgate Configuration ......................................................................... 15-51
15.12 Managing the Preferred Host in 10g WebGates................................................................ 15-51
setAllowEmptyHostIdentifier.............................................................................................. 15-53
16 Maintaining Access Manager Sessions
16.1 Introducing Access Manager Session Management ........................................................... 16-1
16.2 Understanding Server-Side Session Management.............................................................. 16-2
16.2.1 Securing Access Manager Sessions ................................................................................ 16-2
16.2.2 Understanding the Access Manager Session Lifecycle, States, and Enforcement... 16-3
16.2.3 Access Manager Sessions and the Role of Oracle Coherence..................................... 16-6
16.3 Server-Side Session Enforcement Examples ........................................................................ 16-7
16.3.1 Example 1: Single Authentication Scheme.................................................................... 16-7
16.3.2 Example 2: Multiple Authentication Schemes.............................................................. 16-7
16.4 Configuring the Server-Side Session Lifecycle ................................................................... 16-8
16.4.1 About Global Session Lifecycle Settings ....................................................................... 16-9
16.4.2 About Application-Specific Session Overrides .......................................................... 16-10
16.4.3 Viewing or Modifying Global Session Settings.......................................................... 16-11
16.4.4 Viewing or Modifying Optional Application-Specific Session Overrides ............. 16-11
16.5 Managing Active Server-Side Sessions............................................................................... 16-12
16.5.1 About the Session Management Pages........................................................................ 16-12
16.5.2 Locating and Managing Active Sessions..................................................................... 16-14
16.6 Validating Server-Side Session Operations........................................................................ 16-15
16.7 Understanding Client-Side Session Management............................................................. 16-16
16.8 Using WLST To Configure Session Management............................................................. 16-16
16.8.1 displaySSOSessionType................................................................................................. 16-16
16.8.2 configSSOSessionType................................................................................................... 16-16
Part V Implementing Multi-Data Centers
17 Understanding Multi-Data Centers
17.1 Introducing the Multi-Data Center ....................................................................................... 17-1
17.1.1 Understanding Cookies for Multi-Data Center............................................................ 17-3
17.1.2 Understanding Session Adoption During Authorization .......................................... 17-4
xi
17.1.3 Understanding Session Indexing ................................................................................... 17-5
17.1.4 Supported Multi-Data Center Topologies..................................................................... 17-5
17.2 Understanding Multi-Data Center Deployments ............................................................... 17-7
17.2.1 Understanding Session Adoption Without Re-authentication, Session Invalidation or
Session Data Retrieval 17-8
17.2.2 Understanding Session Adoption Without Re-authentication But With Session
Invalidation & Session Data Retrieval 17-9
17.2.3 Understanding Session Adoption Without Re-authentication & Session Invalidation
But With On-demand Session Data Retrieval 17-10
17.2.4 Understanding Authentication & Authorization Requests Served By Different Data
Centers 17-10
17.2.5 Understanding Logout and Session Invalidation ...................................................... 17-12
17.2.6 Understanding Stretch Cluster Deployments ............................................................ 17-13
17.3 Deploying Active-Active Multi-Data Center Topology................................................... 17-14
17.4 Load Balancing Between Access Management Components.......................................... 17-16
17.5 Understanding Time Outs and Session Syncs................................................................... 17-18
17.5.1 Ensuring Maximum Session Constraints .................................................................... 17-18
17.5.2 Configuring Policies for Idle Timeout ......................................................................... 17-18
17.5.3 Expiring Multi-Data Center Sessions........................................................................... 17-19
17.5.4 Synchronizing Sessions and Multi-Data Center Fail Over ....................................... 17-19
17.6 Replicating a Multi-Data Center Environment.................................................................. 17-22
17.6.1 Replicating Data Using the WLST................................................................................ 17-22
17.6.2 Syncing Data Using Automated Policy Synchronization ......................................... 17-22
17.7 Multi-Data Center Recommendations ................................................................................ 17-22
17.7.1 Using a Common Domain............................................................................................. 17-23
17.7.2 Concerning the DCC and the OAM_GITO................................................................. 17-23
17.7.3 Using an External Load Balancer ................................................................................. 17-24
17.7.4 Honoring Maximum Sessions....................................................................................... 17-24
17.7.5 WebGate Cookie Cannot Be Refreshed During Authorization ............................... 17-24
18 Configuring Multi-Data Centers
18.1 Before Setting Up a Multi-Data Center................................................................................. 18-1
18.2 Understanding the Primary Use Cases................................................................................. 18-2
18.3 Setting Up a Multi-Data Center ............................................................................................. 18-2
18.3.1 Enabling the Master Data Center ................................................................................... 18-3
18.3.2 Setting Up the Clone Data Center .................................................................................. 18-5
18.4 Adding A Second Clone to An Existing Multi-Data Center Setup................................... 18-7
18.5 Understanding Multi-Data Center Security Modes............................................................ 18-7
18.5.1 OPEN Security Mode ....................................................................................................... 18-8
18.5.2 SIMPLE Security Mode.................................................................................................... 18-8
18.5.3 CERT Security Mode ........................................................................................................ 18-9
18.6 WLST Commands for Multi-Data Centers......................................................................... 18-10
18.6.1 enableMultiDataCentreMode ....................................................................................... 18-11
18.6.2 disableMultiDataCentreMode ...................................................................................... 18-12
18.6.3 addPartnerForMultiDataCentre ................................................................................... 18-13
18.6.4 removePartnerForMultiDataCentre............................................................................. 18-14
18.6.5 setMultiDataCenterType ............................................................................................... 18-15
xii
18.6.6 setMultiDataCenterWrite .............................................................................................. 18-15
18.6.7 setMultiDataCentreClusterName ................................................................................ 18-16
18.6.8 validateMDCConfig ....................................................................................................... 18-16
18.6.9 exportAccessStore........................................................................................................... 18-16
18.6.10 importAccessStore .......................................................................................................... 18-17
19 Synchronizing Data In A Multi-Data Center
19.1 Understanding the Multi-Data Center Sync ........................................................................ 19-1
19.1.1 How Replication Works................................................................................................... 19-2
19.1.2 Understanding the Replication Agreement ................................................................. 19-3
19.1.3 Manually Syncing Data in a Multi-Data Center........................................................... 19-4
19.2 Enabling Data Replication ...................................................................................................... 19-4
19.3 Syncing Master and Clone Metadata .................................................................................... 19-5
19.3.1 Syncing the UDM Metadata............................................................................................ 19-5
19.3.2 Creating the Replication Agreement ............................................................................. 19-5
19.3.3 Modifying the Replication Agreement.......................................................................... 19-8
19.4 Using and Customizing Transformation Rules................................................................... 19-9
19.5 Modifying a Rule Document................................................................................................ 19-11
19.6 Using REST API for Replication Agreements.................................................................... 19-13
19.6.1 Querying for Replication Agreement Details............................................................. 19-13
19.6.2 Modifying an Existing Replication Agreement.......................................................... 19-13
19.6.3 Deleting a Replication Agreement ............................................................................... 19-14
19.7 Replicating Domains in Identity Manager Deployments ................................................ 19-14
19.8 Best Practices for Replication ............................................................................................... 19-15
19.8.1 Enabling Replication Logs............................................................................................. 19-15
19.8.2 Changing the User Identifier ........................................................................................ 19-15
20 Setting Up the Multi-Data Center: A Sequence
20.1 Before You Begin...................................................................................................................... 20-1
20.2 Setting Up a Multi-Data Center ............................................................................................. 20-2
20.3 Enabling Automated Policy Synchronization ..................................................................... 20-9
20.4 Troubleshooting the Multi-Data Center Setup.................................................................. 20-11
Part VI Managing Access Manager SSO, Policies, and Testing
21 Understanding Single Sign-On with Access Manager
21.1 Introducing Access Manager Single Sign-On ..................................................................... 21-1
21.1.1 About Multiple Network Domain SSO ......................................................................... 21-4
21.1.2 About Application SSO and Access Manager .............................................................. 21-4
21.1.3 About Multiple WebLogic Server Domain SSO........................................................... 21-5
21.1.4 About Reverse-Proxy SSO............................................................................................... 21-6
21.2 Understanding the Access Manager Policy Model............................................................. 21-7
21.3 Anatomy of an Application Domain and Policies ............................................................ 21-10
21.3.1 About Resource Definitions for Policies...................................................................... 21-11
21.3.2 About Authentication Policies ..................................................................................... 21-11
21.3.3 About Authorization Policies........................................................................................ 21-12
xiii
21.3.4 About Token Issuance Policies ..................................................................................... 21-13
21.4 Introduction to Policy Conditions and Rules .................................................................... 21-13
21.5 Understanding SSO Cookies ................................................................................................ 21-14
21.5.1 About Single Sign-On Cookies During User Login................................................... 21-14
21.5.2 About Single Sign-On Server and Agent Cookies ..................................................... 21-15
21.6 Introduction to Configuration Tasks for Single Sign-On................................................. 21-20
22 Managing Authentication and Shared Policy Components
22.1 Prerequisites ............................................................................................................................. 22-1
22.2 Understanding Authentication and Shared Policy Component Tasks ........................... 22-1
22.3 Managing Resource Types...................................................................................................... 22-2
22.3.1 About Resource Types and Their Use ........................................................................... 22-2
22.3.2 About the Resource Type Page....................................................................................... 22-4
22.3.3 Searching for a Specific Resource Type......................................................................... 22-6
22.3.4 Creating a Custom Resource Type................................................................................. 22-7
22.4 Managing Host Identifiers...................................................................................................... 22-7
22.4.1 About Host Identifiers ..................................................................................................... 22-8
22.4.2 About Virtual Web Hosting ......................................................................................... 22-10
22.4.3 About the Host Identifier Page..................................................................................... 22-14
22.4.4 Creating a Host Identifier.............................................................................................. 22-15
22.4.5 Searching for a Host Identifier Definition................................................................... 22-16
22.4.6 Viewing or Editing a Host Identifier Definition ........................................................ 22-16
22.4.7 Deleting a Host Identifier Definition ........................................................................... 22-17
22.5 Understanding Authentication Methods and Credential Collectors ............................. 22-18
22.5.1 About Different Authentication Methods................................................................... 22-18
22.5.2 Comparing Embedded Credential Collector with Detached Credential Collector ...........
22-19
22.5.3 Authentication Event Logging and Auditing ............................................................ 22-23
22.6 Managing Native Authentication Modules ....................................................................... 22-23
22.6.1 About Native Access Manager Authentication Modules ........................................ 22-24
22.6.2 Viewing or Editing Native Authentication Modules ................................................ 22-28
22.6.3 Deleting a Native Authentication Module.................................................................. 22-29
22.7 Orchestrating Multi-Step Authentication with Plug-in Based Modules ...................... 22-29
22.7.1 Comparing Simple Form and Multi-Factor (Multi-Step) Authentication .............. 22-30
22.7.2 About Plug-ins for Multi-Step Authentication Modules ......................................... 22-31
22.7.3 About Plug-in Based Modules for Multi-Step Authentication ................................ 22-39
22.7.4 Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple
OCSP Endpoints 22-46
22.7.5 Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules . 22-48
22.7.6 Creating and Managing Step-Up Authentication ..................................................... 22-50
22.7.7 Configuring an HTTPToken Extractor Plug-in .......................................................... 22-56
22.7.8 Configuring a JSON Web Token Plug-in .................................................................... 22-56
22.8 Deploying and Managing Individual Plug-ins for Authentication................................ 22-58
22.8.1 About Managing Your Own Authentication Plug-ins .............................................. 22-59
22.8.2 Making Custom Authentication Plug-ins Available for Use ................................... 22-62
22.8.3 Checking an Authentication Plug-in's Activation Status.......................................... 22-63
22.8.4 Deleting Your Custom Authentication Plug-ins........................................................ 22-64
xiv
22.9 Managing Authentication Schemes..................................................................................... 22-64
22.9.1 About Authentication Schemes and Pages ................................................................. 22-65
22.9.2 Understanding Multi-Level and Step-Up Authentication........................................ 22-79
22.9.3 Creating an Authentication Scheme ............................................................................ 22-82
22.9.4 Searching for an Authentication Scheme .................................................................... 22-83
22.9.5 Viewing, Editing, or Deleting an Authentication Scheme........................................ 22-83
22.10 Extending Authentication Schemes with Advanced Rules ............................................. 22-84
22.10.1 Using Advanced Rules................................................................................................... 22-85
22.10.2 Using Context Data for Advanced Rules .................................................................... 22-86
22.11 Configuring Challenge Parameters for Encrypted Cookies ............................................ 22-88
22.11.1 About Challenge Parameters for Encrypted Cookies................................................ 22-88
22.11.2 Configuring Challenge Parameters for Security of Encrypted Cookies................. 22-89
22.11.3 Setting Challenge Parameters for Persistence of Encrypted Cookies ..................... 22-89
22.12 Configuring Authentication POST Data Handling........................................................... 22-90
22.12.1 About Authentication Post Data Preservation and Restoration .............................. 22-90
22.12.2 About Configuring Authentication POST Data Handling ....................................... 22-91
22.12.3 About Post Data Size Limits.......................................................................................... 22-93
22.12.4 Configuring Authentication POST Data Handling ................................................... 22-94
22.12.5 Testing POST Data Handling Configuration.............................................................. 22-95
22.13 Long URL Handling During Authentication..................................................................... 22-95
22.13.1 About Long URLs and Authentication Handling...................................................... 22-95
22.13.2 About Configuring Long URL Handling.................................................................... 22-96
22.14 Using Application Initiated Authentication ...................................................................... 22-97
23 Understanding Credential Collection and Login
23.1 Logging In with Access Manager Credential Collection ................................................... 23-1
23.1.1 Login with Self-Service Provisioning Applications..................................................... 23-2
23.1.2 Login Processing with Access Manager-Protected Resources................................... 23-2
23.2 Processing SSO Login with OAM Agents and ECC ........................................................... 23-3
23.3 Processing SSO Login with OAM Agents and DCC .......................................................... 23-5
23.4 Processing SSO Login with OSSO Agents (mod_osso) and ECC ..................................... 23-9
23.5 Configuring 11g WebGates and Authentication Policy for DCC ................................... 23-10
23.5.1 Enabling DCC Credential Operations ......................................................................... 23-11
23.5.2 Locating and Updating DCC Forms for Password Policy ....................................... 23-12
23.5.3 Adding PasswordPolicyValidationScheme to Authentication Policy for DCC .... 23-12
23.5.4 Supporting Federation Flows With DCC.................................................................... 23-14
23.6 Tunneling from DCC to Access Manager Over Oracle Access Protocol ....................... 23-14
23.6.1 How DCC Tunneling with OAP Works...................................................................... 23-15
23.6.2 Configuring OAP Tunneling......................................................................................... 23-15
23.7 Configuring a DCC WebGate for X509 Authentication ................................................... 23-16
23.7.1 Configuring the WebLogic Server................................................................................ 23-16
23.7.2 Configuring a WebGate For DCC ................................................................................ 23-19
23.7.3 Converting the DCC WebGate to SSL ......................................................................... 23-20
24 Using Password Policy
24.1 Using Password Management ............................................................................................... 24-1
24.2 Enabling Password Management.......................................................................................... 24-2
xv
24.3 Configuring Password Policy ................................................................................................ 24-3
24.4 Specifying Credential Collector URLs with Password Policy........................................... 24-5
24.5 Using the Oracle-Provided Password Forms....................................................................... 24-8
24.6 Managing Global Password Policy ..................................................................................... 24-10
24.6.1 Defining Your Global Password Policy....................................................................... 24-11
24.6.2 Designating the Default Store for Your Password Policy......................................... 24-12
24.6.3 Adding Key Password Attributes to the Default Store............................................. 24-13
24.6.4 Adding an Administrator to Change User Attributes After a Password Change 24-15
24.7 Configuring Password Policy Authentication .................................................................. 24-15
24.7.1 Configuring the Password Policy Validation Authentication Module .................. 24-15
24.7.2 Configuring the PasswordPolicyValidationScheme ................................................ 24-19
24.7.3 Adding Your PasswordPolicyValidationScheme to ECC Authentication Policy . 24-20
24.8 Completing Password Policy Configuration ..................................................................... 24-21
24.8.1 Setting the Error Message Mode for Password Policy Messages ............................ 24-21
24.8.2 Overriding Native LDAP Password Policy Validation............................................. 24-21
24.8.3 Disabling ECC Operation and Using DCC Exclusively............................................ 24-22
24.8.4 Testing Your Multi-Step Authentication..................................................................... 24-23
24.9 Configuring the IPFUserPasswordPolicyPlugin............................................................... 24-24
24.9.1 Enabling the IPF Password Service.............................................................................. 24-24
24.9.2 Configuring Password Policy for IPF Password Service.......................................... 24-25
24.9.3 Extending the LDAP Definitions.................................................................................. 24-25
24.9.4 Configuring the Password Policy Validation Authentication Module and Scheme .........
24-26
24.9.5 Setting Up the Forgot Password Module.................................................................... 24-26
25 Managing Policies to Protect Resources and Enable SSO
25.1 Prerequisites ............................................................................................................................. 25-1
25.2 Introduction to Application Domain and Policy Creation ................................................ 25-2
25.2.1 Generating Application Domains and Policies Automatically.................................. 25-3
25.2.2 Managing Application Domains and Policies Remotely ............................................ 25-3
25.2.3 Creating or Managing an Application Domain and Policies ..................................... 25-3
25.3 Understanding Application Domain and Policy Management ........................................ 25-4
25.3.1 Navigating the Application Domain Pages .................................................................. 25-5
25.3.2 Displaying the Application Domain Summary Page .................................................. 25-5
25.3.3 Displaying the Resource Container in an Application Domain ................................ 25-6
25.3.4 Displaying Authentication Policy Pages ....................................................................... 25-7
25.3.5 Displaying Authorization Policy Pages......................................................................... 25-8
25.3.6 Displaying Token Issuance Policy Pages .................................................................... 25-10
25.4 Managing Application Domains Using the Console........................................................ 25-10
25.4.1 Creating a New Application Domain .......................................................................... 25-11
25.4.2 Searching for an Existing Application Domain.......................................................... 25-12
25.4.3 Viewing or Editing an Application Domain............................................................... 25-12
25.4.4 Deleting an Application Domain and Its Contents ................................................... 25-13
25.5 Adding and Managing Policy Resource Definitions ........................................................ 25-13
25.5.1 Defining Resources in an Application Domain.......................................................... 25-14
25.5.2 Defining Resources in an Application Domain.......................................................... 25-27
25.5.3 Searching for a Resource Definition............................................................................. 25-28
xvi
25.5.4 Viewing, Editing, or Deleting a Resource Definition ............................................... 25-30
25.6 Defining Authentication Policies for Specific Resources ................................................. 25-31
25.6.1 About the Authentication Policy Page ........................................................................ 25-31
25.6.2 Creating an Authentication Policy for Specific Resources ....................................... 25-33
25.6.3 Searching for an Authentication Policy....................................................................... 25-34
25.6.4 Viewing or Editing an Authentication Policy............................................................. 25-34
25.6.5 Deleting an Authentication Policy ............................................................................... 25-35
25.7 Defining Authorization Policies for Specific Resources................................................... 25-35
25.7.1 About Authorization Policies for Specific Resources................................................ 25-36
25.7.2 Creating an Authorization Policy and Specific Resources ....................................... 25-37
25.7.3 Searching for an Authorization Policy ....................................................................... 25-37
25.7.4 Viewing or Editing an Authorization Policy and Resources ................................... 25-38
25.7.5 Deleting an Entire Authorization Policy .................................................................... 25-38
25.8 Configuring Success and Failure URLs for Authorization Policies................................ 25-39
25.9 Introduction to Authorization Policy Rules and Conditions .......................................... 25-40
25.9.1 About Allow or Deny Rules.......................................................................................... 25-40
25.9.2 About Authorization Policy Conditions .................................................................... 25-41
25.9.3 About Classifying Users and Groups for Conditions ............................................... 25-42
25.9.4 Guidelines for Authorization Responses Based on Conditions............................... 25-43
25.10 Defining Authorization Policy Conditions ........................................................................ 25-43
25.10.1 Choosing a Condition Type .......................................................................................... 25-44
25.10.2 Defining Identity Conditions........................................................................................ 25-45
25.10.3 Defining IP4 Range Conditions .................................................................................... 25-51
25.10.4 Defining Temporal Conditions..................................................................................... 25-54
25.10.5 Defining Attribute Conditions...................................................................................... 25-55
25.10.6 Viewing, Editing, or Deleting Authorization Policy Conditions............................. 25-59
25.11 Defining Authorization Policy Rules .................................................................................. 25-60
25.11.1 About Defining Rules in an Authorization Policy..................................................... 25-60
25.11.2 About Expressions and Expression-Based Policy Evaluation.................................. 25-63
25.11.3 Defining Rules in an Authorization Policy................................................................. 25-66
25.12 Configuring Policy Ordering ............................................................................................... 25-67
25.13 Introduction to Policy Responses for SSO.......................................................................... 25-68
25.13.1 About Authentication and Authorization Policy Responses for SSO..................... 25-68
25.13.2 About the Policy Response Language ......................................................................... 25-70
25.13.3 About the Namespace and Variable Names for Policy Responses ......................... 25-70
25.13.4 About Constructing a Policy Response for SSO......................................................... 25-72
25.13.5 About Policy Response Processing .............................................................................. 25-74
25.13.6 About Assertion Claims and Processing..................................................................... 25-75
25.14 Adding and Managing Policy Responses for SSO ............................................................ 25-75
25.14.1 Adding a Policy Response for SSO .............................................................................. 25-75
25.14.2 Viewing, Editing, or Deleting a Policy Response for SSO ........................................ 25-76
25.15 Validating Authentication and Authorization in an Application Domain ................... 25-76
25.16 Understanding Remote Policy and Application Domain Management........................ 25-77
25.16.1 About Managing Policies Remotely............................................................................. 25-78
25.16.2 About the Create Policy Request Template ................................................................ 25-79
25.16.3 About the Update Policy Request Template............................................................... 25-80
25.16.4 About Remote Policy Management and Templates .................................................. 25-80
xvii
25.17 Managing Policies and Application Domains Remotely ................................................. 25-82
25.18 Defining an Application........................................................................................................ 25-82
26 Validating Connectivity and Policies Using the Access Tester
26.1 Prerequisites ............................................................................................................................. 26-1
26.2 Introduction to the Access Tester for Access Manager 11g .............................................. 26-1
26.2.1 About OAM Agent and Server Interoperability .......................................................... 26-3
26.2.2 About Access Tester Security and Processing .............................................................. 26-5
26.2.3 About Access Tester Modes and Administrator Interactions ................................... 26-6
26.3 Installing and Starting the Access Tester.............................................................................. 26-8
26.3.1 Installing the Access Tester ............................................................................................. 26-8
26.3.2 About Access Tester Supported System Properties..................................................... 26-9
26.3.3 Starting the Tester Without System Properties For Use in Tester Console Mode. 26-10
26.3.4 Starting the Access Tester with System Properties For Use in Command Line Mode......
26-11
26.4 Introduction to the Access Tester Console and Navigation ............................................ 26-12
26.4.1 Access Tester Menus and Command Buttons............................................................ 26-14
26.5 Testing Connectivity and Policies from the Access Tester Console ............................... 26-15
26.5.1 Establishing a Connection Between the Access Tester and the OAM Server........ 26-16
26.5.2 Validating Resource Protection from the Access Tester Console............................ 26-18
26.5.3 Testing User Authentication from the Access Tester Console................................. 26-20
26.5.4 Testing User Authorization from the Access Tester Console .................................. 26-23
26.5.5 Observing Request Latency........................................................................................... 26-24
26.6 Creating and Managing Test Cases and Scripts................................................................ 26-24
26.6.1 About Test Cases and Test Scripts ............................................................................... 26-25
26.6.2 Capturing Test Cases ..................................................................................................... 26-25
26.6.3 Generating an Input Test Script.................................................................................... 26-26
26.6.4 Personalizing an Input Test Script ............................................................................... 26-27
26.6.5 Executing a Test Script .................................................................................................. 26-28
26.7 Evaluating Scripts, Log File, and Statistics ........................................................................ 26-31
26.7.1 About Evaluating Test Results...................................................................................... 26-31
26.7.2 About the Saved Connection Configuration File....................................................... 26-32
26.7.3 About the Generated Input Test Script ....................................................................... 26-33
26.7.4 About the Target Output File Containing Test Run Results .................................... 26-34
26.7.5 About the Statistics Document ..................................................................................... 26-36
26.7.6 About the Execution Log ............................................................................................... 26-38
27 Configuring Centralized Logout for Sessions Involving 11g WebGates
27.1 Prerequisites ............................................................................................................................. 27-1
27.2 Introduction to Centralized Logout for Access Manager 11g ........................................... 27-1
27.2.1 About Centralized Logout for 11g WebGates ............................................................. 27-2
27.2.2 About Logout Parameters for 11g WebGates............................................................... 27-2
27.3 Configuring Centralized Logout for 11g WebGates........................................................... 27-4
27.3.1 Configuring Centralized Logout for 11g WebGates When the ECC is Used .......... 27-5
27.3.2 Configuring Logout When Using Detached Credential Collector-Enabled WebGate......
27-6
xviii
27.4 Validating Global Sign-On and Centralized Logout ......................................................... 27-6
27.4.1 Confirming Global Sign-On ............................................................................................ 27-6
27.4.2 Validating Global Sign-On with Mixed Agent Types ................................................. 27-7
27.4.3 Observing Centralized Logout ....................................................................................... 27-8
Part VII Registering and Using Agents with Access Manager
28 Registering and Managing Legacy OpenSSO Agents
28.1 Introduction to OpenSSO, Agents, Migration and Co-existence ...................................... 28-1
28.1.1 About Migration and Co-existence Between OpenSSO and Access Manager ..... 28-2
28.1.2 About OpenSSO Agent Reliance on Access Manager................................................. 28-4
28.2 Runtime Processing Between OpenSSO Agents and Access Manager............................ 28-6
28.3 Understanding OpenSSO Agent Registration Parameters .............................................. 28-10
28.3.1 About OpenSSO Agent Registration Parameters....................................................... 28-10
28.3.2 About the Expanded OpenSSO Agent Page and Parameters .................................. 28-12
28.4 Registering and Managing OpenSSO Agents Using the Console ................................. 28-19
28.4.1 Registering an OpenSSO Agent using the Oracle Access Management Console . 28-20
28.4.2 Configuring and Managing Registered OpenSSO Agents Using the Console...... 28-21
28.5 Performing Remote Registration for OpenSSO Agents ................................................... 28-22
28.5.1 Understanding Request Templates for OpenSSO Agent Remote Registration..... 28-22
28.5.2 Reviewing OpenSSO Bootstrap Configuration Mappings....................................... 28-24
28.5.3 Performing In-Band Remote Registration with OpenSSO Agents.......................... 28-25
28.5.4 Performing Out-of-Band Remote Registration with OpenSSO Agents.................. 28-26
28.6 Updating Registered OpenSSO Agents Remotely ............................................................ 28-27
28.6.1 Updating OpenSSO Agents Remotely......................................................................... 28-28
28.7 Locating Other OpenSSO Agent Information ................................................................... 28-28
29 Registering and Managing Legacy OSSO Agents
29.1 Understanding OSSO Agents with Access Manager.......................................................... 29-1
29.1.1 About OSSO Agents with Access Manager .................................................................. 29-1
29.1.2 Comparing Access Manager 11g SSO versus OSSO 10g ............................................ 29-2
29.2 Registering OSSO Agents Using Oracle Access Management Console........................... 29-6
29.2.1 Understanding the Create OSSO Agent Registration Page and Parameters ........... 29-6
29.2.2 Registering an OSSO Agent (mod_osso) Using the Console ..................................... 29-8
29.3 Configuring and Managing Registered OSSO Agents Using the Console...................... 29-9
29.3.1 Understanding the Expanded OSSO Agent Page in the Console.............................. 29-9
29.3.2 Searching for an OSSO Agent (mod_osso) Registration .......................................... 29-10
29.3.3 Viewing or Editing OSSO Agent (mod_osso) Registration...................................... 29-11
29.3.4 Deleting an OSSO Agent (mod_osso) Registration ................................................... 29-11
29.4 Performing Remote Registration for OSSO Agents.......................................................... 29-12
29.4.1 Understanding Request Templates for OSSO Remote Registration ....................... 29-12
29.4.2 Performing In-Band Remote Registration of OSSO Agents ..................................... 29-13
29.4.3 Performing Out-of-Band Remote Registration for OSSO Agents............................ 29-14
29.5 Updating Registered OSSO Agents Remotely................................................................... 29-15
29.6 Configuring Logout for OSSO Agents with Access Manager 11.1.2.............................. 29-16
29.6.1 About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager..........
29-17
xix
29.6.2 Removing Custom mod_osso Cookies on Logout..................................................... 29-17
29.7 Locating Other OSSO Agent Information .......................................................................... 29-18
30 Registering and Managing 10g WebGates with Access Manager 11g
30.1 Prerequisites ............................................................................................................................. 30-1
30.2 Introduction to 10g OAM Agents for Access Manager 11g............................................... 30-2
30.2.1 About IAMSuiteAgent: A Pre-Configured 10g WebGate Registered with Access
Manager 30-2
30.2.2 About Legacy Oracle Access Manager 10g Deployments and WebGates ............... 30-2
30.2.3 About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2 ............ 30-3
30.2.4 About Centralized Logout with 10g OAM Agents and 11g OAM Servers.............. 30-4
30.3 Comparing Access Manager 11.1.2 and 10g ........................................................................ 30-5
30.3.1 Comparing Access Manager 11g versus 10g ................................................................ 30-5
30.3.2 Comparing Access Manager 11g versus 10g Policy Model........................................ 30-7
30.4 Configuring Centralized Logout for IAMSuiteAgent ...................................................... 30-10
30.5 Registering a 10g WebGate with Access Manager 11g Remotely................................... 30-11
30.6 Managing 10g OAM Agents Remotely............................................................................... 30-13
30.7 Locating and Installing the Latest 10g WebGate for Access Manager 11g.................... 30-14
30.7.1 Preparing for a Fresh 10g WebGate Installation with Access Manager 11g .......... 30-14
30.7.2 Locating and Downloading 10g WebGates for Use with Access Manager 11g .... 30-16
30.7.3 Starting WebGate 10g Installation................................................................................ 30-17
30.7.4 Specifying a Transport Security Mode ........................................................................ 30-18
30.7.5 Requesting or Installing Certificates for Secure Communications.......................... 30-18
30.7.6 Specifying WebGate Configuration Details................................................................ 30-19
30.7.7 Updating the WebGate Web Server Configuration................................................... 30-19
30.7.8 Finishing WebGate Installation .................................................................................... 30-21
30.7.9 Installing Artifacts and Certificates ............................................................................. 30-21
30.7.10 Confirming WebGate Installation ................................................................................ 30-22
30.8 Configuring Centralized Logout for 10g WebGate with 11g OAM Servers ................. 30-22
30.8.1 About Centralized Logout Processing for 10g WebGate with 11g OAM Server .. 30-23
30.8.2 About the Centralized Logout Script for 10g WebGates with 11g OAM Servers. 30-24
30.8.3 Configuring Centralized Logout for 10g WebGates with Access Manager........... 30-26
30.9 Removing a 10g WebGate from the Access Manager 11g Deployment ........................ 30-27
31 Configuring Apache, OHS, IHS for 10g WebGates
31.1 Prerequisites ............................................................................................................................. 31-1
31.2 About Oracle HTTP Server and Access Manager ............................................................... 31-1
31.3 About Access Manager with Apache and IHS v2 Webgates............................................. 31-2
31.3.1 About the Apache HTTP Server..................................................................................... 31-3
31.3.2 About the IBM HTTP Server........................................................................................... 31-3
31.3.3 About the Apache and IBM HTTP Reverse Proxy Server .......................................... 31-3
31.4 About Apache v2 Architecture and Access Manager......................................................... 31-4
31.5 Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers ............................ 31-5
31.5.1 Requirements for IHS2 Web Servers.............................................................................. 31-6
31.5.2 Requirements for Apache and IHS v2 Reverse Proxy Servers................................... 31-6
31.5.3 Requirements for Apache v2 Web Servers.................................................................... 31-6
xx
31.6 Preparing Your Web Server.................................................................................................... 31-7
31.6.1 Preparing the IHS v2 Web Server .................................................................................. 31-8
31.6.2 Preparing Apache and Oracle HTTP Server Web Servers on Linux....................... 31-11
31.6.3 Preparing Oracle HTTP Server Web Servers on Linux and Windows Platforms. 31-11
31.6.4 Setting Oracle HTTP Server Client Certificates.......................................................... 31-12
31.6.5 Preparing the Apache v2 Web Server on UNIX......................................................... 31-12
31.6.6 Preparing the Apache v2 SSL Web Server on AIX..................................................... 31-16
31.6.7 Preparing the Apache v2 Web Server on Windows ................................................. 31-17
31.7 Activating Reverse Proxy for Apache v2 and IHS v2....................................................... 31-19
31.7.1 Activating Reverse Proxy For Apache v2 Web Servers ............................................ 31-19
31.7.2 Activating Reverse Proxy For IHS v2 Web Servers................................................... 31-20
31.8 Verifying httpd.conf Updates for Webgates...................................................................... 31-22
31.8.1 Verifying Webgate Details............................................................................................. 31-22
31.8.2 Verifying Language Encoding ...................................................................................... 31-24
31.9 Tuning Oracle HTTP Server Webgates for Access Manager........................................... 31-25
31.10 Tuning OHS /Apache Prefork and Worker MPM Modules for OAM.......................... 31-25
31.10.1 Tuning Oracle HTTP Server /Apache Prefork MPM Module................................. 31-26
31.10.2 Tuning Oracle HTTP Server /Apache Worker MPM Module ................................ 31-26
31.10.3 Tuning Kernel Parameters............................................................................................. 31-27
31.11 Starting and Stopping Oracle HTTP Server Web Servers................................................ 31-27
31.12 Tuning Apache/IHS v2 Webgates for Access Manager ................................................. 31-27
31.13 Removing Web Server Configuration Changes After Uninstall..................................... 31-30
31.14 Helpful Information ............................................................................................................. 31-30
32 Configuring the ISA Server for 10g WebGates
32.1 Prerequisites ............................................................................................................................. 32-1
32.2 About Access Manager and the ISA Server ........................................................................ 32-1
32.3 Compatibility and Platform Support ................................................................................... 32-2
32.4 Installing and Configuring Webgate for the ISA Server .................................................... 32-2
32.4.1 Installing Webgate with ISA Server............................................................................... 32-2
32.4.2 Changing /access Directory Permissions .................................................................... 32-3
32.5 Configuring the ISA Server for the ISAPI Webgate............................................................ 32-3
32.5.1 Registering Access Manager Plug-ins as ISA Server Web Filters.............................. 32-3
32.5.2 Configuring ISA Firewall Policies for ISA Web Filters ............................................... 32-4
32.5.3 Ordering the ISAPI Filters............................................................................................... 32-6
32.6 Starting, Stopping, and Restarting the ISA Server ............................................................. 32-7
32.7 Removing Access Manager Filters Before Webgate Uninstall on ISA Server................. 32-7
33 Configuring the IIS Web Server for 10g WebGates
33.1 Prerequisites ............................................................................................................................. 33-1
33.2 WebGate Guidelines for IIS Web Servers ............................................................................ 33-1
33.2.1 Guidelines for ISAPI WebGates .................................................................................... 33-2
33.3 Prerequisite for Installing Webgate for IIS 7........................................................................ 33-5
33.3.1 Prerequisite for Installing Any 10g Webgate for IIS 7................................................. 33-5
33.3.2 Prerequisite for Installing a 32-bit Webgate for IIS 7................................................... 33-6
33.4 Updating IIS 7 Web Server Configuration on Windows 2008........................................... 33-6
33.5 Completing Webgate Installation with IIS........................................................................... 33-7
xxi
33.5.1 Enabling Client Certificate Authentication on the IIS Web Server ........................... 33-7
33.5.2 Ordering the ISAPI Filters............................................................................................... 33-8
33.5.3 Enabling Pass-Through Functionality for POST Data................................................. 33-9
33.5.4 Protecting a Web Site When the Default Site is Not Setup....................................... 33-13
33.6 Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance ........... 33-14
33.6.1 Installing Each IIS 7 Webgate in a Multiple Webgate Scenario ............................... 33-14
33.6.2 Setting the Impersonation DLL for Multiple IIS 7 Webgates................................... 33-16
33.6.3 Enabling Client Certification for Multiple IIS 7 Webgates ....................................... 33-17
33.6.4 Configuring IIS 7 Webgates for Pass Through Functionality .................................. 33-18
33.6.5 Confirming IIS 7 Webgate Installation ........................................................................ 33-19
33.7 Installing and Configuring Multiple Webgates for a Single IIS 6 Instance ................... 33-19
33.7.1 Installing Each Webgate in a Multiple Webgate Scenario........................................ 33-20
33.7.2 Setting the Impersonation DLL for Multiple Webgates............................................ 33-22
33.7.3 Enabling SSL and Client Certification for Multiple Webgates................................. 33-23
33.7.4 Confirming Multiple Webgate Installation................................................................. 33-24
33.8 Finishing 64-bit Webgate Installation ................................................................................ 33-24
33.8.1 Setting Access Permissions, ISAPI filters, and Directory Security Authentication ...........
33-25
33.8.2 Setting Client Certificate Authentication .................................................................... 33-25
33.9 Confirming Webgate Installation on IIS ............................................................................. 33-26
33.10 Starting, Stopping, and Restarting the IIS Web Server..................................................... 33-27
33.11 Removing Web Server Configuration Changes Before Uninstall................................... 33-27
34 Configuring Lotus Domino Web Servers for 10g WebGates
34.1 Prerequisites ............................................................................................................................. 34-1
34.2 Installing the Domino Web Server ........................................................................................ 34-1
34.3 Setting Up the First Domino Web Server ............................................................................. 34-2
34.4 Starting the Domino Web Server........................................................................................... 34-3
34.5 Enabling SSL (Optional).......................................................................................................... 34-3
34.6 Installing a Domino Security (DSAPI) Filter ....................................................................... 34-4
34.6.1 Completing the WebGate Installation .......................................................................... 34-5
Part VIII Managing the Adaptive Authentication Service and Oracle Mobile
Authenticator
35 Introducing the Adaptive Authentication Service
35.1 Using the Adaptive Authentication Service ........................................................................ 35-1
35.2 Working with the Adaptive Authentication Service .......................................................... 35-2
35.2.1 Understanding the One Time Password Option.......................................................... 35-3
35.2.2 Understanding the Access Request (Push) Notification Option ............................... 35-4
35.2.3 Using the Oracle Mobile Authenticator with OTP And Access Request ................. 35-6
35.3 Understanding Adaptive Authentication Service and OMA Configurations ................ 35-6
35.4 Configuring the Adaptive Authentication Service ............................................................. 35-6
35.4.1 Generating a Secret Key for the Oracle Mobile Authenticator .................................. 35-7
35.4.2 Configuring Mobile OAuth Services to Protect the Secret Key ................................. 35-7
35.4.3 Configuring the Adaptive Authentication Plug-in...................................................... 35-7
xxii
35.4.4 Setting Credentials for UMS, iOS and Android ........................................................... 35-9
35.4.5 Creating a Java KeyStore for iOS Access Request (Push) Notifications ................. 35-10
35.4.6 Configuring Host Name Verifier for Android Access Request (Push) Notifications........
35-11
35.4.7 Configuring Access Manager for VPN Use Case ...................................................... 35-11
36 Configuring the Oracle Mobile Authenticator
36.1 Understanding Oracle Mobile Authenticator Configuration............................................ 36-1
36.2 Using the Oracle Mobile Authenticator App on iOS.......................................................... 36-3
36.2.1 Configuring the Oracle Mobile Authenticator for iOS................................................ 36-3
36.2.2 Initializing the Oracle Mobile Authenticator on iOS................................................... 36-4
36.2.3 Copying a One-Time Password from the Oracle Mobile Authenticator on iOS ..... 36-6
36.2.4 Editing an Account on the Oracle Mobile Authenticator on iOS .............................. 36-6
36.2.5 Deleting an Account on the Oracle Mobile Authenticator on iOS ............................ 36-6
36.2.6 Responding to Access Request (Push) Notifications on iOS...................................... 36-6
36.2.7 Displaying Access Request (Push) Notifications History on iOS.............................. 36-7
36.2.8 Displaying Service Account Details on iOS.................................................................. 36-7
36.2.9 Displaying Access Manager Registered Accounts on iOS.......................................... 36-7
36.2.10 Displaying the OMA Version on iOS............................................................................. 36-7
36.3 Using the Oracle Mobile Authenticator App on Android................................................. 36-7
36.3.1 Configuring the Oracle Mobile Authenticator for Android....................................... 36-8
36.3.2 Initializing the Oracle Mobile Authenticator on Android.......................................... 36-8
36.3.3 Copying a One-Time Password from the Oracle Mobile Authenticator on Android .......
36-10
36.3.4 Editing an Account on the Oracle Mobile Authenticator on Android ................... 36-10
36.3.5 Deleting an Account on the Oracle Mobile Authenticator on Android ................. 36-10
36.3.6 Responding to Access Request (Push) Notifications on Android........................... 36-11
36.3.7 Displaying Access Request (Push) Notifications History on Android................... 36-11
36.3.8 Displaying Service Account Details on Android....................................................... 36-11
36.3.9 Displaying Access Manager Registered Accounts on Android............................... 36-11
36.3.10 Displaying the OMA Version on Android.................................................................. 36-12
36.4 Configuring the Google Authenticator App...................................................................... 36-12
36.5 Using a QR Code for Configuration.................................................................................... 36-12
Part IX Managing Oracle Access Management Identity Federation
37 Introducing Identity Federation in Oracle Access Management
37.1 Integrating Identity Federation with Access Manager....................................................... 37-1
37.2 Deploying Identity Federation with Oracle Access Management.................................... 37-2
37.3 Understanding How Identity Federation Works................................................................ 37-2
37.4 Using Identity Federation....................................................................................................... 37-3
37.4.1 Achieving SSO................................................................................................................... 37-4
37.4.2 Logging Out....................................................................................................................... 37-4
37.4.3 Authorizing ....................................................................................................................... 37-4
37.4.4 Forcing Authentication .................................................................................................... 37-4
37.4.5 Indicating a Passive Identity Provider .......................................................................... 37-5
37.4.6 User and Assertion Mapping ......................................................................................... 37-5
xxiii
37.4.7 Platform Dependencies.................................................................................................... 37-5
37.5 Initiating Federation SSO........................................................................................................ 37-5
37.5.1 IdP Initiated Federation SSO Service............................................................................. 37-5
37.5.2 SP Initiated Federation SSO Service............................................................................... 37-6
37.6 Exchanging Identity Federation Data ................................................................................... 37-6
37.6.1 Using SAML 2.0 ................................................................................................................ 37-6
37.6.2 Using SAML 1.1 ................................................................................................................ 37-9
37.6.3 Using OpenID 2.0............................................................................................................ 37-11
37.6.4 Using WS-Federation 1.1 ............................................................................................... 37-13
37.7 Administrating Identity Federation .................................................................................... 37-14
37.8 Enabling Identity Federation................................................................................................ 37-15
38 Managing Identity Federation Partners
38.1 Understanding Federation And Partners............................................................................. 38-1
38.2 Managing Federation Partners .............................................................................................. 38-1
38.3 Administering Identity Federation As A Service Provider ............................................... 38-2
38.3.1 Creating Remote Identity Provider Partners................................................................ 38-2
38.3.2 Managing the Remote Identity Provider Partners....................................................... 38-8
38.4 Administering Identity Federation As An Identity Provider.......................................... 38-10
38.4.1 Creating Remote Service Provider Partners ............................................................... 38-10
38.4.2 Managing the Remote Service Provider Partners...................................................... 38-11
38.5 Using Attribute Mapping Profiles....................................................................................... 38-12
38.5.1 Using the SP Attribute Mapping Profile ..................................................................... 38-12
38.5.2 Using the IdP Attribute Mapping Profile.................................................................... 38-14
38.6 Mapping Federation Authentication Methods to Access Manager Authentication Schemes.
38-15
38.6.1 Understanding Federation SSO As An IdP................................................................. 38-16
38.6.2 Understanding Federation SSO As An SP .................................................................. 38-17
38.6.3 Configuring an Alternate Authentication Scheme .................................................... 38-17
38.6.4 Using WLST For Mapping Administration ................................................................ 38-18
38.7 Using the Attribute Sharing Plug-in for the Attribute Query Service ........................... 38-18
38.7.1 Understanding the Plug-in and Query Service Design............................................. 38-18
38.7.2 Configuring for Attribute Sharing ............................................................................... 38-22
38.8 Using the Federation Proxy.................................................................................................. 38-24
38.9 Using WLST for Identity Federation Administration ...................................................... 38-25
39 Managing Settings for Identity Federation
39.1 Prerequisites ............................................................................................................................. 39-1
39.2 Introduction to Federation Settings....................................................................................... 39-1
39.3 Managing General Federation Settings ................................................................................ 39-2
39.3.1 About Managing General Federation Settings ............................................................. 39-2
39.3.2 Managing General Federation Settings ......................................................................... 39-3
39.4 Managing Proxy Settings for Federation.............................................................................. 39-3
39.4.1 About Proxy Settings for Federation ............................................................................ 39-3
39.4.2 Managing Proxy Settings for Identity Federation........................................................ 39-4
39.5 Defining Keystore Settings for Federation ........................................................................... 39-4
xxiv
39.5.1 About Managing Keytore Settings for Identity Federation ....................................... 39-4
39.5.2 Managing Identity Federation Encryption/Signing Keys.......................................... 39-5
39.6 Exporting Metadata ................................................................................................................. 39-7
40 Managing Federation Schemes and Policies
40.1 Using Identity Federation and Access Manager Together ................................................ 40-1
40.2 Using Authentication Schemes and Modules for Identity Federation 11g Release 2
(11.1.2.2) 40-2
40.2.1 About the FederationScheme Authentication Scheme................................................ 40-2
40.2.2 About the FederationMTScheme.................................................................................... 40-3
40.2.3 About the FederationPlugin Authentication Module ................................................. 40-3
40.2.4 Managing Authentication with Identity Federation in 11g Release 2 ...................... 40-4
40.3 Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1 .
40-6
40.3.1 About Scheme OIFScheme ............................................................................................. 40-7
40.3.2 About the OIFMTLDAPPlugin Authentication Module ............................................ 40-8
40.3.3 Managing Authentication with Oracle Identity Federation Release 11gR1............. 40-8
40.4 Managing Access Manager Policies for Use with Identity Federation ............................ 40-9
40.4.1 About Policy Responses with Assertion Attributes for Identity Federation ........... 40-9
40.4.2 Defining Policy Responses with Assertion Attributes for Identity Federation..... 40-10
40.5 Testing Identity Federation Configuration ........................................................................ 40-12
40.6 Using the Default Identity Provisioning Plug-in .............................................................. 40-14
40.6.1 Why Use a Provisioning Plug-in? ................................................................................ 40-14
40.6.2 About the Default Provisioning Plug-in...................................................................... 40-14
40.6.3 Using the Default Provisioning Plug-in ...................................................................... 40-14
40.6.4 Switching to a Custom Provisioning Plug-in ............................................................. 40-15
40.7 Configuring the Identity Provider Discovery Service...................................................... 40-15
40.7.1 Using the Bundled IdP Discovery Service .................................................................. 40-15
40.7.2 Creating a custom IdP Discovery Service ................................................................... 40-16
40.7.3 Disabling the use of an IdP Discovery Service........................................................... 40-18
40.8 Configuring the Federation User Self-Registration Module............................................ 40-18
40.9 Integrating OAM Identity Provider With Microsoft Office 365 Service Provider ....... 40-20
40.9.1 Configuring Microsoft Office 365 for OAM Integration........................................... 40-21
40.9.2 Configuring OAM for Microsoft Office 365 Integration ........................................... 40-22
40.9.3 Verifying Federation Single Sign-On........................................................................... 40-23
Part X Managing Oracle Access Management Security Token Service
41 Introducing the Oracle Access Management Security Token Service
41.1 Understanding the Security Token Service.......................................................................... 41-1
41.2 Using the Security Token Service ......................................................................................... 41-2
41.3 Security Token Service Key Terms and Concepts............................................................... 41-3
41.4 Integrating the Oracle Web Services Manager .................................................................... 41-6
41.5 Architecting the Security Token Service............................................................................... 41-8
41.6 Security Token Service Supported Token Matrix ............................................................... 41-8
41.7 Deploying Security Token Service ........................................................................................ 41-9
41.7.1 Centralized Token Authority Deployment................................................................... 41-9
xxv
41.7.2 Tokens Behind a Firewall Deployment ......................................................................... 41-9
41.7.3 Web Services SSO Deployment .................................................................................... 41-10
41.8 Installing Security Token Service ........................................................................................ 41-11
41.8.1 Security Token Service Cluster in Single WLS Domain............................................ 41-11
41.8.2 Endpoint Exposure through a Web Server Proxy...................................................... 41-11
41.8.3 Interoperability of Requester and Relying Party with Other Oracle WS-Trust based
Clients 41-12
41.8.4 Security Token Service Installation Overview ........................................................... 41-12
41.8.5 Post-Installation Tasks: Security Token Service ........................................................ 41-12
41.9 Administrating the Security Token Service ....................................................................... 41-12
42 Security Token Service Implementation Scenarios
42.1 Prerequisites ............................................................................................................................. 42-1
42.2 Typical Token Ecosystem ....................................................................................................... 42-1
42.3 Scenario: Identity Propagation with the Access Manager Token ..................................... 42-2
42.3.1 Component Processing: Identity Propagation with the OAM Token....................... 42-4
42.3.2 Request Security Token Attributes and Run Time Processing .................................. 42-5
42.3.3 Configuration Requirements: Identity Propagation with the OAM Token............. 42-7
42.3.4 Testing Your Implementation....................................................................................... 42-15
42.4 Scenario: Web Service Security With On Behalf Of Username Token .......................... 42-16
42.4.1 Component interactions for Identity Propagation with Username Token ............ 42-16
42.4.2 RST Attributes and Processing for Identity Propagation with a Username Token ...........
42-16
42.4.3 Configuration Requirements: Identity Propagation with the Username Token... 42-18
43 Configuring Security Token Service Settings
43.1 Prerequisites ............................................................................................................................ 43-1
43.2 Introduction to Security Token Service Configuration ...................................................... 43-1
43.2.1 Post-Installation Configuration ...................................................................................... 43-2
43.2.2 About OAM Servers and Security Token Service........................................................ 43-3
43.2.3 About Security Token Service Clients ........................................................................... 43-4
43.2.4 About Agents and Security Token Service ................................................................... 43-4
43.2.5 About Security Token Service End Points and Policies .............................................. 43-5
43.3 Enabling and Disabling Security Token Service ................................................................. 43-7
43.3.1 About Security Token Service and the Oracle Access Management Console ......... 43-8
43.3.2 About Enabling Services for Security Token Service ................................................. 43-9
43.3.3 Enabling and Disabling Services for Security Token Service..................................... 43-9
43.4 Defining Security Token Service Settings............................................................................. 43-9
43.4.1 About Security Token Service Settings.......................................................................... 43-9
43.4.2 Managing Security Token Service Settings................................................................. 43-12
43.5 Using and Managing WSS Policies for Oracle WSM Agents .......................................... 43-12
43.5.1 Using and Modifying Oracle Workspace Studio Policies......................................... 43-13
43.5.2 Managing WSS Policies for Security Token Service: Classpath............................... 43-13
43.5.3 Managing WSS Policies for Security Token Service: Oracle WSM Policy Manager..........
43-14
43.6 Configuring OWSM for WSS Protocol Communication.................................................. 43-15
43.6.1 About Oracle WSM Agent WS-Security Policies for Security Token Service........ 43-15
xxvi
43.6.2 Retrieving the Oracle WSM Keystore Password........................................................ 43-16
43.6.3 Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate ....... 43-16
43.6.4 Adding Trusted Certificates to the Oracle WSM Keystore....................................... 43-17
43.6.5 Validating Trusted Certificates in the Oracle WSM Keystore.................................. 43-17
43.6.6 Configuring Oracle WSM Agent for WSS Kerberos Policies ................................... 43-18
43.7 Managing and Migrating Security Token Service Policies .............................................. 43-19
43.7.1 About Managing and Migrating Security Token Service Policies........................... 43-19
43.7.2 Managing Security Token Service Policies ................................................................. 43-19
43.7.3 Migrating Security Token Service Policies.................................................................. 43-19
43.8 Logging Security Token Service Messages ........................................................................ 43-20
43.9 Auditing the Security Token Service ................................................................................. 43-21
43.9.1 About Security Token Service Audit Record Storage ............................................... 43-21
43.9.2 About Audit Reports and Oracle Business Intelligence Publisher.......................... 43-22
43.9.3 About the Audit Log ...................................................................................................... 43-22
43.9.4 About Auditing Security Token Service Events......................................................... 43-22
44 Managing Security Token Service Certificates and Keys
44.1 Prerequisites ............................................................................................................................. 44-1
44.2 Introducing the Security Token Service Certificates and Keys......................................... 44-1
44.2.1 About Keystores and Security Token Service............................................................... 44-2
44.2.2 About the Oracle Web Services Manager Keystore (default-keystore.jks) .............. 44-3
44.2.3 About Using the OPSS Keystore for Requester Certificates....................................... 44-3
44.3 Managing Security Token Service Encryption/Signing Keys........................................... 44-4
44.3.1 Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore)
Password 44-4
44.3.2 Adding a New Key Entry to the System Keystore (.oamkeystore) ........................... 44-5
44.3.3 Extracting an Security Token Service Certificate ......................................................... 44-6
44.4 Managing Partner Keys for WS-Trust Communications ................................................... 44-7
44.4.1 About Partner Certificates............................................................................................... 44-7
44.4.2 About Downloading the Relying Party's Certificate at Run Time ............................ 44-8
44.4.3 Setting the Partner's Signing or Encryption Certificate .............................................. 44-8
44.5 Managing Certificate Validation ........................................................................................... 44-9
44.5.1 Managing the Trust Anchors Store (amtruststore)...................................................... 44-9
44.5.2 Managing Certificate Revocation Lists........................................................................ 44-10
44.5.3 Using a Custom Trust Anchor Store for Security Token Service............................. 44-10
45 Managing Templates, Endpoints, and Policies
45.1 Introduction .............................................................................................................................. 45-1
45.2 Searching for an Existing Template....................................................................................... 45-2
45.2.1 About Template Search Controls .................................................................................. 45-3
45.2.2 Searching For a Template ................................................................................................ 45-4
45.3 Managing Token Issuance Templates................................................................................... 45-5
45.3.1 About Managing Token Issuance Templates ............................................................... 45-5
45.3.2 Managing a Token Issuance Template ........................................................................ 45-12
45.4 Managing Token Validation Templates ............................................................................. 45-13
45.4.1 About Managing Token Validation Templates.......................................................... 45-13
45.4.2 Managing Token Validation Templates ...................................................................... 45-23
xxvii
45.5 Managing Security Token Service Endpoints.................................................................... 45-25
45.5.1 About Managing Endpoints.......................................................................................... 45-25
45.5.2 Managing EndPoints...................................................................................................... 45-26
45.6 Managing Token Issuance Policies, Conditions, and Rules ............................................ 45-27
45.6.1 About Token Issuance Policies ..................................................................................... 45-27
45.6.2 About Managing Token Issuance Conditions and Rules ......................................... 45-27
45.6.3 Managing Token Issuance Policies and Conditions .................................................. 45-29
45.7 Managing TokenServiceRP Type Resources ..................................................................... 45-30
45.7.1 About Managing TokenServiceRP Type Resources in Access Manager................ 45-32
45.7.2 Managing TokenServiceRP Type Resources in Application Domains................... 45-32
45.8 Making Custom Classes Available...................................................................................... 45-33
45.8.1 About Making Classes Available ................................................................................. 45-33
45.8.2 About Narrowing a Search for Custom Tokens......................................................... 45-35
45.8.3 Managing Custom Tokens ........................................................................................... 45-37
45.9 Managing a Custom Security Token Service Configuration ........................................... 45-38
45.9.1 Creating the Validation Template ................................................................................ 45-38
45.9.2 Creating the Issuance Template for a Custom Token ............................................... 45-40
45.9.3 Adding the Custom Token to a Requester Profile..................................................... 45-42
45.9.4 Adding the Custom Token to the Relying Party Profile........................................... 45-42
45.9.5 Mapping the Token to a Requestor.............................................................................. 45-43
45.9.6 Creating an /wssuser EndPoint ................................................................................... 45-44
46 Managing Token Service Partners and Partner Profiles
46.1 Prerequisites ............................................................................................................................. 46-1
46.2 Introduction Token Service Partners and Partner Profiles ................................................ 46-1
46.2.1 About Token Service Partners ........................................................................................ 46-1
46.2.2 About Partner Profiles ..................................................................................................... 46-2
46.3 Managing Token Service Partners......................................................................................... 46-3
46.3.1 About Managing Token Service Partners ..................................................................... 46-3
46.3.2 Managing a Token Service Partner ................................................................................ 46-5
46.3.3 Refining Partner Searches ............................................................................................... 46-6
46.4 Managing Token Service Partner Profiles ............................................................................ 46-7
46.4.1 About Managing Partner Profiles .................................................................................. 46-7
46.4.2 Managing a Token Service Partner Profile.................................................................. 46-18
46.4.3 Refining a Profile Search................................................................................................ 46-19
47 Troubleshooting Security Token Service
47.1 Authorization Issues................................................................................................................ 47-1
47.2 Endpoint Issues ........................................................................................................................ 47-2
47.3 Mapping Operation Issues ..................................................................................................... 47-2
Part XI Managing Oracle Access Management Mobile and Social
48 Understanding Mobile and Social
48.1 Introducing Mobile and Social............................................................................................... 48-1
48.1.1 Installing Mobile and Social............................................................................................ 48-3
xxviii
48.1.2 Deploying Mobile and Social .......................................................................................... 48-4
48.1.3 Enabling Mobile and Social............................................................................................. 48-5
48.2 Understanding Mobile and Social Services.......................................................................... 48-5
48.2.1 Introducing Authentication Services and Authorization Services............................ 48-6
48.2.2 Understanding the Mobile and Social Services Authorization Flow........................ 48-7
48.2.3 Understanding Single Sign-on (SSO) for Mobile and Social Services....................... 48-7
48.2.4 Introducing the Mobile and Social Services Client SDK ............................................ 48-9
48.2.5 Introducing User Profile Services................................................................................... 48-9
48.3 Understanding the Mobile and Social Services Processes ............................................... 48-10
48.3.1 Registering a Mobile Device With User Authentication........................................... 48-10
48.3.2 Authenticating a User With a Registered Device....................................................... 48-13
48.3.3 Using REST Calls for User Authentication ................................................................. 48-15
48.3.4 Authenticating the User With a Mobile Browser-Based Web App......................... 48-16
48.3.5 Authorization Using the Mobile OAuth Authorization Flow ................................. 48-17
48.4 Using Mobile and Social Services........................................................................................ 48-19
48.4.1 Protecting the Mobile Client Registration Endpoint ................................................. 48-19
48.4.2 Exchanging Credentials ................................................................................................. 48-20
48.4.3 Protecting User Profile Services And Authorization Services ................................. 48-21
48.4.4 Using Mobile and Social Services with Oracle Access Manager ............................. 48-21
48.4.5 Using Mobile and Social Services with Oracle Adaptive Access Manager Services .........
48-22
48.5 Understanding Social Identity ............................................................................................. 48-22
48.6 Understanding Social Identity Processes ........................................................................... 48-23
48.6.1 Authenticating a Returning User With a Local Account .......................................... 48-24
48.6.2 Authenticating a New User With No Local Account................................................ 48-25
48.6.3 Using OAuth For Access Token Retrieval .................................................................. 48-27
48.6.4 Authenticating a User With Access Manager and Social Identity........................... 48-29
48.6.5 Authenticating a User Locally ...................................................................................... 48-31
48.7 Using Social Identity.............................................................................................................. 48-32
48.7.1 Using Social Identity With Oracle Access Manager .................................................. 48-32
48.7.2 Using Social Identity With Mobile and Social Services............................................. 48-32
48.7.3 Using the Social Identity SDK....................................................................................... 48-33
49 Configuring Mobile and Social Services
49.1 Opening the Mobile and Social Services Configuration Page........................................... 49-1
49.2 Understanding Mobile and Social Services Configuration................................................ 49-2
49.2.1 Understanding Service Providers .................................................................................. 49-2
49.2.2 Understanding Service Profiles ...................................................................................... 49-3
49.2.3 Understanding Security Handler Plug-ins ................................................................... 49-3
49.2.4 Understanding Application Profiles.............................................................................. 49-4
49.2.5 Understanding Service Domains.................................................................................... 49-4
49.3 Defining Service Providers..................................................................................................... 49-4
49.3.1 Defining, Modifying or Deleting an Authentication Service Provider..................... 49-5
49.3.2 Defining, Modifying or Deleting an Authorization Service Provider .................... 49-17
49.3.3 Defining, Modifying or Deleting a User Profile Service Provider........................... 49-18
49.4 Defining Service Profiles....................................................................................................... 49-22
49.4.1 Defining, Modifying and Deleting an Authentication Service Profile.................... 49-22
xxix
49.4.2 Defining, Modifying and Deleting an Authorization Service Profile ..................... 49-24
49.4.3 Defining, Modifying and Deleting a User Profile Service Profile ........................... 49-25
49.5 Defining Security Handler Plug-ins.................................................................................... 49-26
49.5.1 Creating a Security Handler Plug-in............................................................................ 49-27
49.5.2 Editing or Deleting a Security Handler Plug-in......................................................... 49-27
49.5.3 Device Fingerprinting and Device Profile Attributes................................................ 49-27
49.6 Defining Application Profiles .............................................................................................. 49-28
49.6.1 Creating an Application Profile.................................................................................... 49-28
49.6.2 Editing or Deleting an Application Profile ................................................................. 49-29
49.7 Defining Service Domains .................................................................................................... 49-30
49.7.1 Creating a Service Domain............................................................................................ 49-30
49.7.2 Editing or Deleting a Service Domain ......................................................................... 49-34
49.8 Using the Jailbreak Detection Policy................................................................................... 49-34
49.8.1 Adding a New Jailbreak Detection Policy .................................................................. 49-34
49.8.2 Editing the Jailbreak Detection Policy ......................................................................... 49-35
49.9 Configuring Mobile and Social Services with Other Oracle Products........................... 49-36
49.9.1 Configuring Mobile and Social Services for Access Manager.................................. 49-36
49.9.2 Configuring Mobile and Social Services for Oracle Adaptive Access Manager ... 49-41
50 Configuring Social Identity
50.1 Opening the Manage Social Identity Page ........................................................................... 50-1
50.2 Understanding Social Identity Configuration ..................................................................... 50-2
50.2.1 Understanding Social Identity Providers...................................................................... 50-2
50.2.2 Understanding Service Provider Interfaces.................................................................. 50-2
50.2.3 Understanding Application Profiles.............................................................................. 50-2
50.3 Defining Social Identity Providers ....................................................................................... 50-3
50.3.1 Creating a Social Identity Provider................................................................................ 50-3
50.3.2 Editing or Deleting a Social Identity Provider ............................................................. 50-7
50.3.3 Generating the Consumer Key and Consumer Secret for OAuth Providers........... 50-8
50.3.4 Troubleshooting Facebook Social Identity Providers................................................ 50-10
50.4 Defining Service Provider Interfaces .................................................................................. 50-11
50.4.1 Creating a Service Provider Interface .......................................................................... 50-12
50.4.2 Editing or Deleting an Service Provider Interface ..................................................... 50-12
50.4.3 Adding a Custom Service Provider Interface Implementation ............................... 50-12
50.5 Defining Application Profiles .............................................................................................. 50-13
50.5.1 Creating an Application Profile.................................................................................... 50-13
50.5.2 Editing or Deleting an Application Profile ................................................................. 50-16
50.6 Integrating Social Identity With Mobile Applications ..................................................... 50-16
50.7 Linking Social Identity Provider Accounts........................................................................ 50-17
50.7.1 Using Social Identity Provider Account Linking ....................................................... 50-18
50.7.2 Configuring Social Identity Provider Account Linking............................................ 50-19
51 Configuring Social Identity System Settings
51.1 Accessing the Social Identity Settings Interface .................................................................. 51-1
51.1.1 Understanding the Social Identity Settings Page ........................................................ 51-1
51.2 Logging and Auditing............................................................................................................. 51-2
xxx
51.3 Deploying Mobile and Social With Oracle Access Manager ............................................. 51-2
51.4 Configuring a Webgate to Support Social Identity............................................................. 51-4
51.5 Configuring Social Identity After Running Test-to-Production Scripts .......................... 51-6
51.6 Configuring Social Identity for High Availability (HA) .................................................... 51-7
51.7 Enabling the REST Client to Specify the Tenant Name...................................................... 51-7
Part XII Managing the Oracle Access Management OAuth Service
52 Understanding OAuth Services
52.1 Using Oracle Access Management OAuth Services ........................................................... 52-1
52.2 Understanding OAuth Services Authorization for Web Clients ...................................... 52-2
52.2.1 Understanding 3-Legged Authorization....................................................................... 52-3
52.2.2 Understanding 2-Legged Authorization....................................................................... 52-4
52.3 Understanding OAuth Services Authorization for Mobile Clients.................................. 52-5
52.4 Understanding the OAuth Services Components............................................................. 52-10
52.4.1 Understanding Identity Domains ................................................................................ 52-10
52.4.2 Understanding Service Profiles .................................................................................... 52-10
52.4.3 Understanding Clients................................................................................................... 52-11
52.4.4 Understanding Service Providers ................................................................................ 52-12
52.4.5 Understanding Resource Servers ................................................................................. 52-13
52.4.6 Understanding Plug-Ins ................................................................................................ 52-17
52.4.7 Understanding Server Settings..................................................................................... 52-18
52.4.8 Understanding Jailbreak Detection Policy.................................................................. 52-18
52.4.9 Understanding Token Life Cycle Management ......................................................... 52-18
52.5 Understanding OAuth Services Tokens ............................................................................. 52-18
52.5.1 Understanding OAuth Services Access Tokens......................................................... 52-19
52.5.2 Understanding OAuth Services Refresh Tokens ....................................................... 52-20
52.5.3 Understanding Mobile OAuth Services Client Tokens............................................. 52-20
52.6 Understanding the Authorization and Authentication Endpoints ................................ 52-20
52.7 Enforcing Access Control...................................................................................................... 52-21
52.8 Understanding Mobile OAuth Services Server-Side Single Sign-on.............................. 52-21
52.8.1 Understanding the Server-Side Single Sign-On Credential Collection Options .. 52-22
52.8.2 Understanding Server-Side SSO For Mobile OAuth Services 3-Legged Flows..... 52-22
52.8.3 Understanding Server-Side SSO For Mobile OAuth Services 2-Legged Flows..... 52-24
52.9 Understanding OAuth Services Plug-ins ........................................................................... 52-25
53 Configuring OAuth Services
53.1 Enabling OAuth Services........................................................................................................ 53-1
53.2 Configuring OAuth Services Components in an Identity Domain .................................. 53-2
53.3 Configuring OAuth Services Settings................................................................................... 53-3
53.3.1 Configuring Identity Domains ...................................................................................... 53-4
53.3.2 Configuring Service Profiles .......................................................................................... 53-6
53.3.3 Configuring Clients ........................................................................................................ 53-12
53.3.4 Configuring the Service Provider................................................................................. 53-18
53.3.5 Configuring Custom Resource Servers ....................................................................... 53-20
53.3.6 Configuring User Profile Services ............................................................................... 53-22
xxxi
53.3.7 Configuring Consent Management Services .............................................................. 53-25
53.3.8 Configuring Plug-Ins...................................................................................................... 53-27
53.3.9 Configuring Server Settings .......................................................................................... 53-28
53.3.10 Configuring the Jailbreak Detection Policy ................................................................ 53-29
53.3.11 Configuring Token Life Cycle Management .............................................................. 53-30
53.4 Configuring OAuth Services for Third-Party JWT Bearer Assertions ........................... 53-31
53.4.1 Understanding the Default Service Profile Keystore ................................................ 53-31
53.4.2 Creating a Non-Default Keystore for a Service Profile ............................................. 53-32
53.4.3 Configuring a Third-Party JWT Trust Issuer.............................................................. 53-36
53.5 Configuring a WebGate to Protect OAuth Services.......................................................... 53-37
53.6 Configuring OAM Session Synchronization...................................................................... 53-39
53.7 Configuring Mobile OAuth for SSO Servlet Authentication........................................... 53-40
53.7.1 Configuring OAM and Your App to use the Mobile SSO Servlet........................... 53-40
53.7.2 Configuring the MobileSSOServlet Authentication Scheme.................................... 53-41
53.8 Configuring the Mobile Security Manager Plug-in .......................................................... 53-43
Part XIII Managing Oracle Access Management Oracle Access Portal
54 Configuring the Access Portal Service
54.1 Prerequisites for Deploying the Access Portal Service....................................................... 54-1
54.2 Overview of the Access Portal Service Deployment Process ............................................ 54-2
54.3 Deploying the Access Portal Service..................................................................................... 54-3
54.3.1 Deploying the Java Cryptography Extension Policy Files.......................................... 54-4
54.3.2 Creating the Identity Store Configuration File............................................................. 54-4
54.3.3 Creating the Oracle Access Manager Configuration File ........................................... 54-7
54.3.4 Understanding the Access Portal Service Repository Objects ................................. 54-10
54.3.5 Preparing and Enabling the Access Portal Service on an Oracle Repository ........ 54-11
54.3.6 Preparing and Enabling the Access Portal Service on Microsoft Active Directory ..........
54-13
54.3.7 (Active Directory Only) Deploying the OAMAgent Web Application .................. 54-17
54.3.8 Setting the Policy Cache Refresh Interval ................................................................... 54-19
54.3.9 Integrating with Oracle Privileged Account Manager.............................................. 54-19
54.3.10 Deploying the Oracle Traffic Director Administration Server................................. 54-22
54.3.11 Deploying the Webgate Binaries and Secure Trust Artifacts................................... 54-23
54.3.12 (Optional) Configuring the ESSOProvisioning Plugin ............................................. 54-24
54.3.13 Creating an Oracle Traffic Director Configuration.................................................... 54-24
54.3.14 Protecting the Oracle Traffic Director Instance with the Webgate Plugin ............. 54-25
54.3.15 (Optional) Enabling the Detached Credential Collector for the Target Webgate . 54-26
54.3.16 Configuring Logon Manager for Compatibility with the Access Portal Service... 54-28
54.4 Enabling Form-Fill Single Sign-On for an Application .................................................... 54-29
54.4.1 Configuring a Form-Fill Application Policy ............................................................... 54-29
54.4.2 Configuring Proxy Rules for an Oracle Access Portal Application......................... 54-33
54.4.3 Configuring the Webgate Request Filtering ............................................................... 54-41
54.5 Adding a Federated Partner Provider Application .......................................................... 54-46
54.6 Adding an Oracle SSO Agent Application......................................................................... 54-47
54.7 Creating an Application Configuration Package .............................................................. 54-47
54.7.1 Contents of the Application Configuration Package................................................. 54-47
xxxii
54.7.2 Required Environment-Specific Configuration Data ................................................ 54-48
54.7.3 Customizing an Application Configuration Package to the Target Environment 54-48
54.7.4 Generating the Customized Application Configuration Package........................... 54-50
54.7.5 Deploying the Customized Application Configuration Package............................ 54-50
54.8 Managing Password Generation Policies........................................................................... 54-51
54.8.1 Searching for Password Generation Policies .............................................................. 54-51
54.8.2 Creating Password Generation Policies ...................................................................... 54-52
54.8.3 Managing Policy Subscribers........................................................................................ 54-54
54.9 Managing Credential Sharing Groups................................................................................ 54-55
54.9.1 Searching for Credential Sharing Groups ................................................................... 54-56
54.9.2 Creating Credential Sharing Groups ........................................................................... 54-56
54.9.3 Managing Applications in Credential Sharing Groups ............................................ 54-58
54.10 Managing Global Agent Settings......................................................................................... 54-59
54.10.1 Searching for Sets of Global Agent Settings................................................................ 54-60
54.10.2 Importing an INI File with a Global Agent Settings Configuration........................ 54-60
54.10.3 Creating a Set of Global Agent Settings ...................................................................... 54-60
Part XIV Using Identity Context
55 Using Identity Context
55.1 Introducing Identity Context ................................................................................................. 55-1
55.2 Understanding Identity Context............................................................................................ 55-3
55.3 Working With the Identity Context Service......................................................................... 55-4
55.3.1 Using the Identity Context Dictionary .......................................................................... 55-4
55.3.2 Understanding Identity Context Runtime .................................................................... 55-7
55.4 Using the Identity Context API.............................................................................................. 55-9
55.5 Configuring the Identity Context Service Components................................................... 55-11
55.5.1 Configuring Oracle Fusion Middleware ..................................................................... 55-11
55.5.2 Configuring Access Manager........................................................................................ 55-12
55.5.3 Configuring Oracle Adaptive Access Manager.......................................................... 55-13
55.5.4 Configuring Web Service Security Manager .............................................................. 55-15
55.5.5 Configuring Oracle Entitlements Server ..................................................................... 55-15
55.5.6 Configuring Oracle Enterprise Single Sign On .......................................................... 55-16
55.5.7 Configuring Oracle Access Management Mobile and Social................................... 55-17
55.6 Validating Identity Context.................................................................................................. 55-18
Part XV Integrating Access Manager with Other Products
56 Integrating RSA SecurID Authentication with Access Manager
56.1 Introduction to Access Manager and RSA SecurID Authentication ................................ 56-1
56.2 Components Required for SecurID Authentication ........................................................... 56-3
56.2.1 Supported Versions and Platforms ................................................................................ 56-3
56.2.2 Required RSA Components ............................................................................................ 56-3
56.2.3 Installation and Configuration Requirements.............................................................. 56-4
56.3 SecurID Authentication Modes.............................................................................................. 56-5
56.3.1 Standard SecurID Authentication .................................................................................. 56-5
xxxiii
56.3.2 SecurID Next Tokencode Authentication ..................................................................... 56-6
56.3.3 SecurID New PIN Authentication.................................................................................. 56-6
56.4 Configuring Access Manager for RSA SecurID Authentication ....................................... 56-6
56.5 Running a Custom RSA Plug-in .......................................................................................... 56-10
57 Configuring Access Manager for Windows Native Authentication
57.1 Introducing Access Manager with Windows Native Authentication.............................. 57-1
57.1.1 Understanding Access Manager WNA Login and Fall Back Authentication ......... 57-2
57.1.2 Understanding Supported Kerberos Authentication Modules ................................. 57-4
57.2 Preparing Your Active Directory/Kerberos Topology ...................................................... 57-5
57.3 Confirming Access Manager Operations ........................................................................... 57-10
57.4 Enabling the Browser to Return Kerberos Tokens ........................................................... 57-10
57.4.1 Enabling Kerberos Tokens in Internet Explorer......................................................... 57-10
57.4.2 Enabling Kerberos Tokens in Mozilla Firefox ............................................................ 57-11
57.5 Integrating KerberosPlugin with Oracle Virtual Directory............................................. 57-11
57.5.1 Preparing Oracle Virtual Directory for Integration................................................... 57-11
57.5.2 Registering Oracle Virtual Directory as the Default Store for WNA ...................... 57-12
57.5.3 Setting Up Authentication with Access Manager KerberosPlugin and OVD ....... 57-13
57.6 Integrating the KerberosPlugin with Search Failover ...................................................... 57-14
57.6.1 Registering Microsoft Active Directory Instances with Access Manager .............. 57-15
57.6.2 Setting Up the KerberosPlugin for ADGCs ................................................................ 57-15
57.7 Configuring Access Manager for Windows Native Authentication .............................. 57-17
57.7.1 Creating the Authentication Scheme for Windows Native Authentication .......... 57-18
57.7.2 Configuring Policies for Windows Native Authentication ...................................... 57-18
57.7.3 Configuring WNA for NTLM Fallback ....................................................................... 57-19
57.7.4 Verifying the Access Manager Configuration File..................................................... 57-19
57.8 Validating WNA with Access Manager Protected Resources ........................................ 57-20
57.9 Configuring WNA For Use With DCC............................................................................... 57-20
57.9.1 Initializing the Kerberos Protocol................................................................................. 57-21
57.9.2 Configuring Access Manager........................................................................................ 57-22
57.10 Troubleshooting WNA Configuration................................................................................ 57-23
57.10.1 Kinit Fails ......................................................................................................................... 57-23
57.10.2 "An Incorrect Username or Password was Specified" Is Displayed ...................... 57-23
57.10.3 User Identity Store is Not Registered Correctly......................................................... 57-24
57.10.4 Two BASIC Authentication Prompts Are Displayed................................................ 57-24
58 Integrating JBoss with Access Manager
58.1 Overview of JBoss Integration with Access Manager ........................................................ 58-1
58.1.1 Understanding the Configuration of and Processing by the JBoss Agent ............... 58-2
58.1.2 Understanding the Configuration of and Processing by the Login Module ........... 58-3
58.1.3 Understanding the Login Module Process in usernamePassword Mode................ 58-4
58.1.4 Understanding the Login Module Process in tokenBased Mode .............................. 58-5
58.2 Understanding the Integration Topology ........................................................................... 58-5
58.2.1 Topology: Access Manager with JBoss Agent ............................................................. 58-5
58.2.2 Topology: JBoss Agent Behind Web Server Configured with WebGate.................. 58-6
58.2.3 Sample Integration Topology ......................................................................................... 58-6
xxxiv
58.3 Preparing Your Environment for JBoss 6.x Integration ..................................................... 58-7
58.4 Preparing Your Environment for JBoss 5.x Integration ..................................................... 58-9
58.5 Protecting JBoss-Specific Resources .................................................................................... 58-10
58.5.1 Registering the JBoss Agent with Automatic Policy Creation ................................. 58-10
58.5.2 Creating a Custom Policy for JBoss Resource Protection ......................................... 58-12
58.6 Protecting Web Applications with the JBoss Agent.......................................................... 58-13
58.6.1 Creating Configuration Properties for the JBoss Agent............................................ 58-13
58.6.2 Configuring the Authentication Valve ........................................................................ 58-14
58.6.3 Mapping the Filter in the Application's web.xml File............................................... 58-15
58.6.4 Configuring the JBoss Login Module to Use Access Manager Policies.................. 58-15
58.7 Configuring JBoss Server to Access a Host Name (not localhost).................................. 58-16
58.8 Configuring the Login Module to Secure EJBs.................................................................. 58-16
58.8.1 Configuring the Server to Secure EJBs ........................................................................ 58-17
58.8.2 Configuring the Client Side for Login Module to Secure EJBs ................................ 58-18
58.9 Configuring the Login Module to Secure Web Service Access....................................... 58-19
58.9.1 Configuring the Server to Secure Web Services Access............................................ 58-19
58.9.2 Configuring the Client to Secure Web Services Access............................................. 58-21
58.10 Configuring Logging for the JBoss Agent and Login Module........................................ 58-21
58.11 Validating Your Configuration............................................................................................ 58-21
59 Integrating Microsoft SharePoint Server with Access Manager
59.1 What is Supported in This Release?...................................................................................... 59-1
59.2 Introduction to Integrating With the SharePoint Server ................................................... 59-2
59.2.1 About Windows Impersonation..................................................................................... 59-3
59.2.2 About Form Based Authentication With This Integration ......................................... 59-3
59.2.3 About Authentication With Windows Impersonation and SharePoint Server
Integration 59-4
59.2.4 About Access Manager and Windows Native Authentication.................................. 59-5
59.3 Integration Requirements ....................................................................................................... 59-6
59.3.1 Confirming Requirements............................................................................................... 59-6
59.3.2 Required Access Manager Components ....................................................................... 59-6
59.3.3 Required Microsoft Components ................................................................................... 59-7
59.4 Preparing for Integration With SharePoint Server.............................................................. 59-8
59.5 Integrating With Microsoft SharePoint Server .................................................................. 59-10
59.5.1 Creating a New Web Application in Microsoft SharePoint Server ......................... 59-11
59.5.2 Creating a New Site Collection for Microsoft SharePoint Server ............................ 59-13
59.6 Setting Up Microsoft Windows Impersonation ............................................................... 59-14
59.6.1 Creating Trusted User Accounts .................................................................................. 59-15
59.6.2 Assigning Rights to the Trusted User.......................................................................... 59-15
59.6.3 Binding the Trusted User to Your WebGate............................................................... 59-16
59.6.4 Adding an Impersonation Response to an Authorization Policy............................ 59-17
59.6.5 Adding an Impersonation DLL to IIS.......................................................................... 59-18
59.6.6 Testing Impersonation ................................................................................................... 59-20
59.7 Completing the SharePoint Server Integration.................................................................. 59-22
59.7.1 Configuring IIS Security ................................................................................................ 59-23
59.8 Integrating With Microsoft SharePoint Server Configured With LDAP Membership
Provider 59-23
xxxv
59.8.1 About Integrating With Microsoft SharePoint Server Configured With LDAP
Membership Provider 59-24
59.8.2 Installing Access Manager for Microsoft SharePoint Server Configured With LDAP
Membership Provider 59-25
59.8.3 Configuring an Authentication Scheme for Use With LDAP Membership Provider .......
59-26
59.8.4 Updating the Application Domain Protecting the SharePoint Web Site................ 59-27
59.8.5 Creating an Authorization Response for Header Variable SP_SSO_UID ............. 59-28
59.8.6 Creating an Authorization Response for the OAMAuthCookie ............................. 59-29
59.8.7 Configuring and Deploying OAMCustomMembershipProvider........................... 59-29
59.8.8 Enabling Logging for CustomMemberShipProvider ................................................ 59-32
59.8.9 Ensuring Directory Servers are Synchronized ........................................................... 59-32
59.8.10 Testing the Integration................................................................................................... 59-32
59.9 Configuring Single Sign-On for Office Documents .......................................................... 59-32
59.10 Configuring Single Sign-off for Microsoft SharePoint Server ......................................... 59-33
59.10.1 Configuring a Custom Logout URL in SharePoint Server ....................................... 59-33
59.10.2 Configuring Logout in SharePoint Server With Impersonation.............................. 59-34
59.11 Setting Up Access Manager and Windows Native Authentication ............................... 59-34
59.11.1 Setting Up Access Manager WNA ............................................................................... 59-34
59.11.2 Setting Up WNA With SharePoint Server................................................................... 59-35
59.11.3 Installing Access Manager for WNA and SharePoint Server................................... 59-35
59.11.4 Testing Your WNA Implementation ........................................................................... 59-37
59.12 Synchronizing User Profiles Between Directories ............................................................ 59-37
59.13 Testing Your Integration....................................................................................................... 59-37
59.13.1 Testing the SharePoint Server Integration .................................................................. 59-37
59.13.2 Testing Single Sign-On for the SharePoint Server Integration................................. 59-38
59.14 Troubleshooting ..................................................................................................................... 59-38
59.14.1 Internet Explorer File Downloads Over SSL Might Not Work................................ 59-38
60 Integrating Access Manager with Outlook Web Application
60.1 What is New in This Release? ................................................................................................ 60-1
60.2 Introduction to Integration with Outlook Web Application ............................................. 60-1
60.2.1 About Impersonation Provided by Microsoft Windows............................................ 60-2
60.2.2 About Access Manager 11g Support for Windows Impersonation .......................... 60-2
60.2.3 About Single Sign-On for Authenticated Access Manager Users into Exchange ... 60-2
60.2.4 About Confirming Requirements................................................................................... 60-3
60.3 Enabling Impersonation With a Header Variable............................................................... 60-3
60.3.1 Requirements for Impersonation with a Header Variable ......................................... 60-3
60.3.2 Creating an Impersonator as a Trusted User................................................................ 60-4
60.3.3 Assigning Rights to the Trusted User............................................................................ 60-5
60.3.4 Binding the Trusted User to Your WebGate................................................................. 60-6
60.3.5 Adding an Impersonation Response to An Application Domain ............................. 60-6
60.3.6 Adding an Impersonation DLL to IIS............................................................................ 60-7
60.3.7 Testing Impersonation ..................................................................................................... 60-8
60.4 Setting Up Impersonation for Outlook Web Application (OWA).................................. 60-10
60.4.1 Prerequisites to Setting Impersonation for Outlook Web Application................... 60-10
60.4.2 Creating a Trusted User Account for Outlook Web Application ............................ 60-11
xxxvi
60.4.3 Assigning Rights to the Outlook Web Application Trusted User ........................... 60-11
60.4.4 Binding the Trusted Outlook Web Application User to Your WebGate................ 60-11
60.4.5 Adding an Impersonation Action to an Application Domain for Outlook Web
Application 60-12
60.4.6 Adding an Impersonation dll to IIS ............................................................................. 60-13
60.4.7 Configuring IIS Security ................................................................................................ 60-13
60.4.8 Testing Impersonation for Outlook Web Application .............................................. 60-14
60.5 Setting Up Access Manager WNA for Outlook Web Application ................................. 60-15
61 Integrating Microsoft Forefront Threat Management Gateway 2010 with
Access Manager
61.1 What is New in This Release? ................................................................................................ 61-1
61.2 Introduction to Integration with TMG Server 2010 ............................................................ 61-1
61.2.1 About This Integration..................................................................................................... 61-1
61.2.2 About Confirming Certification Requirements............................................................ 61-2
61.3 Creating a Forefront TMG Policy and Rules........................................................................ 61-2
61.3.1 Creating a Custom Policy for Forefront TMG .............................................................. 61-2
61.3.2 Creating a Forefront TMG Firewall Policy Rule .......................................................... 61-3
61.3.3 Verifying Forefront TMG Proxy Configuration ........................................................... 61-5
61.4 Installing and Configuring 10g Webgate for Forefront TMG Server .............................. 61-6
61.4.1 Installing 10g Webgate with TMG Server..................................................................... 61-6
61.4.2 Changing /access Directory Permissions .................................................................... 61-6
61.5 Configuring the TMG 2010 Server for the ISAPI 10g Webgate......................................... 61-7
61.5.1 Registering Access Manager Plug-ins as TMG Server Web Filters ........................... 61-7
61.5.2 Ordering the ISAPI Filters............................................................................................... 61-7
61.5.3 Verifying Form-based Authentication........................................................................... 61-8
61.6 Starting, Stopping, and Restarting the TMG Server .......................................................... 61-8
61.7 Removing Access Manager Filters Before WebGate Uninstall on TMG Server ............. 61-9
61.8 Troubleshooting ....................................................................................................................... 61-9
62 Integrating Access Manager with SAP NetWeaver Enterprise Portal
62.1 What is Supported in This Release?...................................................................................... 62-1
62.2 Supported Versions and Platforms ....................................................................................... 62-1
62.3 Integration Architecture.......................................................................................................... 62-2
62.3.1 Process Overview: Integration with SAP NetWeaver Enterprise Portal.................. 62-2
62.4 Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x........ 62-3
62.4.1 Before You Begin............................................................................................................... 62-3
62.4.2 Configuring the Apache HTTP Server as a Proxy ...................................................... 62-4
62.4.3 Configuring SAP NetWeaver Enterprise Portal for External Authentication ......... 62-5
62.4.4 Adjusting the Login Module Stacks for using Header Variables .............................. 62-6
62.4.5 Configuring Access Manager for SAP Enterprise Portal ........................................... 62-7
62.5 Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x........ 62-8
62.5.1 Before You Begin............................................................................................................... 62-8
62.5.2 Configuring Access Manager for SAP NetWeaver Enterprise Portal 7.4.x.............. 62-8
62.5.3 Configuring Apache Web Server 2.0.x or 2.2.x........................................................... 62-10
62.5.4 Configuring SAP Enterprise Portal 7.4 for External Authentication ...................... 62-11
62.5.5 Adjusting the Login Module Stacks for Using Header Variables ........................... 62-13
xxxvii
62.6 Testing the Integration .......................................................................................................... 62-13
62.7 Troubleshooting the Integration.......................................................................................... 62-14
63 Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal
Using OpenSSO Policy Agent 2.2
63.1 What is Supported in This Release?...................................................................................... 63-1
63.2 Registering the OpenSSO Agent............................................................................................ 63-2
63.3 Installing the OpenSSO Policy Agent 2.2 on SAP Enterprise Portal ................................ 63-3
63.3.1 Post-Installation Steps...................................................................................................... 63-3
63.4 Deploying the Agent Software Delivery Archive ............................................................... 63-4
63.5 Making a Class Loader Reference to the Login Module .................................................... 63-4
63.6 Modifying the SAP Enterprise Portal 7.0 / Web Application Server 7.0 Class Path ..... 63-5
63.7 Deploying and Starting the Agentapp.war File .................................................................. 63-5
63.8 Using Telnet to Create a Reference Between agentapp and Library AmSAPAgent2.2. 63-5
63.9 Adding the Login Module to the Stack................................................................................. 63-6
63.10 Modifying the Login Module Stack ...................................................................................... 63-6
63.11 Updating the ume.logoff.redirect.uri.................................................................................... 63-6
63.12 Configuring the AMAgent.properties File........................................................................... 63-7
63.13 Testing the Integration ........................................................................................................... 63-7
Part XVI Appendixes
A Integrating Oracle ADF Applications with Access Manager SSO
A.1 Introducing Oracle Platform Security Services and Oracle Application Developer
Framework A-1
A.1.1 Oracle Platform Security Services Single Sign-on Framework .................................... A-1
A.1.2 Oracle Application Developer Framework..................................................................... A-2
A.2 Integrating Access Manager With Web Applications Using Oracle ADF Security and the
OPSS SSO Framework A-3
A.2.1 Sample SSO Configuration for Access Manager............................................................ A-4
A.2.2 SSO Provider Configuration Details ................................................................................ A-6
A.3 Configuring Centralized Logout for Oracle ADF-Coded Applications ............................ A-7
A.3.1 About Centralized Logout Processing for Applications Coded to Oracle ADF
Standards A-7
A.3.2 Configuring Centralized Logout for ADF-Coded Applications with Access Manager....
A-8
A.4 Confirming Application-Driven Authentication During Runtime .................................. A-10
B Internationalization and Multibyte Data Support for 10g WebGates
B.1 Introduction to Internationalization and Multibyte Data Support .................................... B-1
B.1.1 Languages For Localized Messages ................................................................................ B-1
B.1.2 Bi-directional Language Support ..................................................................................... B-3
B.1.3 UTF-8 Encoding .................................................................................................................. B-3
C Securing Communication
C.1 Prerequisites ............................................................................................................................... C-1
xxxviii
C.2 Securing Communication Between OAM Servers and WebGates ..................................... C-1
C.2.1 About Certificates, Authorities, and Encryption Keys.................................................. C-3
C.2.2 About Security Modes and X509Scheme Authentication ............................................ C-4
C.2.3 About the Importcert Tool................................................................................................. C-4
C.3 Generating Client Keystores for OAM Tester in Cert Mode ............................................... C-5
C.4 Configuring Cert Mode Communication for Access Manager ........................................... C-6
C.4.1 About Cert Mode Encryption and Files .......................................................................... C-6
C.4.2 Generating a Certificate Request and Private Key for OAM Server........................... C-7
C.4.3 Retrieving the OAM Keystore Alias and Password ..................................................... C-7
C.4.4 Importing the Trusted, Signed Certificate Chain Into the Keystore ........................... C-8
C.4.5 Adding Certificate Details to Access Manager Settings.............................................. C-10
C.4.6 Generating a Private Key and Certificate Request for WebGates ............................. C-11
C.4.7 Updating WebGate to Use Certificates.......................................................................... C-12
C.5 Configuring Simple Mode Communication with Access Manager ................................. C-13
C.5.1 About Simple Mode, Encryption, and Keys ................................................................. C-14
C.5.2 Retrieving the Global Passphrase for Simple Mode.................................................... C-14
C.5.3 Updating WebGate Registration for Simple Mode...................................................... C-15
C.5.4 Verifying Simple Mode Configuration.......................................................................... C-16
D Reviewing Bundled, Generated, and Migrated Artifacts
D.1 Bundled 10g IAMSuiteAgent Artifacts................................................................................... D-1
D.1.1 Pre-Registered 10g IAMSuiteAgent ................................................................................ D-1
D.1.2 IAMSuiteAgent Security Provider Settings, WebLogic Administration Console..... D-2
D.1.3 IAMSuiteAgent Registration............................................................................................. D-2
D.1.4 Resources Protected by IAMSuiteAgent ......................................................................... D-4
D.1.5 Pre-seeded IAM Suite Application Domain and Policies............................................. D-5
D.2 Generated Artifacts: OpenSSO............................................................................................... D-10
D.2.1 Generated OpenSSOAgentAuthPlugin......................................................................... D-10
D.2.2 Generated Host Identifier: OpenSSOAgent1................................................................ D-11
D.2.3 Generated Application Domain: OpenSSOAgent1 ..................................................... D-11
D.2.4 Generated Resources: OpenSSOAgent1........................................................................ D-12
D.2.5 Generated Authentication Policy: OpenSSOAgent Application Domain................ D-12
D.2.6 Generated Authorization Policy: OpenSSOAgent Application Domain ................. D-13
D.3 Migrated Artifacts: OpenSSO................................................................................................. D-13
D.3.1 Migrated User Identity Store: OpenSSOAgent1 .......................................................... D-14
D.3.2 Migrated Agents: OpenSSOAgent1 ............................................................................... D-15
D.3.3 Migrated Authentication Module: OpenSSOAgent1 .................................................. D-16
D.3.4 Migrated Host Identifier: OpenSSOAgent1.................................................................. D-16
D.3.5 Migrated Application Domain: OpenSSOAgent1........................................................ D-16
D.3.6 Migrated Resources: OpenSSOAgent1.......................................................................... D-17
D.3.7 Migrated Authentication Policy: OpenSSOAgent1 ..................................................... D-17
D.3.8 Migrated Authorization Policy: OpenSSOAgent1....................................................... D-18
E Troubleshooting
E.1 Introduction to Oracle Access Management Troubleshooting ........................................... E-2
E.1.1 About System Analysis and Problem Scenarios ............................................................ E-2
E.1.2 About LDAP Server or Identity Store Issues .................................................................. E-3
xxxix
E.1.3 About OAM Server or Host Issues................................................................................... E-4
E.1.4 About Agent-Side Configuration and Load Issues........................................................ E-4
E.1.5 About Runtime Database (Audit or Session Data) Issues ............................................ E-5
E.1.6 About Change Propagation or Activation Issues .......................................................... E-5
E.1.7 About Policy Store Database Issues................................................................................. E-6
E.2 Using My Oracle Support for Additional Troubleshooting Information.......................... E-6
E.3 Administrator Lockout.............................................................................................................. E-6
E.4 Error During Federation Configuration After Upgrade from PS1 to PS2 ......................... E-7
E.5 Oracle Access Management Console Inconsistent State ...................................................... E-7
E.6 AdminServer Won't Start if the Wrong Java Path Given with WebLogic Server Installation
E-8
E.7 Agent Naming Not Unique ...................................................................................................... E-8
E.8 Application URL Requirements............................................................................................... E-8
E.9 Authentication Issues ................................................................................................................ E-9
E.9.1 Anonymous Authentication Issues.................................................................................. E-9
E.9.2 X.509Scheme and SSL Handshake Issues........................................................................ E-9
E.9.3 X.509 Protected Resource and Single Sign Off ............................................................. E-10
E.9.4 X509CredentialExtractor Certificate Validation Error ................................................ E-11
E.10 Authorization Issues................................................................................................................ E-11
E.10.1 Authorization Condition Error....................................................................................... E-11
E.10.2 LDAP Search Filter Test Results..................................................................................... E-11
E.10.3 Authorization Header Response Names....................................................................... E-12
E.11 Cannot Access Authentication LDAP or Database............................................................. E-12
E.12 Cannot Find Configuration .................................................................................................... E-12
E.12.1 Configuration Does Not Exist ........................................................................................ E-12
E.13 Co-existence Between OSSO and Access Manager............................................................. E-13
E.14 Could Not Find Partial Trigger.............................................................................................. E-13
E.15 Denial of Service Attacks ........................................................................................................ E-13
E.15.1 Protecting the OAM Server from Crashing Under Load............................................ E-14
E.15.2 Compensating for Network Latency ............................................................................ E-15
E.15.3 Protecting OAM Servers from a Flood of HTTP Requests ......................................... E-15
E.16 Deployments with Freshly Installed 10g Webgates............................................................ E-15
E.16.1 Authentication Issues with 10g Webgates .................................................................... E-16
E.16.2 Logout Issues with 10g Webgates .................................................................................. E-16
E.17 Diagnosing Initialization and Performance Issues ............................................................. E-16
E.17.1 Diagnosing an Initialization Issue.................................................................................. E-16
E.17.2 Diagnosing a Performance Issue .................................................................................... E-17
E.17.3 Diagnosing Out-of-Memory Issues With a Heap Dump............................................ E-17
E.18 Disabling Windows Challenge/Response Authentication on IIS Web Servers ............. E-18
E.19 Changing UserIdentityStore1 Type Can Lock Out Administrators................................. E-18
E.20 IIS Web Server Issues .............................................................................................................. E-18
E.20.1 Form Authentication or Pass-Through Not Working ................................................. E-19
E.20.2 IIS and General Web Component Guidelines .............................................................. E-19
E.20.3 Issues with IIS v6 Web Servers ....................................................................................... E-19
E.20.4 Page Cannot Be Displayed Error.................................................................................... E-20
E.20.5 Removing and Reinstalling IIS DLLs............................................................................. E-20
E.21 Import and File Upload Limits .............................................................................................. E-21
xl
E.22 jps Logger Class Instantiation Warning is Logged on Authentication............................ E-21
E.23 Internationalization, Languages, and Translation .............................................................. E-21
E.23.1 Automatically Generated Descriptions Are Not Translated...................................... E-22
E.23.2 Console Looks Messy ...................................................................................................... E-22
E.23.3 Authentication Fails: Users with Non-ASCII Characters ........................................... E-22
E.23.4 Access Tester Does Not Work with Non-ASCII Agent Names ................................. E-22
E.23.5 Locales, Languages, and Oracle Access Management Console Login Page............ E-22
E.24 Login Failure for a Protected Page ........................................................................................ E-23
E.25 OAM Metric Persistence Timer IllegalStateException: SafeCluster ................................ E-23
E.26 Partial Cluster Failure and Intermittent Login and Logout Failures ............................... E-24
E.27 RSA SecurID Issues and Logs ................................................................................................ E-24
E.28 Registration Issues ................................................................................................................... E-25
E.29 Rowkey does not have any primary key attributes Error.................................................. E-25
E.30 SELinux Issues.......................................................................................................................... E-25
E.31 Session Issues............................................................................................................................ E-26
E.31.1 Session Impersonation Not Enabled by Default .......................................................... E-26
E.31.2 Sessions with Oracle Access Manager 11.1.1 Integrated with Oracle Identity Federation
11.1.1 E-27
E.32 SSL versus Open Communication......................................................................................... E-27
E.33 Start Up Issues.......................................................................................................................... E-27
E.34 Synchronizing OAM Server Clocks ...................................................................................... E-28
E.35 Using Coherence ..................................................................................................................... E-29
E.36 Validation Errors...................................................................................................................... E-30
E.37 Web Server Issues .................................................................................................................... E-30
E.37.1 Server Fails on an Apache Web Server.......................................................................... E-31
E.37.2 Apache v2 on HP-UX ....................................................................................................... E-31
E.37.3 Apache v2 Bundled with Red Hat Enterprise Linux 4................................................ E-31
E.37.4 Apache v2 Bundled with Security-Enhanced Linux ................................................... E-31
E.37.5 Apache v2 on UNIX with the mpm_worker_module for Webgate .......................... E-32
E.37.6 Domino Web Server Issues.............................................................................................. E-33
E.37.7 Errors, Loss of Access, and Unpredictable Behavior................................................... E-33
E.37.8 Known Issues for ISA Web Server ................................................................................. E-33
E.37.9 Oracle HTTP Server Fails to Start with LinuxThreads................................................ E-34
E.37.10 Oracle HTTP Server Webgate Fails to Initialize On Linux Red Hat 4 ...................... E-34
E.37.11 Oracle HTTP Server Web Server Configuration File Issue......................................... E-35
E.37.12 Issues with IIS v6 Web Servers ....................................................................................... E-35
E.37.13 PCLOSE Error When Starting Sun Web Server............................................................ E-36
E.37.14 Removing and Reinstalling IIS DLLs............................................................................. E-36
E.38 Windows Native Authentication........................................................................................... E-36
xli
List of Figures
1–1 Oracle Access Management Overview.................................................................................... 1-2
1–2 Access Manager 11g Components and Services..................................................................... 1-5
1–3 Access Manager 11g Component Distribution....................................................................... 1-5
2–1 Oracle Access Management Administrator Launch Pad...................................................... 2-6
2–2 Self Service Launch Pad ............................................................................................................. 2-7
2–3 SSO Agent Search Page........................................................................................................... 2-11
3–1 Oracle Access Management Configuration Options ............................................................. 3-2
3–2 Available Services ....................................................................................................................... 3-3
3–3 Common Settings Page (Collapsed View)............................................................................... 3-5
3–4 Common Coherence Settings .................................................................................................... 3-7
3–5 Certificate Revocation List Dialog Box .................................................................................... 3-8
3–6 OCSP/CDP Settings ................................................................................................................... 3-9
5–1 Creating User Identity Store Registration .............................................................................. 5-9
5–2 System Store Registration ...................................................................................................... 5-12
5–3 Identity Directory Service Console Page .............................................................................. 5-16
5–4 Create IDS Profile Page ........................................................................................................... 5-18
5–5 Create IDS Repository Page ................................................................................................... 5-25
5–6 Add System Administrator Roles.......................................................................................... 5-27
6–1 OAM Server Registration Page with Proxy Tab Displayed ................................................. 6-5
8–1 Audit to Database Architecture ................................................................................................ 8-4
8–2 Common Settings: Auditing Configuration......................................................................... 8-23
9–1 Log-Level Activation in the Default Log Configuration File ............................................ 9-21
11–1 Server Processes Overview Page ........................................................................................... 11-3
11–2 OAM Server Metrics: Session Operations Monitoring Page ............................................. 11-4
11–3 OAM Server Metrics: Server Operations Tab ...................................................................... 11-5
11–4 OAM Server Metrics: WebGates Tab .................................................................................... 11-6
11–5 Webgate Metrics: Connectivity Table .................................................................................. 11-7
11–6 Webgate Metrics: Operations Overview Table ................................................................... 11-7
11–7 Webgate Metrics: Operations Detail Table .......................................................................... 11-7
11–8 Webgate Metrics: Detached Information Table .................................................................. 11-8
11–9 OSSO Agent Monitoring Page with Operation Details...................................................... 11-8
11–10 OSSO Agent Monitoring Process Overview Table ............................................................ 11-9
11–11 OSSO Agent Operation Details Table .................................................................................. 11-9
11–12 OAM Metrics Table ............................................................................................................... 11-12
11–13 Weblogic Metrics.................................................................................................................... 11-12
12–1 Fusion Middleware Control (AS-Control) Deployment Architecture ............................ 12-2
12–2 OAM Farm Page in Fusion Middleware Control................................................................ 12-4
12–3 Farm Navigation Tree in Fusion Middleware Control ...................................................... 12-5
12–4 Node Information Page in Fusion Middleware Control.................................................... 12-5
12–5 Application Deployment Summary for the Selected Internal Application..................... 12-6
12–6 Application Deployment Menu............................................................................................. 12-6
12–7 WebLogic Server Domain Summary with Context Menu Exposed................................. 12-7
12–8 Cluster Page ............................................................................................................................. 12-9
12–9 Key Metrics for Server Page ................................................................................................ 12-10
12–10 Aggregated Access Manager Component Metrics for the Cluster................................. 12-12
12–11 Access Manager Component Metrics for a Single OAM Server Instance ..................... 12-12
12–12 Aggregated STS Component Metrics for the Cluster ....................................................... 12-14
12–13 STS Component Metrics for an Individual OAM Server Instance ................................. 12-14
12–14 Performance Summary Command...................................................................................... 12-15
12–15 Performance Summary Page with Metric Palette ............................................................ 12-15
12–16 Access Manager Log Levels on the Log Configuration Tab............................................ 12-21
12–17 Log Levels for Security Token Service ............................................................................... 12-22
12–18 Log Files Configuration Page............................................................................................... 12-25
12–19 Typical Log Messages Page in Fusion Middleware Control ........................................... 12-29
xlii
12–20 System MBean Browser and Attributes Tab...................................................................... 12-35
13–1 Access Manager Settings: Load Balancer ............................................................................. 13-2
13–2 Access Manager Settings: Server Error Mode...................................................................... 13-3
13–3 Access Manager Settings: SSO ............................................................................................... 13-6
13–4 Common Policy Evaluation Caches .................................................................................... 13-10
15–1 Create OAM 11g WebGate Page............................................................................................ 15-2
15–2 Load Balanced Deployment ................................................................................................. 15-12
15–3 Expanded 11g WebGate Page with Defaults .................................................................... 15-15
15–4 WebGate Search Controls and Create Button.................................................................... 15-21
15–5 Key Generation....................................................................................................................... 15-28
16–1 Global Session Details: Common Settings Page .................................................................. 16-9
16–2 Common Configuration: Session Management Page....................................................... 16-12
17–1 Multi-Data Center System Architecture ............................................................................... 17-2
17–2 Active-Active Deployment Mode.......................................................................................... 17-6
17–3 Active-Active Mode Failover ................................................................................................. 17-7
17–4 Multi-Data Center Deployment............................................................................................. 17-8
17–5 Requests Served By Different Data Centers....................................................................... 17-12
17–6 Logout and Session Invalidation ......................................................................................... 17-13
17–7 Stretch Cluster Deployment ................................................................................................. 17-14
17–8 Traditional MDC Deployment............................................................................................. 17-14
17–9 Active-Active Topology ........................................................................................................ 17-15
17–10 Active-Active Topology Across Multiple Data Centers................................................... 17-16
17–11 Load Balancing Access Manager Components ................................................................. 17-17
17–12 Global Load Balancer Front Ends Local Load Balancer ................................................... 17-18
19–1 Replication Flow ...................................................................................................................... 19-3
19–2 EnableMDCReplication Java Property ................................................................................. 19-4
19–3 Starting Sequence Illustrated.................................................................................................. 19-6
19–4 Applying Custom Transformation Rules........................................................................... 19-11
21–1 Access Manager 11g Policy Model ...................................................................................... 21-7
21–2 Access Manager Shared Policy Components....................................................................... 21-7
21–3 Anatomy of Access Manager Policies................................................................................. 21-11
22–1 Default HTTP Resource Type Definition ............................................................................. 22-4
22–2 Default Resource Type wl_authen ........................................................................................ 22-5
22–3 Default Resource Type TokenServiceRP Resource Type ................................................... 22-5
22–4 Create Host Identifier Page .................................................................................................. 22-14
22–5 Native Kerberos Authentication Module........................................................................... 22-25
22–6 Native LDAP Authentication Module................................................................................ 22-26
22–7 Native X.509 Authentication Module ................................................................................. 22-27
22–8 Access Manager Plug-ins for Customized Authentication Modules ............................. 22-32
22–9 Creating Custom Authentication Modules: General ....................................................... 22-33
22–10 Adding a Step and Associating a Plug-in........................................................................... 22-34
22–11 Plug-in Based Authentication Module Steps and Details................................................ 22-38
22–12 Steps Orchestration for Plug-in Based Authentication Modules.................................... 22-39
22–13 KerberosPlugin....................................................................................................................... 22-40
22–14 Default KerberosPlugin Steps and Details......................................................................... 22-41
22–15 Default KerberosPlugin Steps and Orchestration............................................................. 22-41
22–16 LDAPPlugin............................................................................................................................ 22-42
22–17 Default LDAPPlugin Steps and Details.............................................................................. 22-42
22–18 Default Orchestration of Steps for LDAPplugin ............................................................... 22-43
22–19 X509Plugin .............................................................................................................................. 22-43
22–20 X509Plugin Default Steps and Details ................................................................................ 22-44
22–21 Default Orchestration for X509Plugin Steps ...................................................................... 22-45
22–22 Password Policy Validation Module Plug-ins................................................................... 22-45
22–23 Steps Orchestration: Password Policy Validation Plug-ins ............................................. 22-46
22–24 Plug-ins Page .......................................................................................................................... 22-59
xliii
22–25 Plugin Details: Activation Status of Selected Plug-in....................................................... 22-62
22–26 Default LDAPScheme Page.................................................................................................. 22-65
23–1 SSO Log-in with Embedded Credential Collector and OAM Agents.............................. 23-4
23–2 Example: Separate Resource WebGate and DCC WebGate Deployment ...................... 23-7
23–3 Combined DCC and WebGate Configuration..................................................................... 23-8
23–4 SSO Login Processing with OSSO Agents and ECC........................................................... 23-9
23–5 OAP Tunneling with DCC.................................................................................................... 23-15
23–6 Enable SSL............................................................................................................................... 23-17
23–7 Keystore Configuration......................................................................................................... 23-17
23–8 Add Private Key Alias........................................................................................................... 23-18
23–9 SSL Advanced Options ......................................................................................................... 23-18
23–10 New X509 Scheme.................................................................................................................. 23-22
24–1 Password Policy Configuration Page.................................................................................... 24-4
24–2 Password Policy Validation Authentication Module with Orchestrated Plug-ins ...... 24-16
24–3 Step Orchestration for Password Policy Validation Module........................................... 24-16
24–4 Server Error Mode for Password Management................................................................. 24-21
25–1 Application Domains Search Page ........................................................................................ 25-5
25–2 Example Application Domain Summary Page.................................................................... 25-6
25–3 Search Results for Resources in an Application Domain................................................... 25-6
25–4 Authentication Policies Tab.................................................................................................... 25-7
25–5 Authentication Policy Page: Resources and Responses .................................................... 25-8
25–6 Authorization Policies Page ................................................................................................... 25-9
25–7 Individual Authorization Policy Page .................................................................................. 25-9
25–8 Individual Authorization Policy Resources tab ................................................................ 25-10
25–9 Token Issuance Policies Page ............................................................................................... 25-10
25–10 Create Resource Page in the Application Domain............................................................ 25-15
25–11 HTTP Resources, Query String Resource URL Controls ................................................. 25-25
25–12 Resource Search within an Application Domain .............................................................. 25-29
25–13 Sample Authentication Policies Page in the Application Domain ................................. 25-32
25–14 Sample Individual Authentication Policy Page ................................................................ 25-32
25–15 Sample Individual Authorization Policy Page .................................................................. 25-36
25–16 Individual Authorization Policy Conditions Tab ............................................................. 25-42
25–17 Add Condition Window ...................................................................................................... 25-44
25–18 Condition Containers on the Authorization Policy Page................................................. 25-45
25–19 Add Identities Window ....................................................................................................... 25-46
25–20 Identity Condition and Details ............................................................................................ 25-47
25–21 Add Search Filter Controls ................................................................................................... 25-48
25–22 Identity Conditions: Details ................................................................................................. 25-49
25–23 IP4 Range Conditions............................................................................................................ 25-53
25–24 Temporal Condition Type Details Page ............................................................................. 25-54
25–25 Attribute Conditions Page.................................................................................................... 25-57
25–26 Add Attribute Condition Dialog ........................................................................................ 25-57
25–27 Authorization Policy Rules Tab: Simple Mode ................................................................. 25-62
25–28 Rules Tab: Expression Rule Mode....................................................................................... 25-64
25–29 Adding a Resource Prefix for Policy Ordering.................................................................. 25-67
25–30 Authorization Policy Response in the Console ................................................................. 25-69
25–31 Simple Response Samples..................................................................................................... 25-72
25–32 Complex Response Sample ................................................................................................. 25-73
26–1 OAM Agent (PEP) and OAM Server (PDP) Inter-operability........................................... 26-4
26–2 User Interactions with the Access Tester.............................................................................. 26-7
26–3 Access Tester Console ........................................................................................................... 26-13
26–4 Server Connection Panel in the Access Tester ................................................................... 26-16
26–5 Protected Resource URI Panel in the Access Tester.......................................................... 26-19
26–6 Access Tester User Identity Panel ....................................................................................... 26-21
26–7 Test Case Workflow............................................................................................................... 26-25
xliv
28–1 Typical Deployment with OpenSSO and Access Manager ............................................... 28-7
28–2 Create OpenSSO Agent Page ............................................................................................... 28-11
28–3 Expanded OpenSSO Web Agent Registration Page ......................................................... 28-13
28–4 Expanded OpenSSO J2EE Agent Registration Page ......................................................... 28-14
29–1 Create OSSO Agent Page........................................................................................................ 29-7
29–2 OSSO Agent Page and Confirmation Window ................................................................... 29-9
35–1 Second Factor Authentication Preferred Method Page...................................................... 35-2
35–2 One Time Password Login Page............................................................................................ 35-3
35–3 Access Request Notification Preferred Method Page......................................................... 35-5
35–4 Access Request Notification Wait Screen............................................................................. 35-6
37–1 Available Services Page......................................................................................................... 37-15
38–1 New Identity Provider Page, Service Details Loaded from Metadata............................. 38-3
38–2 New Identity Provider Page, Service Details entered Manually ...................................... 38-4
38–3 Searching for Identity Providers............................................................................................ 38-9
38–4 Attribute Sharing Plug-in Design........................................................................................ 38-19
39–1 Identity Federation Service Settings Page ............................................................................ 39-2
39–2 Keystore Settings...................................................................................................................... 39-5
40–1 FederationScheme.................................................................................................................... 40-2
40–2 FederationPlugin Steps ........................................................................................................... 40-3
40–3 FederationPlugin Orchestration ............................................................................................ 40-4
40–4 Setting Up the Authentication Policy with FederationScheme......................................... 40-6
40–5 OIFScheme ................................................................................................................................ 40-7
40–6 OIFMTLDAPPlugin................................................................................................................. 40-8
40–7 Authorization Policy Response Tab.................................................................................... 40-10
40–8 Adding a Federation Response Attribute to an AuthZ Policy........................................ 40-12
41–1 Security Token Service Architecture..................................................................................... 41-8
41–2 Security Token Service Token Support................................................................................. 41-8
41–3 Token Translation at a Centralized Authority..................................................................... 41-9
41–4 Translating Tokens Behind a Firewall ................................................................................ 41-10
41–5 Web Services SSO................................................................................................................... 41-11
42–1 Typical Token Ecosystem ....................................................................................................... 42-2
42–2 Identity Propagation with the OAM Token......................................................................... 42-3
42–3 Process Flow During Identity Propagation.......................................................................... 42-3
42–4 Identity Propagation Deployment......................................................................................... 42-4
42–5 Identity Propagation Processing ........................................................................................... 42-4
42–6 Required v1.0 WebLogic Server Identity Assertion Providers ......................................... 42-9
42–7 IAP-Security Token Service Details..................................................................................... 42-10
42–8 LDAP Provider: IAP-DSEE .................................................................................................. 42-11
42–9 Default Identity Store Defined in Access Manager........................................................... 42-12
42–10 Token Issuance Policy for Identity Propagation .............................................................. 42-12
42–11 /wssuser Endpoint for Identity Assertion......................................................................... 42-13
42–12 Default Identity Store Defined for Access Manager ......................................................... 42-19
42–13 Token Issuance Policy for Identity Propagation ............................................................... 42-20
42–14 /wss11user Endpoint for Identity Assertion..................................................................... 42-20
43–1 Default Endpoints, Policies, and Validation Templates..................................................... 43-5
43–2 WS-Security 1.0 and 1.1 Policies ............................................................................................ 43-7
43–3 Security Token Service Page................................................................................................. 43-10
45–1 Validation Templates Search Controls ................................................................................. 45-3
45–2 Issuance Template Search Controls....................................................................................... 45-3
45–3 Issuance Template: General Details and Defaults............................................................... 45-6
45–4 Issuance Properties: Username Token Type........................................................................ 45-6
45–5 Issuance Properties: SAML Token Types............................................................................. 45-7
45–6 Security Details: SAML Tokens ............................................................................................. 45-9
45–7 New Validation Template page: General Page Defaults.................................................. 45-14
45–8 New Validation Template: General Authentication Details............................................ 45-16
xlv
45–9 Token Mapping: SAML2 WS-Security Validation Template .......................................... 45-18
45–10 Token Mapping, username-wstrust-validation-template................................................ 45-19
45–11 Token Mapping: x509-wss-validation-template................................................................ 45-19
45–12 Endpoints Page....................................................................................................................... 45-25
45–13 Token Issuance Policies and Conditions ............................................................................ 45-28
45–14 Pre-defined Resource Type: TokenServiceRP ................................................................... 45-31
45–15 Search: Resource Type TokenServiceRP in Application Domain................................... 45-32
45–16 New Custom Token Page ..................................................................................................... 45-34
45–17 Custom Tokens Search Page and Controls ........................................................................ 45-36
45–18 General Details: email-wstrust-valid-temp........................................................................ 45-39
45–19 Token Mapping: email-wstrust-valid-temp....................................................................... 45-39
45–20 General Details: email-issuance-temp ................................................................................ 45-40
45–21 Issuance Properties: email-issuance-temp ......................................................................... 45-41
46–1 New Requester Partner Page.................................................................................................. 46-3
46–2 New Relying Party Partners Page ......................................................................................... 46-4
46–3 Partner Search Controls .......................................................................................................... 46-7
46–4 Requester Profile: General ...................................................................................................... 46-8
46–5 Requester Profile: Token and Attributes .............................................................................. 46-9
46–6 Relying Party Profile Token and Attributes....................................................................... 46-10
46–7 Token and Attributes: Issuing Authority .......................................................................... 46-14
46–8 Issuing Authority Profile: Token Mapping Tab ................................................................ 46-16
46–9 Search Partner Profiles Page: Requester Profiles............................................................... 46-20
48–1 First Time Device/Application Registration and Authentication Process.................... 48-12
48–2 Mobile SSO Agent Requests Access Token from Access Manager ................................ 48-13
48–3 Mobile SSO Agent Has Valid Access Token in Credential Store.................................... 48-14
48–4 Mobile SSO Agent Does Not Have Valid Access Token in Credential Store................ 48-15
48–5 User Authentication Using REST ........................................................................................ 48-16
48–6 Authenticating User From Browser-based Web App on Registered Mobile Device... 48-17
48–7 .................................................................................................................................................. 48-19
48–8 Authenticating a Returning User with a Local Account.................................................. 48-25
48–9 Authenticating a New User with No Local Account........................................................ 48-27
48–10 Authenticating a User With an OAuth Identity Provider ............................................... 48-29
48–11 Authenticating a User with Access Manager..................................................................... 48-31
48–12 Authenticating a User Locally.............................................................................................. 48-32
49–1 Using ODSM to create the PIN attribute in OUD ............................................................. 49-13
49–2 Using ODSM to create the pinperson object class............................................................. 49-14
49–3 Using the OAM Console to create an IdentityStore.......................................................... 49-15
50–1 Social Identity Account Linking .......................................................................................... 50-18
52–1 OAuth 3-Legged Flow Diagram ............................................................................................ 52-4
52–2 Using a Split Request to get a Client Verification Code..................................................... 52-6
52–3 The Complete Mobile App Authorization Request Flow.................................................. 52-9
53–1 Mobile (top) and Federation (bottom) Identity Domain Screens...................................... 53-2
53–2 Identity Federation DefaultDomain Configuration Page .................................................. 53-3
53–3 Mobile Security DefaultDomain Configuration Page ........................................................ 53-3
53–4 OAuth Services Service Profile Configuration Page......................................................... 53-37
54–1 Password Generation Policies Search/Create Tab............................................................ 54-51
54–2 New Password Generation Policy Summary Tab............................................................. 54-52
54–3 Password Constraints Tab of a Password Generation Policy ......................................... 54-54
54–4 Add Applications Dialog...................................................................................................... 54-55
54–5 Credential Sharing Groups tab ............................................................................................ 54-56
54–6 New Credential Sharing Group Page ................................................................................. 54-58
54–7 Add Applications Dialog...................................................................................................... 54-59
54–8 Global Agent Settings Search tab......................................................................................... 54-60
54–9 New Global Agent Settings Page......................................................................................... 54-61
55–1 End to End Identity Context Process .................................................................................... 55-3
xlvi
55–2 End To End Identity Context Process Components ........................................................... 55-3
55–3 Identity Context Process Flow ............................................................................................... 55-8
55–4 OAM Authentication Provider Configuration .................................................................. 55-18
58–1 Various Clients Deployed on JBoss Application Server..................................................... 58-5
58–2 JBoss Agent Deployed with an Oracle HTTP Server WebGate ........................................ 58-6
58–3 Sample Integration Topology................................................................................................. 58-6
59–1 Setting up a Trusted User Account for Windows Impersonation .................................. 59-15
59–2 Configuring Rights for the Trusted User in Windows Impersonation.......................... 59-16
59–3 Registering the Impersonation Module.............................................................................. 59-19
59–4 Verifying Event Viewer Settings.......................................................................................... 59-21
59–5 Impersonation Authentication............................................................................................. 59-23
60–1 Setting up a Trusted User Account for Windows Impersonation .................................... 60-5
60–2 Configuring Rights for the Trusted User in Windows Impersonation............................ 60-6
60–3 Verifying Event Viewer Settings............................................................................................ 60-9
60–4 Impersonation Authentication............................................................................................. 60-14
C–1 Communication Channels for OAM Servers and WebGates.............................................. C-2
D–1 IAMSuiteAgent Settings in the WebLogic Administration Console.................................. D-2
D–2 IAMSuiteAgent Registration.................................................................................................... D-3
D–3 Resources Protected by the IAMSuiteAgent.......................................................................... D-5
D–4 IAMSuite Authentication Policy: OAM Admin Console Policy......................................... D-6
D–5 Protected HigherLevel Policy: Authentication, LDAP Scheme .......................................... D-7
D–6 Protected LowerLevel Policy: Authentication, OIMScheme .............................................. D-8
D–7 Public Policy: Authentication, AnonymousSheme ............................................................... D-8
D–8 IAM Suite Authorization Policy .............................................................................................. D-9
D–9 IAM Suite Token Issuance Policy and Resource URLs ........................................................ D-9
D–10 Generated Authentication Module: OpenSSOAgentAuthPlugin..................................... D-10
D–11 Generated Host Identifier: OpenSSOAgent1....................................................................... D-11
D–12 Generated Application Domain: OpenSSOAgent1............................................................. D-11
D–13 Application Domain Resources: OpenSSOAgent1 ............................................................. D-12
D–14 Generated Authentication Policy: OpenSSOAgent Application Domain ....................... D-12
D–15 Generated Authorization Policy: OpenSSOAgent Application Domain......................... D-13
D–16 Migrated User Identity Store.................................................................................................. D-14
D–17 Migrated Agent: OpenSSOAgent1 ........................................................................................ D-15
D–18 Migrated Authentication Module: OpenSSOAgent1.......................................................... D-16
D–19 Migrated Host Identifier: OpenSSOAgent1 ......................................................................... D-16
D–20 Migrated Application Domain: OpenSSOAgent1............................................................... D-16
D–21 Migrated Resources: OpenSSOAgent1 ................................................................................. D-17
D–22 Migrated Authentication Policy: OpenSSOAgent1 ............................................................ D-17
D–23 Migrated Authorization Policy2 Condition: OpenSSOAgent1 ......................................... D-18
D–24 Migrated Authorization Policy2: IP Condition Details ...................................................... D-18
xlvii
xlviii
List of Tables
1–1 Access Manager Deployment Types....................................................................................... 1-6
1–2 Features in Access Manager 11.1.2 .......................................................................................... 1-7
1–3 Features Not Available In Access Manager 11.1.2 ................................................................ 1-9
1–4 Oracle Access Management Post-Installation Tasks.......................................................... 1-11
2–1 Language Codes For Login Pages ........................................................................................ 2-13
2–2 Oracle Access Management Language Selection Methods............................................... 2-14
2–3 OAM_LANG_PREF Cookie .................................................................................................. 2-15
2–4 Application Integration for Language Preference ............................................................. 2-15
3–1 Configuration Options .............................................................................................................. 3-2
3–2 Common Services ...................................................................................................................... 3-4
3–3 Common Settings....................................................................................................................... 3-5
3–4 Common Coherence Settings ................................................................................................... 3-7
3–5 .................................................................................................................................................... 3-13
4–1 Roles for Delegating Administration ...................................................................................... 4-2
5–1 Data Sources for Oracle Access Management ....................................................................... 5-1
5–2 Data Sources for Oracle Access Management Services........................................................ 5-2
5–3 Components That Use Identity Stores .................................................................................... 5-8
5–4 User Identity Store Elements.................................................................................................... 5-9
5–5 Access Manager Keys and Storage....................................................................................... 5-32
5–6 Keystores for Access Manager and Security Token Service............................................. 5-32
6–1 Conditions Requiring Server Restart ...................................................................................... 6-4
6–2 OAM Server Instance Settings ................................................................................................. 6-6
6–3 OAM Proxy Settings for an Individual OAM Server ........................................................... 6-6
6–4 Default Coherence Settings for Individual OAM Servers.................................................... 6-7
7–1 Logging Files............................................................................................................................... 7-2
7–2 Logging Defaults........................................................................................................................ 7-2
7–3 Oracle Access Management Server-Side Component Loggers........................................... 7-3
7–4 Oracle Access Management Shared-Service Engine Component Loggers ....................... 7-4
7–5 Oracle Access Management Foundation API Component Loggers................................... 7-4
7–6 Mapping of ODL to Java Levels .............................................................................................. 7-5
7–7 Oracle Security Token Service and Identity Federation Loggers ....................................... 7-9
8–1 Oracle Business Intelligence Enterprise Edition Reports for OAM.................................... 8-5
8–2 Access Manager Administrative Audit Events ..................................................................... 8-6
8–3 Access Manager Run-time Audit Events................................................................................ 8-9
8–4 REST Run-Time Audit Events............................................................................................... 8-12
8–5 Mobile and Social Run-Time Audit Events......................................................................... 8-12
8–6 Categories of Audit Events for Identity Federation........................................................... 8-14
8–7 Identity Federation Session Management Events.............................................................. 8-14
8–8 Protocol Flow Events for Identity Federation..................................................................... 8-15
8–9 Server Configuration Identity Federation........................................................................... 8-15
8–10 Security Events for Identity Federation............................................................................... 8-16
8–11 Security Token Service Configuration Management Operations .................................... 8-17
8–12 Security Token Service-specific Run-time Events.............................................................. 8-19
8–13 Audit Configuration Elements.............................................................................................. 8-23
9–1 Logging Levels ........................................................................................................................... 9-2
9–2 Log Configuration File Names for Components................................................................... 9-5
9–3 Log Writers .............................................................................................................................. 9-10
9–4 Global Parameters in the First Compound List.................................................................. 9-11
9–5 Factors that Determine Whether Logging Is Active .......................................................... 9-16
9–6 Mandatory Log Configuration File Parameters ................................................................. 9-17
9–7 Log Data File Configuration Parameters............................................................................. 9-18
9–8 ParamName Values You Can Configure for Per-Module Logging Threshold.............. 9-23
10–1 Accounts_Locked_Out Report Fields .................................................................................. 10-3
xlix
10–2 Authentication_statistics Report Fields ............................................................................... 10-3
10–3 AuthenticationFromIPByUser Report Fields...................................................................... 10-4
10–4 AuthenticationPerIP Report Fields ...................................................................................... 10-4
10–5 AuthenticationStatisticsPerServer Report Fields ............................................................... 10-4
10–6 All Errors and Exceptions Report Fields ............................................................................. 10-5
10–7 Authentication Failures Report Fields................................................................................. 10-5
10–8 Authentication History Report Fields.................................................................................. 10-5
10–9 Authorization History Report Fields ................................................................................... 10-6
10–10 Multiple Logins From Same IP Report Fields..................................................................... 10-6
11–1 OAM Server Metrics: Server Processes Overview Tab ..................................................... 11-3
11–2 OAM Server Metrics: Session Operations ........................................................................... 11-4
11–3 OAM Server Metrics: Server Operations Tab ..................................................................... 11-5
11–4 OAM Proxy Metrics.............................................................................................................. 11-10
11–5 OAM Proxy Tuning Parameters ......................................................................................... 11-11
11–6 OpenSSO Proxy Server Events............................................................................................ 11-13
11–7 OpenSSO Proxy Metrics: Server ......................................................................................... 11-13
11–8 OpenSSO Proxy Metrics: Agent.......................................................................................... 11-14
12–1 Farm Page Sections ................................................................................................................. 12-4
12–2 Resulting Pages for Selected Nodes and Targets ............................................................... 12-8
12–3 Summary of Performance Overviews in Fusion Middleware Control......................... 12-10
12–4 Access Manager Component Metrics ................................................................................ 12-13
12–5 STS Component-Specific Metrics........................................................................................ 12-14
12–6 Status and Controls on Performance Summary Pages.................................................... 12-15
12–7 OAM Log Availability and Functions in Fusion Middleware Control......................... 12-20
12–8 Log Levels Tab on Log Configuration Page...................................................................... 12-22
12–9 Log Files Elements ................................................................................................................ 12-26
12–10 OAM Log Message Search Controls in Fusion Middleware Control............................ 12-29
12–11 System MBean Browser ....................................................................................................... 12-34
12–12 MBeans that Access Manager and Security Token Service Deploy............................... 12-34
12–13 System MBean Browser ....................................................................................................... 12-36
13–1 Access Manager Settings: Load Balancer ............................................................................ 13-2
13–2 Server Error Mode .................................................................................................................. 13-3
13–3 Error Trigger Condition, Modes, and Message Codes...................................................... 13-4
13–4 External Error Codes, Trigger Conditions, and Recommended Messages.................... 13-4
13–5 Access Manager Settings: SSO .............................................................................................. 13-6
13–6 Summary: Simple and Cert Mode........................................................................................ 13-7
13–7 Server Common OAM Proxy Secure Communication Settings....................................... 13-8
13–8 Policy Evaluation Caches..................................................................................................... 13-10
14–1 Agent Types............................................................................................................................. 14-2
14–2 Agent Registration and SSO Support................................................................................... 14-3
14–3 Run Time Processing Overview for Access Manager........................................................ 14-4
14–4 Keys and Policies Generated During Agent Registration................................................. 14-6
14–5 Artifacts Associated with Agent Registration .................................................................... 14-7
14–6 Copying Generated Artifacts ................................................................................................ 14-7
14–7 Remote Registration Methods............................................................................................... 14-8
14–8 Remote Registration Does Not Support .............................................................................. 14-8
14–9 Agent Registration and Configuration Update Artifacts................................................ 14-10
15–1 Elements on Create Pages for 11g and 10g OAM Agents................................................. 15-3
15–2 User-Defined WebGate Parameters ..................................................................................... 15-6
15–3 Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages..... 15-16
15–4 Agent Search Controls.......................................................................................................... 15-21
15–5 Environment Variables to Set within oamreg................................................................... 15-25
15–6 Remote Registration Command Arguments: mode ........................................................ 15-25
15–7 Remote Registration Command Samples.......................................................................... 15-25
15–8 Common Elements in Remote Registration Requests ..................................................... 15-26
l
15–9 Remote Registration Request Templates for OAM Agents ............................................ 15-29
15–10 Elements in Extended OAM Agent Remote Registration Requests.............................. 15-30
15–11 Variables Required for Remote Registration .................................................................... 15-33
15–12 Files Returned by in-band Administrator to out-of-band Administrator .................... 15-35
15–13 Remote Agent Update Modes and Input Files ................................................................. 15-37
15–14 Delta: OAM Agent Update versus Registration Request................................................ 15-37
16–1 Session Lifecycle States .......................................................................................................... 16-3
16–2 Session Checks for State Changes......................................................................................... 16-4
16–3 Session Removal...................................................................................................................... 16-4
16–4 Application Domain-Specific Overrides.............................................................................. 16-5
16–5 Session Content: Single Authentication Scheme................................................................ 16-7
16–6 Session Outcomes: Multiple Authentication Schemes ...................................................... 16-8
16–7 Global Session Settings........................................................................................................... 16-9
16–8 Application-Specific Session Timing Overrides............................................................... 16-10
16–9 Session Management Controls and the Results Table..................................................... 16-12
17–1 Multi-Data Center Policy Configurations for Idle Timeout ........................................... 17-19
17–2 Session Synchronization and Failover Scenarios ............................................................. 17-20
18–1 MDC Use Cases....................................................................................................................... 18-2
18–2 oamMDC.properties Properties.......................................................................................... 18-11
18–3 partnerInfo.properties Properties....................................................................................... 18-13
19–1 Replication States .................................................................................................................... 19-3
19–2 Modifying Replication Agreement Properties.................................................................. 19-14
21–1 Summary: SSO Components ................................................................................................. 21-2
21–2 Introduction to SSO Implementations ................................................................................. 21-3
21–3 Access Manager Global, Shared Policy Components........................................................ 21-8
21–4 Access Manager Policy Components................................................................................... 21-9
21–5 Condition Types.................................................................................................................... 21-13
21–6 SSO Cookies........................................................................................................................... 21-14
22–1 Comparison: Resource Types for Access Manager versus 10g........................................ 22-3
22–2 Resource Type Definition ...................................................................................................... 22-5
22–3 Host Identifiers Examples...................................................................................................... 22-8
22–4 Host Identifier Definitions................................................................................................... 22-15
22–5 Comparing the DCC and ECC............................................................................................ 22-20
22–6 Native Authentication Modules ......................................................................................... 22-24
22–7 Native Kerberos Authentication Module Definition....................................................... 22-25
22–8 Native LDAP Authentication Modules Definition .......................................................... 22-26
22–9 X509 Authentication Module Definition ........................................................................... 22-27
22–10 Simple Form versus Multi-Step Authentication............................................................... 22-31
22–11 General tab............................................................................................................................. 22-33
22–12 Add New Step Entries, Steps Results Table, and Details Section.................................. 22-34
22–13 Parameter Details for Various Plug-ins ............................................................................. 22-35
22–14 Steps Orchestration Tab....................................................................................................... 22-39
22–15 X509 Step Details (KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT) ...................... 22-44
22–16 Steps and Plug-ins in a Customized Step-up Authentication Module ......................... 22-51
22–17 Managing Custom Plug-ins Actions .................................................................................. 22-60
22–18 Plugins Status Table.............................................................................................................. 22-61
22–19 Example of Plugin Details Extracted from XML Metadata File..................................... 22-62
22–20 Authentication Scheme Definition ..................................................................................... 22-65
22–21 Pre-configured Authentication Schemes........................................................................... 22-68
22–22 Challenge Parameters in Pre-configured Schemes .......................................................... 22-75
22–23 User-Defined Challenge Parameters for Authentication Schemes................................ 22-76
22–24 Advanced Rules Attributes ................................................................................................. 22-84
22–25 Sample Advanced Rules ...................................................................................................... 22-85
22–26 Request Context Data........................................................................................................... 22-86
22–27 Location Context Data.......................................................................................................... 22-87
li
22–28 Session Context Data............................................................................................................ 22-87
22–29 User Context Data................................................................................................................. 22-87
22–30 Challenge Parameters for 10g/11g Encrypted Cookies .................................................. 22-88
22–31 Resource Webgate Support of POST Data Preservation and Restoration.................... 22-90
22–32 Credential Collector Support for POST Data Handling.................................................. 22-91
22–33 Authentication Schemes Supporting POST Data Handling........................................... 22-92
22–34 Parameters Required for Authentication POST Data Handling.................................... 22-92
22–35 ECC and DCC: Long URL Handling ................................................................................. 22-96
22–36 Authentication Schemes Supporting Long URL Handling ............................................ 22-96
22–37 Parameters Required for Long URL Handling................................................................. 22-96
23–1 Login Processing with Access Manager-Protected Resources ......................................... 23-3
23–2 DCC Deployment Support .................................................................................................... 23-6
24–1 Password Policy Configuration Parameters ....................................................................... 24-3
24–2 Password Policy Elements..................................................................................................... 24-4
24–3 Specifying Credential Collectors and Related Forms for Authentication ...................... 24-6
24–4 Credential Collector Password Pages.................................................................................. 24-9
24–5 Password Management Forms and Functions ................................................................... 24-9
24–6 Location of Oracle-provided LDIFs for LDAP Providers............................................... 24-13
24–7 Key Password Attributes in a Password Policy ............................................................... 24-14
24–8 User Password Step Details................................................................................................. 24-17
24–9 Included LDIF Schema Files................................................................................................ 24-25
25–1 Resource Definition Elements............................................................................................. 25-15
25–2 HTTP Resources Sample URL Values................................................................................ 25-18
25–3 Supported Wildcards in Resource URL Patterns (Precedence Order).......................... 25-19
25–4 Sample Resource URLs ........................................................................................................ 25-21
25–5 Pattern Matching for Requested URLs .............................................................................. 25-22
25–6 Query String Matching: Examples ..................................................................................... 25-23
25–7 Resource Evaluation Outcomes.......................................................................................... 25-26
25–8 Search Elements for a Resource in an Application Domain ........................................... 25-29
25–9 Authentication Policy Elements and Descriptions........................................................... 25-32
25–10 Authorization Policy Elements and Descriptions ............................................................ 25-36
25–11 Authorization Policy Condition Tab.................................................................................. 25-42
25–12 Add Condition Window Elements..................................................................................... 25-44
25–13 Add identities Elements....................................................................................................... 25-47
25–14 Add Search Filter Elements................................................................................................. 25-48
25–15 LDAP Search Filter Examples for Access Manager ......................................................... 25-49
25–16 Temporal Condition Details................................................................................................ 25-55
25–17 Access Conditions that Require Attribute-Type Conditions.......................................... 25-56
25–18 Attribute Condition Elements............................................................................................. 25-57
25–19 Attribute Names for Request Built-ins .............................................................................. 25-58
25–20 Attribute Names for Session Built-ins................................................................................ 25-58
25–21 Attribute Condition Data (Aggregation of Conditions).................................................. 25-59
25–22 Authorization Policy Rules Elements ................................................................................ 25-62
25–23 Rule Tab in Expression Mode ............................................................................................. 25-64
25–24 Operators for Expressions in Authorization Rules.......................................................... 25-64
25–25 Response Elements ............................................................................................................... 25-69
25–26 Namespace Request Variables for Single Sign-On........................................................... 25-71
25–27 Namespace Session Variables for Single Sign-On............................................................ 25-71
25–28 Namespace User Variables.................................................................................................. 25-71
25–29 Simple Responses and Descriptions................................................................................... 25-72
25–30 Complex Responses.............................................................................................................. 25-73
25–31 Fresh OSSO Installation: Protected Policy Response (Header)...................................... 25-75
25–32 Remote Policy Management Modes, Templates, and Flags ........................................... 25-78
25–33 Remote Management Template Elements......................................................................... 25-81
26–1 User Interactions: Tester Console Mode versus Command Line Mode Operations .... 26-7
lii
26–2 Access Tester Supported System Properties....................................................................... 26-9
26–3 Access Tester Console Panels.............................................................................................. 26-13
26–4 Command Buttons in Access Tester Panels...................................................................... 26-14
26–5 Additional Access Tester Buttons....................................................................................... 26-14
26–6 Access Tester Menus............................................................................................................. 26-15
26–7 Connection Panel Information............................................................................................ 26-17
26–8 Protected Resource URI Panel Fields and Controls......................................................... 26-19
26–9 Access Tester User Identity Panel Fields and Controls................................................... 26-21
26–10 Access Tester Capture Request Options............................................................................ 26-26
26–11 Generate Script Command .................................................................................................. 26-27
26–12 Test Script Control Parameters ........................................................................................... 26-28
26–13 Run Test Script Commands................................................................................................. 26-29
26–14 Mismatched Results Reasons in the Statistics Document ............................................... 26-32
27–1 Centralized Logout Circumstances...................................................................................... 27-2
27–2 Logout Details After Registration (ObAccessClient.xml) ................................................. 27-3
28–1 Features: OpenSSO Agents with Access Manager............................................................. 28-2
28–2 OpenSSO Policy Migration.................................................................................................... 28-3
28–3 OpenSSO Reliance on Access Manager ............................................................................... 28-5
28–4 Access Manager Processing with OpenSSO ....................................................................... 28-8
28–5 Elements on the New OpenSSO Agent Page.................................................................... 28-11
28–6 Relocating OpenSSO Artifacts ............................................................................................ 28-12
28–7 Expanded OpenSSO Agent Registration Elements.......................................................... 28-15
28–8 OpenSSO Request Files for Remote Registration............................................................. 28-22
28–9 OpenSSO Agent Remote Registration Request ................................................................ 28-23
28–10 J2EE Request File Mappings to the Properties File.......................................................... 28-24
28–11 Mapping the Web Request File to the Properties File ..................................................... 28-25
28–12 Delta: OpenSSO Remote Registration versus Remote Updates..................................... 28-27
28–13 Other OpenSSO Information in this Guide....................................................................... 28-29
29–1 OSSO Agents with Access Manager .................................................................................... 29-2
29–2 11g Access Manager SSO versus OSSO 10g Component Summary ............................... 29-3
29–3 Create OSSO Agent Page Elements...................................................................................... 29-7
29–4 Relocating OSSO Artifacts..................................................................................................... 29-8
29–5 Expanded OSSO Agent Elements......................................................................................... 29-9
29–6 OpenSSO Request Files for Remote Registration............................................................. 29-12
29–7 OSSO-Specific Elements in a Remote Registration Request........................................... 29-13
29–8 Delta: OSSO Remote Registration versus Remote Updates ........................................... 29-15
29–9 Other OSSO Information in this Guide ............................................................................. 29-18
30–1 Installation Comparison with 10g WebGates ..................................................................... 30-4
30–2 Comparison: Access Manager 11g versus 10g.................................................................... 30-6
30–3 Comparing Access Manager 11g Policy Model versus 10g.............................................. 30-8
30–4 Preparing for 10g WebGate Installation with Access Manager 11g.............................. 30-14
30–5 Sample end_url Parameter Specifications......................................................................... 30-26
33–1 IIS 7 Webgate Windows Server 2008.................................................................................... 33-6
35–1 Adaptive Authentication Plugin Properties ....................................................................... 35-8
35–2 Server Side Configuration for Adaptive Authentication Service .................................... 35-9
36–1 Location URL Parameter Definitions................................................................................... 36-2
36–2 Offline Configuration URL Parameters............................................................................... 36-3
37–1 Supported SAML 2.0 NameID Formats............................................................................... 37-7
37–2 SAML 2.0 URLs for Identity Federation Acting As Identity Provider............................ 37-9
37–3 SAML 2.0 URLs for Identity Federation Acting as Service Provider.............................. 37-9
37–4 Supported SAML 1.1 NameID Formats............................................................................. 37-10
37–5 SAML 1.1 URLs for Identity Federation Acting As Identity Provider.......................... 37-11
37–6 SAML 1.1 URL for Identity Federation Acting as Service Provider.............................. 37-11
37–7 OpenID 2.0 URLs for Identity Federation Acting As Identity Provider....................... 37-13
37–8 OpenID 2.0 URLs for Identity Federation Acting as Service Provider ......................... 37-13
liii
37–9 Configuring Identity Federation Settings.......................................................................... 37-14
37–10 Implementing Identity Federation .................................................................................... 37-14
38–1 Default Partner Profiles.......................................................................................................... 38-2
38–2 Identity Provider Partner Settings........................................................................................ 38-4
38–3 Attributes for Google OpenID Partner ............................................................................... 38-7
38–4 Attributes for Yahoo OpenID Partner................................................................................. 38-8
38–5 Elements Used for IdP Provider Search ............................................................................. 38-9
38–6 Service Provider Partner Settings....................................................................................... 38-10
38–7 Sample SP Attribute Mappings........................................................................................... 38-13
38–8 Attribute Mapping Value Expressions .............................................................................. 38-13
38–9 Sample IdP Attribute Mappings......................................................................................... 38-15
38–10 Default Federation Authentication Method and Access Manager Authentication Scheme
Mappings 38-16
38–11 Configuration Parameters for Attribute Sharing Plug-in ............................................... 38-22
38–12 Session Attributes Accessible To Attribute Sharing Plug-in .......................................... 38-22
39–1 Federation Settings in the Console ....................................................................................... 39-2
39–2 General Federation Settings .................................................................................................. 39-3
39–3 Federation Proxy Settings...................................................................................................... 39-4
39–4 Keystore Settings for Federation........................................................................................... 39-5
40–1 FederationScheme Element Definitions............................................................................... 40-2
40–2 FederationPlugin Steps .......................................................................................................... 40-4
40–3 Orchestration of FederationPlugin...................................................................................... 40-4
40–4 OIFScheme Definition ............................................................................................................ 40-7
40–5 OIFMTLDAPPlugin Steps ..................................................................................................... 40-8
40–6 Policy Response Elements ................................................................................................... 40-10
40–7 Message Attribute Mapping................................................................................................ 40-22
40–8 Office 365 Service Provider Attribute Values ................................................................... 40-22
41–1 Security Token Service 11g Infrastructure .......................................................................... 41-3
41–2 Security Token Service Terms............................................................................................... 41-4
41–3 Integrated Oracle Web Services Manager ........................................................................... 41-7
43–1 Security Token Service Settings .......................................................................................... 43-10
43–2 Configuring a Non-Oracle WSM Client for WSS Kerberos Policies.............................. 43-18
44–1 Security Token Service Public Keys Used at Run Time .................................................... 44-2
44–2 Keystore Mbeans..................................................................................................................... 44-2
44–3 Partner Keys for WS-Trust Communications ..................................................................... 44-7
44–4 Conditions for Security Token Service Certificate Validation.......................................... 44-9
44–5 Successful Certificate Validation Requirements................................................................. 44-9
45–1 Search Validation Template .................................................................................................. 45-4
45–2 Issuance Template Requirements......................................................................................... 45-5
45–3 Issuance Template: General Details ..................................................................................... 45-6
45–4 Issuance Properties: Username Token Type....................................................................... 45-6
45–5 Issuance Properties: SAML Token Types............................................................................ 45-8
45–6 Security Details: SAML Tokens ............................................................................................ 45-9
45–7 Issuance Template: Attribute Mapping, SAML Token ................................................... 45-10
45–8 Validation Template Protocols............................................................................................ 45-14
45–9 New Validation Template: General Details ...................................................................... 45-15
45–10 New Validation Template: Authentication Details.......................................................... 45-16
45–11 New Validation Template: Token Mapping ..................................................................... 45-20
45–12 Endpoints Page...................................................................................................................... 45-26
45–13 Conditions tab: Token Issuance Policy .............................................................................. 45-28
45–14 New Custom Token Elements............................................................................................. 45-34
45–15 Custom Tokens Search Elements and Controls................................................................ 45-36
46–1 Security Token Service Partners ........................................................................................... 46-1
46–2 Security Token Service Clients.............................................................................................. 46-2
46–3 Security Token Service Partner Entry .................................................................................. 46-2
liv
46–4 Security Token Service Partner Profile Data....................................................................... 46-2
46–5 Partner Elements for Partner Types ..................................................................................... 46-3
46–6 Elements for Security Token Service Partners.................................................................... 46-4
46–7 Profile: General........................................................................................................................ 46-8
46–8 Requester Profile: Token and Attributes ............................................................................. 46-9
46–9 Relying Party Profile Requirements................................................................................... 46-11
46–10 Token and Attributes Elements: Issuing Authority......................................................... 46-15
46–11 Issuing Authority Token Mapping Elements ................................................................... 46-17
48–1 Features in Mobile and Social Based on the Companion Services Installed .................. 48-3
48–2 Mobile and Non-Mobile Authentication Service Providers in Mobile and Social Services....
48-7
48–3 Android, iOS, and Java Features of the Mobile and Social Services Client SDK........... 48-9
48–4 Token Requirements for the Mobile and Social Server ................................................... 48-20
48–5 Identity Providers That Mobile and Social Natively Supports...................................... 48-23
49–1 Pre-configured Authentication Service Providers ............................................................. 49-6
49–2 Access Manager Authentication Service Provider Default Attributes............................ 49-8
49–3 Webgate Agent for Authentication Service Provider Default Attributes....................... 49-9
49–4 JWT Authentication Service Provider Default Attributes............................................... 49-10
49–5 JWT-OAM Authentication Service Provider Default Attributes ................................... 49-10
49–6 Access Manager Authorization Service Provider Default Attributes ........................... 49-17
49–7 Webgate Agent for Authorization Service Provider Default Attributes ...................... 49-18
49–8 User Profile Service Provider Default Attribute Names and Values ............................ 49-19
49–9 User Profile Service Provider Default Attribute Names and Values ............................ 49-20
49–10 Authentication Service Profile Default General Properties............................................ 49-23
49–11 Token Support and URI Category Information Default Properties .............................. 49-23
49–12 Authorization Service Profile Default General Properties.............................................. 49-24
49–13 User Profile Service Profile Default General Properties.................................................. 49-25
49–14 Security Handler Plug-in General Properties ................................................................... 49-27
49–15 Application Profile General Properties.............................................................................. 49-28
49–16 Service Domain General Properties ................................................................................... 49-30
49–17 Application Profile Selection Properties............................................................................ 49-31
49–18 Service Profile Selection Properties.................................................................................... 49-32
49–19 User Profile Service Protection Properties ........................................................................ 49-33
49–20 Authorization Service Protection Properties .................................................................... 49-33
49–21 OAAM Policies Supported By Mobile and Social............................................................ 49-42
49–22 Mapping Terms Between OAAM and Mobile and Social .............................................. 49-43
50–1 OpenID Protocol Attributes .................................................................................................. 50-4
50–2 OAuth Protocol Attributes .................................................................................................... 50-5
50–3 User Attributes Returned By Google ................................................................................... 50-6
50–4 User Attributes Returned By Yahoo..................................................................................... 50-6
50–5 User Profile Attributes Returned By Foursquare............................................................... 50-7
50–6 User Profile Attributes Returned By Windows Live ......................................................... 50-7
50–7 Service Provider Interface Information Properties .......................................................... 50-12
50–8 Account Linking Properties................................................................................................. 50-19
51–1 Attribute Settings for an Oracle Access Manager 11gR1 PS1 Authentication Service
Provider 51-2
52–1 Default User Profile Services Endpoint Operations ........................................................ 52-14
52–2 User Profile Resource Server - Scope Settings .................................................................. 52-15
53–1 OAuth Service Profile Configuration Attributes................................................................ 53-8
53–2 Web Client Attributes Names and Values ........................................................................ 53-14
53–3 OAuth Service Provider Attributes for Access Manager................................................ 53-19
53–4 User Profile Service Attributes............................................................................................ 53-24
53–5 OAuth Server Settings Attributes....................................................................................... 53-29
53–6 Default OAuth JKS Keystore File and Settings File ......................................................... 53-31
55–1 Identity Context Schema Attributes..................................................................................... 55-4
lv
55–2 Mapping Identity Context Operations ................................................................................ 55-9
56–1 Access Manager Support for RSA Features ........................................................................ 56-2
56–2 RSA Features Not Supported................................................................................................ 56-2
56–3 Installation and Configuration Guidelines ......................................................................... 56-4
57–1 Sample Naming....................................................................................................................... 57-6
58–1 JBoss Agent Composition ...................................................................................................... 58-3
59–1 Component Requirements..................................................................................................... 59-6
59–2 Microsoft Requirements for this Integration....................................................................... 59-7
59–3 Create Web Application Options for Microsoft SharePoint Server............................... 59-11
59–4 Create a Web Application to Host a Site Collection for SharePoint Server.................. 59-13
60–1 Requirements for Impersonation with a Header Variable ............................................... 60-3
62–1 Login Module Stacks for using Header Variables ............................................................. 62-6
62–2 Login Module Stacks for using Header Variables ........................................................... 62-13
63–1 .................................................................................................................................................... 63-3
63–2 .................................................................................................................................................... 63-4
63–3 Ticket Authentication Values................................................................................................ 63-6
A–1 addOAMSSOProvider Command-line Arguments............................................................. A-4
B–1 Languages for Localized Messages ........................................................................................ B-2
C–1 importcert Command Syntax.................................................................................................. C-4
D–1 Comparing IAMSuiteAgent with 11g and 10g Webgates................................................... D-4
lvi
List of Examples
3–1 Certificate Validation Module Configuration...................................................................... 3-10
3–2 Multiple OCSP Responder Configuration ........................................................................... 3-12
7–1 Configuring Access Manager Loggers and Log Handlers.................................................... 7-4
9–1 The Default Log Configuration File with Comments ........................................................... 9-6
9–2 Simple Lists with Global Settings (First Compound List in oblog_config_wg.xml)...... 9-12
9–3 FILTER_LIST Masks Sensitive Attributes in Log Files....................................................... 9-15
9–4 Valid Name/Value List........................................................................................................... 9-15
9–5 Another Valid Name/Value List........................................................................................... 9-15
9–6 Opening tag for a Name/Value List ..................................................................................... 9-16
9–7 Opening tag for a Name/Value List ..................................................................................... 9-16
9–8 A Default Log Configuration File Without Embedded Comments ................................ 9-19
15–1 rreg registration Sample Output.......................................................................................... 15-34
15–2 Updates for the 11g WebGate in mod_wl_ohs.conf ......................................................... 15-45
18–1 DCMaster.properties for Master............................................................................................ 18-4
18–2 DCClone1.properties for Clone ............................................................................................. 18-4
18–3 Sample oamMDCProperty.properties File......................................................................... 18-12
19–1 Default Transformation Rules................................................................................................ 19-9
19–2 Modified PrimaryServerList Transformation Rule........................................................... 19-10
19–3 Modified Transformation Rule for Different Agents........................................................ 19-11
19–4 Replication Rules XML File .................................................................................................. 19-11
26–1 Connection Configuration File............................................................................................. 26-32
26–2 Generated Input Test Script.................................................................................................. 26-33
26–3 Output File Generated During a Test Run......................................................................... 26-35
26–4 Sample Statistics Document ................................................................................................. 26-36
26–5 Execution Log......................................................................................................................... 26-38
30–1 logout.html Script .................................................................................................................. 30-24
38–1 Sample SOAP Attribute Request ......................................................................................... 38-20
38–2 Sample SOAP Attribute Response ...................................................................................... 38-20
42–1 Sample exchange: Request Security Token Sent By the Client ....................................... 42-21
42–2 Request Security Token Response sent by the Security Token Service ......................... 42-22
49–1 Sample merge-creds.xml....................................................................................................... 49-40
53–1 Creating the Keystore............................................................................................................ 53-33
53–2 Loading the Certificates ........................................................................................................ 53-33
53–3 Update jps-config.xml ........................................................................................................... 53-34
53–4 Adding the new Service Instance ........................................................................................ 53-34
53–5 Creating Credential Store Entries........................................................................................ 53-35
55–1 Working with Identity Context Dictionary.......................................................................... 55-9
55–2 Using WLST To Grant Attribute Service Access To Application ................................... 55-10
55–3 Working with Identity Context Runtime ........................................................................... 55-10
55–4 Custom Function Creating Identity Context ..................................................................... 55-15
57–1 oam-config.xml....................................................................................................................... 57-19
59–1 Sample .ASP Page Code........................................................................................................ 59-22
A–1 Sample SSO Configuration for Access Manager ................................................................... A-5
lvii
Preface
This guide provides information on administration and configuration tasks using
Oracle Access Management.
Audience
This document is intended for Administrators who are familiar with:
■Oracle WebLogic Server concepts and administration
■LDAP server concepts and administration
■Database concepts and administration (for policy and session management data)
■Web server concepts and administration
■Webgate and mod_osso agents
■Auditing, logging, and monitoring concepts
■Security token concepts
■Integration of the Policy store, Identity store, and familiarity with Oracle Identity
Management and OIS might be required
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc
.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support
through My Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info
or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
if you are hearing
impaired.
Related Documents
This Preface is for the Oracle Fusion Middleware Administrator's Guide for Oracle Access
Management. It explains how to manage configuration and policies for Access
Manager, Security Token Service, Identity Federation, Access Portal, Mobile and
Social, Adaptive Authentication, Identity Context and other available services. For
more information, see the following documents in the Oracle Fusion Middleware 11g
Release 2 (11.1.2.3) documentation set:
lviii
■Oracle Access Management 11g Release 2 (11.1.2.3) Release Notes
■Oracle Fusion Middleware Installation Guide for Oracle Identity and Access
Management—Explains how to use the Oracle Universal Installer and the
WebLogic Configuration Wizard for initial Access Manager 11g deployment.
Installing 11g WebGates for Access Manager is also covered.
■Oracle Fusion Middleware Developer's Guide for Oracle Access Management—Explains
how to write custom applications and plug-ins to functions programmatically, to
create custom Access Clients that protect non-Web-based resources.
■Oracle Fusion Middleware Upgrade Guide for Java EE—For information about the
types of Java EE environments available in 10g and instructions for upgrading
those environments to Oracle Fusion Middleware 11g.
■Oracle Fusion Middleware Upgrade Guide for Oracle Identity and Access Management
■Oracle Fusion Middleware Migration Guide for Oracle Identity and Access Management
■Oracle Fusion Middleware Performance and Tuning Guide
■Oracle Fusion Middleware Administrator's Guide—Describes how to manage a secure
Oracle Fusion Middleware environment, including how to change ports, deploy
applications, and how to back up and recover Oracle Fusion Middleware. This
guide also explains how to move data from a test to a production environment.
■Oracle Fusion Middleware Enterprise Deployment Guide for Oracle Identity
Management—For a step-by-step guide to deployment.
■Oracle Fusion Middleware High Availability Guide—For high availability conceptual
information as well as administration and configuration procedures for
Administrators, developers, and others whose role is to deploy and manage
Oracle Fusion Middleware with high availability requirements.
■Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and
Access Management—Provides details on customized Identity and Access
Management WLST commands.
■Oracle Fusion Middleware Security and Administrator's Guide for Web
Services—Describes how to administer and secure Web services.
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace
Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
lix
What's New in This Guide?
This chapter describes changes and updates to this book. See the following sections for
details.
■Product Enhancements for Oracle Access Management 11.1.2.3.0
■Product Enhancements for Oracle Access Management 11.1.2.2.0
■Product Enhancements for Oracle Access Management 11.1.2.1.0
■Product Enhancements in Oracle Access Management 11.1.2.0.0
■Product and Component Name Changes with 11.1.2
Product Enhancements for Oracle Access Management 11.1.2.3.0
This list of enhancements has been developed for this Oracle Access Management
11.1.2.3.0 release. Where applicable, links to the documentation are included.
■This Oracle Access Management 11g Release 2 (11.1.2.3) release allows for two
console interfaces. The familiar Oracle Access Management Console has been
updated and streamlined, and a new Access Manager Policy Manager Console,
deployable on a WebLogic Managed Server, has been introduced. Additional
information on the two consoles can be found in Section 2.3, "About the Oracle
Access Management Console and the Policy Manager Console."
■Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
■AP Proxy Application Logon Packaging, see Chapter 54, "Configuring the Access
Portal Service."
■New Administrator Roles, see Chapter 4, "Delegating Administration."
■The Adaptive Authentication Service now offers multifactor authentication in
addition to the standard user name and password. Additional security is enforced
by adding a One Time Password (OTP) or a Push Notification step as a second
factor in the authentication process. It is configured in tandem with the Oracle
Mobile Authenticator mobile app. For details, see Part VIII, "Managing the
Adaptive Authentication Service and Oracle Mobile Authenticator."
■WS-Federation 1.1 support has been implemented in the Federation Service using
WLST commands. See Section 37.6.4, "Using WS-Federation 1.1."
■Mobile and Social
–Mobile Services has been renamed to Mobile and Social Services.
–Mobile and Social Services (Mobile Services) and OAuth Services now use a
direct connection to communicate with OAM. Prior to version 11.1.2.3, Mobile
lx
and Social only communicated with OAM using TCP/IP (that is, remote
mode). Now communication defaults to local, which is faster. Important! If
Mobile and Social is configured to communicate with OAM 10g in your
environment, set the
OAM_LOCAL_MODE
attribute to
false
. For details, see
Section 49.3.1, "Defining, Modifying or Deleting an Authentication Service
Provider" (for Mobile and Social Services) and Section 53.3.4, "Configuring the
Service Provider" (for OAuth Services).
■DCC Enhancements for the following use cases:
–Access Manager SSO flows for all OOTB schemes including forms, basic,
WNA, X509, TOTP, and RSA.
–Unsolicited login where an external custom login page can submit to a DCC
end point instead of the ECC.
–Converged Federation Service flows for both SP and IDP. DCC is capable of
tunneling SAML tokens to Access Manager.
–OAAM step-up flows. DCC is capable of redirecting to OAAM and sending
the user’s context, then tunneling the TAP token back to Access Manager.
–Flows in an MDC set-up.
See Section 22.5, "Understanding Authentication Methods and Credential
Collectors" and Chapter 23, "Understanding Credential Collection and Login."
■Multi-Data Centers documentation has been upgraded and expanded. See Part V,
"Implementing Multi-Data Centers."
■A JSON Web Token Plug-in has been added. See Chapter 22.7.8, "Configuring a
JSON Web Token Plug-in."
■Access to the Forgot Password URL using Access Manager is discussed in
Section 2.9.1, "Administering the Forgot Password URL."
Product Enhancements for Oracle Access Management 11.1.2.2.0
This list of enhancements has been developed for this Oracle Access Management
11.1.2.2.0 release. Where applicable, links to the documentation are included.
■Understanding Multi-Data Centers
■Delegating Administration
■OAuth Service
The Oracle Access Manager OAuth 2.0 Service provides a standards compliant
OAuth 2.0 authorization server with support for both 3-legged and 2-legged
OAuth flows and enables the OAuth 2.0 Client and the OAuth 2.0 Resource Server
roles. It also provides support for mobile OAuth 2.0 clients (such as native
applications on mobile devices) and includes built-in support for mobile
application registration and device identification during the OAM OAuth 2.0
mobile flow ensuring trusted access from mobile devices and built-in server side
single sign-on. It is ideally suited for enterprise scenarios that may require higher
levels of security during an OAuth flow and would benefit from built-in OAM
integrations provided by the OAM OAuth 2.0 service.
■Introduction to Application Domain and Policy Creation
■Administering Identity Federation As An Identity Provider
■Managing Oracle Access Management Oracle Access Portal
lxi
■Understanding the Oracle Access Management Console
Policy Management Enhancements include:
–Right click menu items available for all search result tables
–Duplicate Resources, Authentication Policies, Authorization Policies and
Token Issuance Policies and create new objects using the duplicate (Copy of)
–Search for the Host Identifier from the Resource page
–New Administrator tab in the Application Domain edit screen
–New Advance Rules tab (with Pre-Authentication and Post-Authentication
sub tabs) in Authentication Policy
■For Granular Timeout and cookie-based session management, see Maintaining
Access Manager Sessions
■SHA2 encryption for all WebGate servers
■Configuring Policy Ordering
■Using Application Initiated Authentication
■Understanding Persistent Login (Remember Me)
■Coexistence enhancements
■Support added for Internet Protocol version 6 (IPv6)
Product Enhancements for Oracle Access Management 11.1.2.1.0
The following list outlines the enhancements available with Oracle Access
Management 11.1.2.1.0.
■Newly certified integrations described in:
–Chapter 60: Outlook Web Application (OWA) 2010
–Chapter 61: Microsoft Forefront Threat Management Gateway (TMG) 2010
–Chapter 62: SAP Enterprise Portal v6.0 and v7.0
–Oracle Fusion Middleware Third-Party Application Server Guide for Oracle
Identity and Access Management (WebSphere Portal)
■Authentication POST Data preservation and restoration is explained in:
"Configuring Authentication POST Data Handling" on page 22-90.
■Long URL handling is explained in "Long URL Handling During Authentication"
on page 22-95.
■Step up authentication is described in "Creating and Managing Step-Up
Authentication" on page 22-50.
■Language selection on Login page is described in "Choosing a User Login
Language" on page 2-13.
■Configurable WebGate Request Context Cookie Expiry Time is explained in:
–Table 15–2, " User-Defined WebGate Parameters"
–"OAMRequestContext" on page 21-17
lxii
Product Enhancements in Oracle Access Management 11.1.2.0.0
Oracle Access Management 11.1.2.0.0 provides new functions and enhancements
outlined in following topics.
■November 2012 Book Refresh
■August 2012 Book Refresh
■Access Management Services
■Access Tester
■Attribute Type Authorization Condition
■Deprecation
■Detached Credential Collection
■Dynamic Multi-Factor/Multi-Step Authentication
■Identity Context
■Integration with Third Party Products
■LDAP Search Filters in Identity Conditions
■Leverage SubjectAltName Extension Data/Integrate with Multiple OCSP
Endpoints
■Mobile and Social
■Multiple Identity Store Support
■OpenSSO Support
■Password Policy Management
■Query String Name and Value Parameters in a Resource Definition Pattern
■Resource Type TokenServiceRP for Non-Browser Client-enabled WebGate
■RESTful Services
■Shared Secret Key: Access Client and Software Developer Kit Enhancement
■Token Issuance Policy for Mobile and Social
■Tuning Performance
■User-Defined Parameters: 11g WebGate
November 2012 Book Refresh
The following information has been added or updated:
■Chapter 1: Added "About System Requirements and Certification".
■Chapter 2: Removal (redundant) has altered chapter numbers.
■Chapter 3: Moved password policy, refocused for ECC, into Chapter 16 with other
authentication details.
■Chapter 6: Added descriptions of loggers to:
–Table 7–3, " Oracle Access Management Server-Side Component Loggers"
–Table 7–4, " Oracle Access Management Shared-Service Engine Component
Loggers"
–Table 7–5, " Oracle Access Management Foundation API Component Loggers"
lxiii
■Chapter 12: Re-focused for 11g OAM Agents (WebGates and Access Clients).
■Chapter 13:
–Combined console and remote registration for 11g OAM Agents.
–Moved Configuring 11g WebGates and Authentication Policy for DCC to
chapter 20.
■Chapter 15:
–Added Understanding Credential Collection and Login.
■Chapter 16: Relocated authentication details with other shared policy components:
–Combined console and remote registration for 11g OAM Agents.
–Added "Understanding Credential Collection and Login"
–Refocused and moved from chapter 3: "Managing Global Password Policy"
–Moved "Configuring 11g WebGates and Authentication Policy for DCC" from
chapter 3.
■Chapter 17:
–Added "Understanding Remote Policy and Application Domain
Management".
–Added "Managing Policies and Application Domains Remotely".
■Chapter 20: Relocated OpenSSO Agent registration and management details here.
■Chapter 20: Relocated OSSO Agent registration and management details here.
■Chapter 22: Expanded 10g OAM Agent details to include console and remote
registration updates, and logout with Access Manager.
■Appendix A: Relocated to relevant logout configuration details.
August 2012 Book Refresh
This book has been updated to address reported issues. Global updates include
cosmetic changes and updated screens.
Access Management Services
Several previously separate access products of the Oracle Identity Management
portfolio are combined into one product: Oracle Access Management.
See Also: The following topics are new or updated in this release.
■Table 25–31, " Fresh OSSO Installation: Protected Policy Response
(Header)" for details about obtaining subscriber DN information
from Oracle Internet Directory.
■Table 22–13, " Parameter Details for Various Plug-ins"
■Section 38.3.1, "Creating Remote Identity Provider Partners" for
details about defining OpenID 2.0 IdP partners for federation.
lxiv
Access Tester
The Access Tester can validate the connections in the pool and make cache flush
(SYNC_INFO) requests to be sent over a connection that is already established; instead
of using out-of-band connection for cache flush requests.
Attribute Type Authorization Condition
Authorization conditions enable you to implement dynamic security policies and
resulted in changes to the Policy Configuration interface in the Oracle Access
Management Console:
■Authorization Conditions: The earlier constraint class is renamed as a Condition
Type. Conditions contain no Allow or Deny specification; however, new Rules
specify Allow or Deny access options.
■A new condition type: Attribute.
■Use of Implied Constraints option in policies is replace, allowing you to create
particular condition types by instantiating those and selecting rules.
Deprecation
Standard Authentication Modules (LDAP, Kerberos, and X509) are targeted for
deprecation in future releases. Oracle strongly recommends using native or custom
Plug-ins rather than standard Authentication Modules.
See Also:
■Chapter 1, "Introducing Oracle Access Management"
■Part IV, "Managing Access Manager Settings and Agents"
■Part IX, "Managing Oracle Access Management Identity
Federation"
■Part XI, "Managing Oracle Access Management Mobile and
Social"
■Part XIV, "Using Identity Context"
See Also: Chapter 26, "Validating Connectivity and Policies Using
the Access Tester"
See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40
See Also: "About Attribute Conditions" on page 25-56
See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40
See Also:
■Table 22.7, "Orchestrating Multi-Step Authentication with Plug-in
Based Modules" on page 22-29
■Oracle Fusion Middleware Developer's Guide for Oracle Access
Management if you want to create custom authentication plug-ins.
lxv
Detached Credential Collection
Detached credential collection is an additional capability of the 11g WebGate (OAM
Agent). This is required for secure dynamic multi-factor/multi-step authentication.
You can easily enable the 11g WebGate to use as a DCC; or continue using the
embedded credential collector (ECC) in the OAM Server.
Dynamic Multi-Factor/Multi-Step Authentication
Multi-factor authentication requires a custom authentication plug-in to transmit
information to the back-end authentication scheme several times during the login
process. All information collected by the plug-in and saved in the context will be
available to the plug-in through the authentication process. Context data can also be
used to set cookies or headers in the user's login page.
Identity Context
Identity Context leverages the context-aware policy management and authorization
capabilities built into the Oracle Access Management platform. Identity Context
secures access to resources using traditional security controls (roles and groups) as and
dynamic data established during authentication and authorization (strength, risk
levels, device trust, and so on).
Integration with Third Party Products
Details of integrating Access Manager with third-party products have moved from the
earlier Oracle Fusion Middleware Integration Guide for Oracle Access Manager to this
book. The following integrations are supported:
LDAP Search Filters in Identity Conditions
Access Manager authorization conditions accept a list of users, groups, and LDAP
search filters as part of allowed or denied identities. LDAP search filters provide a
simple way of specifying a target identity population without having to reorganize or
create new groups in the identity store (directory server). This brings to Access
Manager 11g, parity with Oracle Access Manager 10g.
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"
See Also:
■Oracle Fusion Middleware Developer's Guide for Oracle Access
Management
See Also: Chapter 55, "Using Identity Context"
See Also: Part XV, "Integrating Access Manager with Other
Products"
■Chapter 56, "Integrating RSA SecurID Authentication with Access
Manager"
■Chapter 57, "Configuring Access Manager for Windows Native
Authentication"
■Chapter 58, "Integrating JBoss with Access Manager"
■Chapter 59, "Integrating Microsoft SharePoint Server with Access
Manager"
lxvi
Leverage SubjectAltName Extension Data/Integrate with Multiple OCSP
Endpoints
Access Manager support for personal identity verification (PIV) cards (a United States
Federal smart card), is to use FASC-N and EDIPI attributes from the SubjectaltName
extension to map the user during X.509 authentication. While multiple OCSP
providers are not supported, you can use an OCSP Gateway or write a custom
authentication plug-in that uses the OSDT OCSP APIs to validate against multiple
OCSP providers.
Mobile and Social
Mobile and Social serves as an intermediary between a user seeking to access
protected resources, and the back-end Oracle Access Management and Oracle Identity
Management services that protect those resources. Mobile and Social services'
pluggable architecture enables Administrators to add, modify, and remove Identity
and Access Management services without having to update user installed software.
Multiple Identity Store Support
Administrators can install multiple user identity stores for Access Manager. Each
identity store can rely on a different LDAP provider. Each authentication module (or
plug-in within an authentication step) can be configured to use a specific user identity
store.
OpenSSO Support
Access Manager supports Web and Java Agents deployed on Web or J2EE containers.
Each OpenSSO Agent is a filter that is plugged into the container (Oracle WebLogic
Server, JBoss, Apache, and so on) that hosts applications.
Access Manager provides an OpenSSO Proxy to handle requests for resources
protected by OpenSSO Agents. The Oracle-provided OpenSSO Proxy facilitates single
sign-on to OpenSSO Agent-protected applications by enabling communication
between the agent and the OAM Server.
See Also: "About LDAP Search Filter Support in Identity
Conditions" on page 25-47
See Also:
■"Example: Leveraging SubjectAltName Extension Data and
Integrating with Multiple OCSP Endpoints" on page 22-46
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social"
See Also:
■"Using Multiple Identity Stores" on page 5-6
■"Orchestrating Multi-Step Authentication with Plug-in Based
Modules" on page 22-29
See Also:
■Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
■Oracle Fusion Middleware Upgrade Guide for Oracle Identity and
Access Management
lxvii
Password Policy Management
Access Manager enables password policy management through the Oracle Access
Management Console. The global password policy applies to Access Manager users
when the Password Policy Validation Module is implemented. The password policy is
stored within the policy store and applies to all resources protected by Access
Manager.
Query String Name and Value Parameters in a Resource Definition Pattern
The Policy Model supports Query String Name and Value Parameters in a Resource
Pattern Definition:
Resource Type TokenServiceRP for Non-Browser Client-enabled WebGate
A TokenServiceRP type resource represents resources for, and is based on, the Token
Service Relying Party (required for non-browser clients such as Identity Connect).
RESTful Services
Oracle Access Management supports programmatic RESTful services.
Shared Secret Key: Access Client and Software Developer Kit
Enhancement
Custom Access Clients developed using the Access Manager 11g Access Software
Developer Kit support the 11g Shared Secret Key Per Agent (WebGate or Access
Client) security feature. Each agent has its own secret key that is shared between the
Access Client and the OAM Server to encrypt or decrypt the host-based
Access-Client-specific OAMAuthnCookie. Even if one Access Client is compromised,
the impact is limited to that particular Access Client; no other Access Clients are
affected.
Access Manager 11g Pure Java ASDK provides both Oracle Java APIs (in
oracle.security.am.asdk packages) and Oblix Java APIs (in com.oblix.access packages).
Access Manager 11g Pure Java Access Clients:
See Also:
■"Managing Global Password Policy"
■"Configuring 11g WebGates and Authentication Policy for DCC"
See Also:
■"About Query String Name and Value Parameters for Resource
Definitions" on page 25-21
See Also: "Managing TokenServiceRP Type Resources in
Application Domains" on page 45-32
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management
Note: There is no impact to existing 10g ASDK users. Oblix class
wrappers can be modified to create Access Client instances with 10g
mode transparently. However, to operate in 11g compatible mode,
Oracle java APIs should be used.
lxviii
■Communicate with OAM Servers using Oracle Java APIs and either Oracle Access
Protocol version 3 (or version 4 which supports Shared Secret Key Per WebGate
security feature)
■Communicate with 10g Servers using Oblix Java APIs and Oracle Access Protocol
version 3 only (with no support for SSKPA)
Token Issuance Policy for Mobile and Social
A Token Issuance Policy is required for clients for Mobile and Social performing
authentication and authorization.
Tuning Performance
A survey of topics is provided to help tune a deployed Oracle Access Management
environment to ensure optimal performance and stability.
User-Defined Parameters: 11g WebGate
11g WebGate works with browser clients. However, there are cases where a
non-browser (Representational State Transfer (REST) client needs to access HTTP
resources and perform authentication and authorization.
Product and Component Name Changes with 11.1.2
Oracle Access Management provided some product and component name changes, as
shown in the following table.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social" for details about Mobile and Social Authentication Service
See Also: Oracle Fusion Middleware Performance and Tuning
Guide
See Also:
■"About 11g WebGate Functionality for Mobile and Social" on
page 14-5
■Part XI, "Managing Oracle Access Management Mobile and
Social"
■Oracle Fusion Middleware Developer's Guide for Oracle Access
Management
Item In Oracle Access Management 11.1.2 In Oracle Access Management 11.1.1
Services Access Manager
Identity Federation
Security Token Service
Mobile and Social
Identity Context (always enabled)
Access Manager
N/A
Security Token Service
N/A
Agents WebGate (OAM Agent)
Access Client (OAM Agent)
OSSO Agent
OpenSSO Agent
WebGate (OAM Agent)
Access Client (OAM Agent)
OSSO Agent
N/A
lxix
Console Names Oracle Access Management Console Oracle Access Manager Console
Administrators Administrator or Oracle Access Management
Administrator
Oracle Access Manager Administrator
Agent and Application
Domain Registration
Policy Creation
Oracle Access Management Console
Remote registration tool for automated Agent
registration, Application Domain creation with
default security policies.
Oracle Access Manager Console
Remote registration tool
Authorization Conditions and Rules Constraints
Item In Oracle Access Management 11.1.2 In Oracle Access Management 11.1.1
lxx
Part I
Part I
Introduction to Oracle Access Management
Part I provides an introduction to Oracle Access Management. It contains information
on the available services as well as instructions on how to login and start using the
Oracle Access Management Console. This part contains the following chapters.
■Chapter 1, "Introducing Oracle Access Management"
■Chapter 2, "Getting Started with Oracle Access Management"
1
Introducing Oracle Access Management 1-1
1
Introducing Oracle Access Management
[2]
This chapter introduces Oracle Access Management, the enterprise-level security
platform. Oracle Access Management includes Oracle Access Management Access
Manager (Access Manager) and many incorporated services including (but not limited
to) Identity Federation, Mobile and Social, Security Token Service, Identity Context
and Access Portal.
The following sections provide a high-level overview of the Oracle Access
Management architecture and these services.
■Understanding Oracle Access Management Services
■Understanding Oracle Access Management Access Manager
■About Access Manager 11.1.2.3.0
■About System Requirements and Certification
■Understanding Oracle Access Management Installation
1.1 Understanding Oracle Access Management Services
Oracle Access Management is a Java, Enterprise Edition (Java EE)-based
enterprise-level security application that provides a full range of Web-perimeter
security functions and Web single sign-on services including identity context,
authentication and authorization; policy administration; testing; logging; auditing; and
more. It leverages shared platform services including session management, Identity
Context, risk analytics, and auditing, and provides restricted access to confidential
information. Many existing access technologies in the Oracle Identity Management
stack converge in the Oracle Access Management stack as illustrated in Figure 1–1.
Understanding Oracle Access Management Services
1-2 Administrator's Guide for Oracle Access Management
Figure 1–1 Oracle Access Management Overview
Starting with release 11.1.2, Oracle Access Management includes these services.
■Oracle Access Management Access Manager (Access Manager) is described in
"Understanding Oracle Access Management Access Manager" on page 1-3 and the
following parts of this guide.
–Part II, "Managing Common and System Configurations"
–Part III, "Logging, Auditing, Reporting and Monitoring Performance"
–Part IV, "Managing Access Manager Settings and Agents"
–Part VI, "Managing Access Manager SSO, Policies, and Testing"
–Part VII, "Registering and Using Agents with Access Manager"
–Part XV, "Integrating Access Manager with Other Products"
■Oracle Access Management Identity Federation (Identity Federation) provides
cross-domain single sign-on support using open federation protocol standards
such as SAML and OpenID. Beginning with release 11.1.2, Identity Federation has
been incorporated as a part of the Oracle Access Management platform, leveraging
its shared services. This Identity Federation service includes a streamlined user
interface and administration experience. For more information, see the chapters
listed in Part IX, "Managing Oracle Access Management Identity Federation."
■Oracle Access Management Security Token Service (Security Token Service)
provides token validation and generation to facilitate access to services across
security domains and beyond organizational boundaries. Essentially the service
acts as a trust-broker that receives and validates client requests and generates
appropriate tokens for a requested resource. For more information, see the
chapters listed in Part X, "Managing Oracle Access Management Security Token
Service."
■Oracle Access Management Mobile and Social (Mobile and Social) acts as an
intermediary between a user seeking access to protected resources, and the
back-end Identity and Access Management services that protect the resources.
Mobile and Social extends security and compliance to mobile platforms and
simplifies integration with Social Identity services including Facebook and
Google. Mobile and Social RESTful enables Identity and Access Management
Understanding Oracle Access Management Access Manager
Introducing Oracle Access Management 1-3
infrastructure and includes platform-specific developer kits for leading mobile
platforms that enables developers to easily access security services and enable
single sign-on across native and mobile browser-based applications. For more
information, see the chapters listed in Part XI, "Managing Oracle Access
Management Mobile and Social."
■Oracle Access Portal is a hosted single sign-on proxy service that enables intranet
and extranet applications with Oracle's form-fill single sign-on technology. It also
provides REST interfaces that implement the Web Logon Manager end-user web
application as well as custom front-end applications for user-level management of
application credentials via desktop and mobile Web browsers. With the 11.1.2.2
release, Oracle Access Portal has been incorporated into the Oracle Access
Management platform. For more information, see the chapters listed in Part XIII,
"Managing Oracle Access Management Oracle Access Portal."
■The Adaptive Authentication Service is a One Time Password Authenticator that
provides multifactor authentication in addition to the standard user name and
password type authentication. It provides a framework for adding a custom
second factor authentication processor that accepts a PIN from a user. For more
information, see the chapters listed in Part VIII, "Managing the Adaptive
Authentication Service and Oracle Mobile Authenticator."
■OAuth Services allows organizations to implement the open OAuth 2.0 Web
authorization protocol in an Access Manager environment. OAuth Services
enables a client to access resources protected by Access Manager that belong to
another resource owner. An OAuth client can be an application or service created
and controlled by your organization, or it can be an application or service created
and controlled by another organization that requires access to resources protected
by Access Manager. For more information, see the chapters listed in Part XII,
"Managing the Oracle Access Management OAuth Service."
■Identity Context provides context-aware security policy management that enables
Administrators to control the level of security imposed in an application delivery
environment through security frameworks provided by Oracle Identity
Management. For more information, see the chapters listed in Part XIV, "Using
Identity Context".
OpenSSO 8.0 and Sun Access Manager 7.1 have also converged into Oracle Access
Management 11.1.2. For more information, see:
■Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
■Oracle Fusion Middleware Upgrade Guide for Oracle Identity and Access Management
1.2 Understanding Oracle Access Management Access Manager
Oracle Access Management Access Manager (Access Manager) is the former
(standalone) product named Oracle Access Manager. Access Manager provides the
Oracle Fusion Middleware 11g single sign-on (SSO) solution. It operates
independently (as described in this book) but can also operate with the Access
Manager Authentication Provider as described in the Oracle Fusion Middleware
Application Security Guide.
Understanding Oracle Access Management Access Manager
1-4 Administrator's Guide for Oracle Access Management
Access Manager SSO allows users and groups to access multiple applications after
authentication, eliminating the need for multiple sign-on requests. To enable SSO, a
Web server, Application Server, or any third-party application must be protected by a
WebGate (or mod_osso instance) that is registered as an agent with Access Manager.
Administrators then define authentication and authorization policies to protect the
resource. To enforce these authentication policies, the agent acts as a filter for HTTP
requests.
You can also integrate any Web applications currently using Oracle ADF Security and
the OPSS SSO Framework with Access Manager. (See Appendix A, "Integrating Oracle
ADF Applications with Access Manager SSO.") The following sections contain more
details on Access Manager.
■About Components in Access Manager
■Understanding Access Manager Deployments
1.2.1 About Components in Access Manager
Access Manager 11g sits on an instance of Oracle WebLogic Server and is part of the
Oracle Fusion Middleware Access Management architecture. While providing
backward compatibility and co-existence with existing solutions, Access Manager 11g
replaces and converges the earlier technologies Access Manager 10g and Oracle
Application Server SSO (OSSO) 10g. Figure 1–2 illustrates the primary Access
Manager 11g components and services. The Protocol Compatibility Framework
interfaces with OAM WebGates, mod_osso agents, and custom Access Clients created
using the Access Manager Software Developer Kit (SDK).
Note: For information on the differences between Access Manager
11g, 10g and other software, see:
■"Comparing Access Manager 11.1.2 and 10g" on page 30-5
■"Comparing Access Manager 11g SSO versus OSSO 10g" on
page 29-2
■"Introduction to OpenSSO, Agents, Migration and Co-existence"
on page 28-1
Note: WebGates are agents provided for various Web servers by
Oracle as part of the product. Custom access clients, created using the
Access Manager SDK, can be used with non-Web applications. Unless
explicitly stated, information in this book applies equally to both.
Note: This section does not illustrate or discuss all Access Manager
components.
Understanding Oracle Access Management Access Manager
Introducing Oracle Access Management 1-5
Figure 1–2 Access Manager 11g Components and Services
Figure 1–3 illustrates the distribution of Access Manager components.
Figure 1–3 Access Manager 11g Component Distribution
The Oracle Access Management Console resides on the Oracle WebLogic
Administration Server (referred to as AdminServer). WebLogic Managed Servers
hosting OAM runtime instances are known as OAM Servers. Information shared
between the two includes:
■Agent and server configuration data
■Access Manager policies
■Session data (shared among all OAM Servers)
Starting in the 11g Release 2 (11.1.2.3), a Policy Manager Console can optionally be
deployed on the WebLogic Managed Servers. See Section 2.3, "About the Oracle Access
Management Console and the Policy Manager Console" for details.
1.2.2 Understanding Access Manager Deployments
Table 1–1 describes the types of deployments in which Access Manager might be
installed by your enterprise.
Understanding Oracle Access Management Access Manager
1-6 Administrator's Guide for Oracle Access Management
During initial installation and configuration of Access Manager in your deployment,
you create a new WebLogic Server domain (or extend an existing domain). Regardless
of the deployment size or type, in a new WebLogic Server domain, the following
components are installed using the Oracle Fusion Middleware Configuration Wizard.
■WebLogic Administration Server
■Oracle Access Management Console deployed on the WebLogic Administration
Server
■A WebLogic Managed Server for Oracle Access Management services
■Application deployed on the Managed Server
Once the domain is configured, additional details are defined for OAM Servers,
Database Schemas, (optional) WebLogic Managed Servers and clusters, and the
following store types:
■Policy Store: The default policy store is file-based for development and
demonstration purposes, and is not supported in production environments. All
policy operations and configurations are performed directly on the database
configured as the policy store in production environments.
■Identity Store: The default Embedded LDAP data store is set as the primary user
identity store for Access Manager.
■Keystore: A Java keystore is configured for certificates for Simple or
Certificate-based communication between OAM Servers and WebGates during
authorization. The keystore bootstrap also occurs on the initial AdminServer
startup after running the Configuration Wizard.
Table 1–1 Access Manager Deployment Types
Deployment Type Description
Development Deployment Ideally a sandbox-type setting where the dependency on the
overall deployment is minimal
QA Deployment Typically a smaller shared deployment used for testing
Pre-production Deployment Typically a shared deployment used for testing with a wider
audience
Production Deployment Fully shared and available within the enterprise on a daily basis
Note: In an existing WebLogic Server domain, the WebLogic
Administration Server is already installed and operational.
See Also: "Understanding Oracle WebLogic Server Domains" in the
Oracle Fusion Middleware Understanding Domain Configuration for Oracle
WebLogic Server guide provides information about Oracle WebLogic
Server administration domains.
See Also: "Managing the Policy and Session Database" on page 5-29
See Also: "Registering and Managing User Identity Stores" on
page 5-4
See Also: "Managing the Policy and Session Database" on page 5-29
About Access Manager 11.1.2.3.0
Introducing Oracle Access Management 1-7
1.3 About Access Manager 11.1.2.3.0
The following sections provide details on the features available (and not available) in
Access Manager 11.1.2.3.0.
■About the Features Of Access Manager 11.1.2.3.0
■About Features Not In Access Manager 11.1.2.3.0
1.3.1 About the Features Of Access Manager 11.1.2.3.0
Table 1–2 provides an overview of Access Manager 11.1.2. For a list of names that have
changed with 11.1.2, see "Product and Component Name Changes with 11.1.2" on
page lxviii.
Table 1–2 Features in Access Manager 11.1.2
Access Manager 11g Description
Oracle Identity
Management Infrastructure
Enables secure, central management of enterprise identities.
Policy Enforcement Agents Resides with the relying parties and delegate authentication and authorization tasks to OAM
Servers.
■11g OAM Agents, Chapter 15
■10g OAM Agents and the Pre-configured IAMSuiteAgent (10g OAM Agent), Chapter 30
■OpenSSO Agents, Chapter 28
■10g OSSO Agents (mod_osso), Chapter 29
Notes:
Nine Administrator languages are supported.
Unless explicitly stated, the term "Webgate" refers to both an out of the box Webgate or a custom
Access Client.
See Chapter 14 for an introduction to agents.
Server-side components ■OAM Server (installed on a WebLogic Managed Sever),
Console Oracle Access Management Console provides access to all services and configuration details.
See Chapter 2.
Protocols for information
exchange on the Internet
Front channel protocols exchanged between Agent and Server: HTTP/HTTPS.
Back channel protocols: Authenticated clients can perform session operations using enhancements
in the Oracle Access Protocol (OAP).
Proxy Provides support for legacy systems
■OAM Proxy supports legacy Access Manager implementations by acting as a legacy Access
Server.
"Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security" on page 13-6
"Introduction to OAM Proxy Metrics and Tuning" on page 11-10
■OSSO Proxy supports OSSO Agents by acting as the legacy OSSO Server. See Chapter 29.
■Oracle-provided OpenSSO Proxy handles requests for resources protected by OpenSSO
Agents. See Chapter 28.
See Also: About the Embedded Proxy Server and Backward Compatibility and the new Part XIII,
"Managing Oracle Access Management Oracle Access Portal."
About Access Manager 11.1.2.3.0
1-8 Administrator's Guide for Oracle Access Management
Cryptographic keys Note: One key is generated and used per registered mod_osso or 11g Webgate. However, one
single key is generated for all 10g Webgates.
■During 11g agent registration, one per-agent secret key shared is generated for encrypting and
decrypting SSO cookies between 11g Webgate and OAM Server. See Chapter 15.
■During 10g agent registration, a global shared secret key is generated across all of Access
Manager 11g (all Agents and OAM Servers). See Chapter 30.
■During OSSO agent registration, One key per partner shared between mod_osso and OSSO
server. See Chapter 29.
■OpenSSO Agent Host- or Domain-based key stored locally in Agent bootstrap file on the
Agent host. See Chapter 28.
■During OAM Server registration, one server key is generated.
Keys storage ■Agent side: A per-agent key is stored locally in the Oracle Secret Store in a wallet file
■OAM Server side: Per- agent keys, and server keys, are stored in the credential store on the
server side
Encryption / Decryption
(The process of converting
encrypted data back into its
original form)
Introduces client-side cryptography and ensures that cryptography is performed at both the agent
and server ends:
1. Webgate encrypts obrareq.cgi using the agent key.
Note: obrareq.cgi is the authentication request in the form of a query string redirected from
Webgate to OAM Server.
2. OAM Server decrypts the request, authenticates, creates the session, and sets the server
cookie.
3. OAM Server also generates the authentication token for the agent (encrypted using the agent
key), packs it in obrar.cgi with a session token (if using cookie-based session management),
authentication token and other parameters, then encrypts obrar.cgi using the agent key.
Note: obrar.cgi is the authentication response string redirected from the OAM Server to
Webgate.
4. Webgate decrypts obrar.cgi, extracts the authentication token, and sets a host-based cookie.
Policy Store Database in production environments; file-based in demonstration and development
environments, as described in "Managing the Policy and Session Database" on page 5-29.
Applications An application that delegates authentication and authorization to Access Manager and accepts
headers from a registered Agent.
Note: External applications do not delegate authentication. Instead, these display HTML login
forms that ask for application user names and passwords. For example, Yahoo! Mail is an external
application that uses HTML login forms.
SSO Engine Manages the session lifecycle, facilitates global logout across all relying parties in the valid session,
and provides consistent service across multiple protocols. Uses Agents registered with Access
Manager 11g:
■Authentication with the default embedded credential collector occurs across the HTTP
(HTTPS) channel
■Authentication with the optional detached credential collector occurs across the Oracle Access
Protocol (OAP) channel
■Authorization occurs across the Oracle Access Protocol (OAP) channel
See: Chapter 21
Session Management ■Global session specifications are enabled for all Application Domains and resources. In
addition, Application Domain-specific session overrides can be configured.
See Chapter 16.
Policies Registered agents rely on Access Manager authentication, authorization, and token issuance
policies to determine who gets access to protected applications (defined resources).
See: Chapter 25
Client IP ■Maintains this client's age, and includes it in the host-based cookie: OAMAuthnCookie for 11g
Webgate (or ObSSOCookie for 10g Webgate)
Response token replay
prevention
■Include
RequestTime
(the timestamp just before redirect) in obrareq.cgi and copy it to
obrar.cgi (the authentication response string redirected from the OAM Server to Webgate) to
prevent response token replay.
Table 1–2 (Cont.) Features in Access Manager 11.1.2
Access Manager 11g Description
About System Requirements and Certification
Introducing Oracle Access Management 1-9
1.3.2 About Features Not In Access Manager 11.1.2.3.0
Table 1–3 lists several features provided in Access Manager 10g but not included in
Access Manager 11.1.2.
1.4 About System Requirements and Certification
Refer to the system requirements and certification documentation on Oracle
Technology Network (OTN) for information about hardware and software
requirements, platforms, databases, and other information.
The system requirements document covers information such as hardware and
software requirements, minimum disk space and memory requirements, and required
system libraries, packages, or patches:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-requirem
ents-100147.html
The certification document covers supported installation types, platforms, operating
systems, databases, JDKs, and third-party products:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certific
ation-100350.html
Multiple network domain
support
Access Manager 11g supports cross-network-domain single sign-on out of the box.
Oracle recommends you use Oracle Federation for this situation.
Cookies Host-based authentication cookie:
■11g Webgate, One per agent: OAMAuthnCookie_host:port_random_number set by Webgate
using the authentication token received from the OAM Server after successful authentication.
Note: A valid OAMAuthnCookie is required for a session.
■11g Webgate, Transient: OAM_REQ is scoped to the OAM Server. OAM_REQ is set or cleared
by the OAM Server if the Authentication request context cookie is enabled. Protected with
keys known to the OAM Server only. This cookie is configured as a high availability option to
store the state about the user's original request to a protected resource while his credentials
are collected and authentication is performed.
■10g Webgate, One ObSSOCookie for all 10g Webgates.
■One for the OAM Server: OAM_ID, which is scoped to the OAM Server. OAM_ID is
generated by the OAM Server when the user is challenged for credentials and submitted to
the server on every redirect to the server.
See Chapter 21.
Centralized log-out ■The
logOutUrls
(10g Webgate configuration parameter) is preserved. 10g logout.html
requires specific details for Access Manager 11g. See Chapter 30.
■11g Webgate parameters are new:
Logout Redirect URL
Logout Callback URL
Logout Target URL
See Chapter 27.
Table 1–3 Features Not Available In Access Manager 11.1.2
Unavailable or Unsupported Feature
Extensibility framework required for building custom authorization plug-ins.
Authorization for mod_osso-protected resources
Table 1–2 (Cont.) Features in Access Manager 11.1.2
Access Manager 11g Description
Understanding Oracle Access Management Installation
1-10 Administrator's Guide for Oracle Access Management
1.5 Understanding Oracle Access Management Installation
The following sections contain information and links regarding Access Manager
installation and post-installation tasks.
■About Oracle Access Management Installation
■About Oracle Access Management and WebGates
■About Oracle Access Management Post-Installation Tasks
1.5.1 About Oracle Access Management Installation
The Oracle Fusion Middleware Supported System Configurations document provides
certification information on supported installation types, platforms, operating systems,
databases, JDKs, and third-party products related to Oracle Identity Management 11g.
You can access the Oracle Fusion Middleware Supported System Configurations document
by searching the Oracle Technology Network (OTN) Web site using the document
name, or click the link below.
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
Using the Oracle Fusion Middleware Configuration Wizard, the following components
are deployed for a new domain:
■WebLogic Administration Server
■Oracle Access Management Console deployed on the WebLogic Administration
Server (sometimes referred to as the OAM Administration Server, or simply
AdminServer)
■A Managed Server for Oracle Access Management
■An application deployed on the Managed Server
See the Oracle Fusion Middleware Installation Guide for Oracle Identity and Access
Management for details on installation.
1.5.2 About Oracle Access Management and WebGates
OracleAS 10g SSO deployments can be upgraded to use Oracle Access Management
11g SSO. After upgrading and registering OSSO Agents, authentication is based on
Access Manager 11g Authentication Policies. However, only OAM Agents
(WebGates/Access Clients) use Access Manager 11g authorization policies. Over time,
all mod_osso agents in the upgraded environment should be replaced with WebGates
to enable use of 11g authorization policies.
For details about co-existence after the upgrade, see Oracle Fusion Middleware Upgrade
Guide for Oracle Identity and Access Management.
1.5.3 About Oracle Access Management Post-Installation Tasks
Each WebLogic Server domain is a logically related group of Oracle WebLogic Server
resources. WebLogic administration domains include a special Oracle WebLogic Server
instance called the Administration Server. Usually, the domain includes additional
Oracle WebLogic Server instances called Managed Servers, where Web applications
and Web Services are deployed.
During initial deployment, the WebLogic Administrator userID and password are set
for use when signing in to both the Oracle Access Management and WebLogic Server
Understanding Oracle Access Management Installation
Introducing Oracle Access Management 1-11
Administration Console. A different Administrator can be assigned for Oracle Access
Management, as described in "About Oracle Access Management Administrators" on
page 2-3. Administrators can log in and use the Oracle Access Management Console
for the post-installation tasks documented in Table 1–4.
Table 1–4 Oracle Access Management Post-Installation Tasks
Service Requirements
Access Manager Enable Access Manager Service.
Register:
■Data Sources
■OAM Server instances
■Agents for Access Manager
■Application domains and policies that protect resources
Configure:
■Common Settings, including Session-timing
■Certificate Validation
■Common Password Policy
Configure Access Manager Settings.
Identity Federation Enable Identity Federation Service
Configure Federation Settings
Register Identity Provider and Service Provider partners
Security Token Service Enable Security Token Service Service.
Configure Security Token Service Settings.
Register Endpoints
Create Token Issuance and Validation Templates
Register Partner Profiles and Partners
Mobile and Social Enable Mobile and Social Service
Configure Mobile and Social
Understanding Oracle Access Management Installation
1-12 Administrator's Guide for Oracle Access Management
2
Getting Started with Oracle Access Management 2-1
2
Getting Started with Oracle Access
Management
[3]
This chapter describes the initial steps needed to start your servers and log in to the
Oracle Access Management Console. All tasks presume that Oracle Access
Management 11.1.2 is deployed as described in the Oracle Fusion Middleware Installation
Guide for Oracle Identity and Access Management.
This information is organized in the following sections.
■Starting and Stopping Servers in Your Deployment
■About Oracle Access Management Administrators
■About the Oracle Access Management Console and the Policy Manager Console
■Understanding the Oracle Access Management Console
■Logging Into the Oracle Access Management Console
■Using the Oracle Access Management Console
■Configuring with the Command-Line Tools
■Logging, Auditing, Reporting and Monitoring Performance
■Configuring Oracle Access Management Login Options
2.1 Starting and Stopping Servers in Your Deployment
The Oracle Access Management Console is deployed on the WebLogic Administration
Server (AdminServer) thus, Oracle Access Management Administrators can access it
only when the AdminServer is running. If the Oracle Access Management Console is
protected by a WebGate, the OAM Server must also be running. And the Node
Manager must be started before the other servers. The following sections have more
details.
■Starting Node Manager
■Starting and Stopping WebLogic AdminServer
■Starting and Stopping Managed WebLogic Servers and Access Manager Servers
2.1.1 Starting Node Manager
Node Manager is a Java utility that allows you to perform common operations tasks
for a Managed Server, regardless of its location with respect to its Administration
Server. Node Manager must be running before you can start and stop the WebLogic
AdminServer, or WebLogic managed servers hosting OAM Servers.
Starting and Stopping Servers in Your Deployment
2-2 Administrator's Guide for Oracle Access Management
After installing and configuring Oracle Identity Manager, configure the Node
Manager for use with the WebLogic Administration Console (AdminServer) or Oracle
Enterprise Manager Fusion Middleware Control. This configuration is done only once,
as described in "Configuring the Node Manager" in Oracle Fusion Middleware
Administrator's Guide for Oracle Identity Manager.
Following this configuration, ensure that the Node Manager is up by running the
startNodeManager.sh
script. Oracle WebLogic Administration Server does not do this
automatically.
$WLS_HOME/server/bin/startNodeManager.sh
1. Change to your $WLS_HOME/server/bin directory.
2. Enable Start Scripts: Run
setNMProps
to start the stack and instruct Node
Manager to enable the use of start scripts (
StartScriptEnabled=true
):
./setNMProps.sh
3. Start Node Manager:
./startNodeManager.sh
2.1.2 Starting and Stopping WebLogic AdminServer
Starting the WebLogic AdminServer the first time can take 12-15 minutes or more. This
process must not be interrupted or terminated as policy data might be corrupted. The
following procedure describes starting and stopping the WebLogic AdminServer using
the scripts located in your
$DOMAIN_HOME/bin
directory.
■Unix:
startWebLogic.sh
or
stopWebLogic.sh
■Windows:
startWebLogic.cmd
or
stopWebLogic.cmd
1. Navigate to your
$DOMAIN_HOME/bin
.
2. Start AdminServer:
■Unix:
./startWebLogic.sh
■Windows:
run startWebLogic.cmd
3. Stop AdminServer:
■Unix:
./stopWebLogic.sh
■Windows:
run stopWebLogic.
cmd
2.1.3 Starting and Stopping Managed WebLogic Servers and Access Manager Servers
You can perform all start and stop operations for managed WebLogic Servers hosting
Oracle Access Management Servers (OAM Servers) from either a command prompt,
the Oracle WebLogic Server Administration Console, the OAM Policy Manager
See Also: Oracle WebLogic Server Administrator Guide for details.
WARNING: If startWebLogic.cmd (Windows) or startWebLogic.sh
(Linux) is stopped for any reason (whether accidently or because of
a system crash or reboot), policy data might be corrupted. This
would require removal and recreation of the domain and running
the RCU again to recreate the OAM schema.
About Oracle Access Management Administrators
Getting Started with Oracle Access Management 2-3
Console or the Oracle Enterprise Manager Fusion Middleware Control. When using
the command line scripts (located in the
$DOMAIN_HOME/bin
directory), the Managed
Server name and the AdminServer URL are required as input.
The Unix system scripts are
startManagedWebLogic.sh
and
stopManagedWebLogic.sh
,
and the Windows system scripts are
startManagedWebLogic.cmd
and
stopManagedWebLogic.cmd
. The following procedure describes starting and stopping
the OAM Server using the scripts.
1. Navigate to
$DOMAIN_HOME/bin
.
2. Start OAM Server.
■Unix: ./
startManagedWebLogic.sh
MANAGED_SERVER_NAME
ADMIN_SERVER_URL
■Windows: run
startManagedWebLogic.cmd
MANAGED_SERVER_NAME
ADMIN_
SERVER_URL
If the managed server is named oam_server1 and the AdminServer URL is
http://examplewlsadminhost.example.com:7001, the start command run on a Unix
system would be:
startManagedWebLogic.sh oam_server1 http://examplewlsadminhost.example.com:7001
3. Stop OAM Server.
■Unix: ./
stopManagedWebLogic.sh
MANAGED_SERVER_NAME
ADMIN_SERVER_URL
■Windows: run
stopManagedWebLogic.cmd
MANAGED_SERVER_NAME
ADMIN_
SERVER_URL
If the managed server is named oam_server1 and the AdminServer URL is
http://examplewlsadminhost.example.com:7001, the stop command run on a Unix
system would be:
stopManagedWebLogic.sh oam_server1 http://examplewlsadminhost.example.com:7001
2.2 About Oracle Access Management Administrators
A single default LDAP group, the WebLogic Server
Administrators
group, is set in
the Default User Identity Store (Embedded LDAP) designated as the System Store. The
LDAP group, when assigned to a specified user, grants full system and policy
configuration privileges. Specifying a different LDAP group prohibits WebLogic
Administrators from logging in to Oracle Access Management Console or from using
administrative command-line tools.
During initial deployment with the Oracle Fusion Middleware Configuration Wizard,
the System Administrator userID and password are set. These credentials grant access
to the:
■Oracle Access Management Console to register and manage system
configurations, security elements, and policies. See About the Oracle Access
Management Console and the Policy Manager Console for details.
■WebLogic Server Administration Console to view the Summary of Server
Configuration (Cluster, Machine, State, Health, and Listening Port) of deployed
Note: Unless explicitly stated, the term Administrator in this guide
refers to the Oracle Access Management System Administrator.
About the Oracle Access Management Console and the Policy Manager Console
2-4 Administrator's Guide for Oracle Access Management
OAM Servers within the WebLogic Server domain, and also to Start, Resume,
Suspend, Shutdown, or Restart SSL on these servers. See the Oracle Fusion
Middleware Administrator's Guide for more information.
■Custom Administrative command-line tools (including the WebLogic Scripting
Tool and Remote Registration Tool) provide an alternative to the Oracle Access
Management Console for a specific set of functions. See Section 2.7, "Configuring
with the Command-Line Tools" for more information.
Initially, a System Administrator user must log in to the Oracle Access Management
Console using the WebLogic Administrator credentials set during initial configuration.
However, your enterprise might require independent sets of Administrators: one set of
users responsible for Oracle Access Management administration and a different set for
WebLogic administration. For information on this, see Section 4.1, "Understanding
Administrator Roles.".
2.3 About the Oracle Access Management Console and the Policy
Manager Console
This Oracle Access Management 11g Release 2 (11.1.2.3) release allows for two console
interfaces.
■The Oracle Access Management Console is the full-featured graphical interface
deployed on the WebLogic AdminServer. The AdminServer will not display the
Mobile Security Manager (MSM) and Mobile Security Access Server (MSAS) tiles
in the Launch Pads (which will be displayed in the new Access Manager Policy
Manager Console). The Oracle Access Management Console can be accessed at:
http://wlsadminhost.example.com:7001/oamconsole
The Oracle Access Management Console interface has been redesigned for 11g
Release 2 (11.1.2.3). See Understanding the Oracle Access Management Console for
details.
■The Policy Manager Console can be deployed on one or more WebLogic Managed
Servers and does not contain the full functionality available in the Oracle Access
Management Console deployed on the AdminServer. The new Policy Manager
Console has only the policy administration functionality of the familiar Oracle
Access Management Console. It is deployed when using the Oracle Mobile
Security Suite (OMSS) or when more capacity is needed to support many
delegated administrative users of Access Manager policies. The Policy Manager
Console has mobile end points for the Mobile Security Manager (MSM) and
Mobile Security Access Server (MSAS) components of the OMSS and can be
accessed at:
http://wlsadminhost.example.com:14150/access
OAM customers upgrading from R2PS2 who do not plan on using the OMSS can
continue to use the Oracle Access Management Console on AdminServer. OAM
customers (or ex-Bitzer customers) who plan to use OMSS and are upgrading to 11g
Release 2 (11.1.2.3) will need to use the Policy Manager Console but will also need to
log into the AdminServer console to access the:
■Identity Directory Store management interface for OMSS, OAM, APS, OIC
■Certificate Revocation List interface for OAM
■Authentication Plug-ins interface for OAM
Understanding the Oracle Access Management Console
Getting Started with Oracle Access Management 2-5
2.4 Understanding the Oracle Access Management Console
The Oracle Access Management Console is a Web-based program that provides
function controls for system and policy configuration. Oracle Access Management
11.1.2.3 introduces a redesigned Oracle Access Management Console. This new
Console displays a Launch Pad and subsequent pages based on the Administration
Role to which a user is assigned a successful login. It is divided into Launch Pads and
page-level tabs with forms and controls.
Any clicked shortcut appears as a named tab next to the Launch Pad. Each page is
displayed only once. No warning is issued if you attempt to open the same page
multiple times. The tab of the active page is white. Only the active page is visible and
generally provides a work space where you can add, view, or modify related settings.
Up to ten pages (tabs) can be open simultaneously. You can see named tabs for each
page and click the tab to access a page that is concealed. See the following sections for
details on the new Launch Pads.
■About the System Launch Pad
■Accessing the Access Manager Launch Pad
■Accessing the Agents Launch Pad
■Accessing the Help Desk Launch Pad
■Accessing the Self Service Launch Pad
2.4.1 About the System Launch Pad
The System Launch Pad will display when the user name entered is the Oracle Access
Management System Administrator as described in About Oracle Access Management
Administrators. This role has access to all functions and features of the Console
including policy creation, system configuration, and services settings (including
Access Manager, Security Token Service, Identity Federation, Access Portal and the
like). When the System Administrator is logged in, access is granted to five Launch
Pads:
1. Application Security contains the functions generally associated with Oracle
Access Manager and single sign-on (SSO). From this Launch Pad, click the
appropriate link to gain access to agent registration, policy and policy objects
creation, session management, password policy, authentication modules and
plug-ins.
2. Federation contains functions associated with Identity Federation (including links
to configure and manage Identity and Service Providers), the Security Token
Service, Social Identity, OAuth Services and the Access Portal Service.
Note: REST endpoints, WLST and the RREG servlet are available
only on AdminServer.
Note: The Oracle Access Management Console is designed for
optimal display at a resolution of 1024x768.
Note: Some of these services are disabled by default and would need
to be enabled under the Configuration Launch Pad.
Understanding the Oracle Access Management Console
2-6 Administrator's Guide for Oracle Access Management
3. Mobile Security contains functions specific to configuring and managing secure
access to mobile applications and devices. This includes features like Mobile
Security Manager, Mobile Security Access Server, Mobile Authentication and
Mobile OAuth Services.
4. Configuration contains panels for managing the Oracle Access Management
system settings. This includes enabling and disabling available Access services,
configuring user identity stores and settings, certificate validation, server
instances, and granting administrative permissions.
5. Self Service contains panels for managing the user’s preferences and
configurations. This also includes sessions and devices.
Figure 2–1 is a screenshot of the Oracle Access Management System Administrator
Console with the Application Security Launch Pad displayed. This is the default login
view. Note the fours disabled tabs on the top right of the screenshot which, when
clicked, will display the other Launch Pads visible by the System Administrator.
Figure 2–1 Oracle Access Management Administrator Launch Pad
2.4.2 Accessing the Access Manager Launch Pad
The Oracle Access Manager Launch Pad and subsequent functionality will display
when the user name entered is assigned the Application Administrator
(appadminuser) Role as described in Section 4.1, "Understanding Administrator
Roles." This role has access to all functions and features of the Console that includes
policy object creation and policy management. When the Application Administrator is
logged in, access is to the Launch Pads is limited to Access Manager and Automated
Policy Synchronization (APS).
2.4.3 Accessing the Agents Launch Pad
The Agents Launch Pad and subsequent functionality will display when the user
name entered is assigned the Oracle Access Management Agent Administrator Role as
described in Section 4.1, "Understanding Administrator Roles." This role has access to
Logging Into the Oracle Access Management Console
Getting Started with Oracle Access Management 2-7
all functions and features of the Console that include management and configuration
of SSO Agents.
2.4.4 Accessing the Help Desk Launch Pad
The Help Desk Launch Pad and subsequent functionality will display when the user
name entered is assigned the Oracle Access Management Help Desk Administrator
Role as described in Section 4.1, "Understanding Administrator Roles." Users with this
role will land on the
http://wlsadminhost.example.com:7001/oamconsole/faces/helpdesk.jspx page after
logging in. The System Administrator can access this console directly by entering the
URL in the browser. Any one without the Help Desk Administrator role cannot access
this page. If OMSS is disabled, only Session Management will be displayed.
2.4.5 Accessing the Self Service Launch Pad
The Self Service Launch Pad and subsequent functionality will display when any
authenticated user without assigned roles is logged in. The user will land on
http://wlsadminhost.example.com:7001/oamconsole/faces/selfservice.jspx after
logging in. It contains panels for managing the user’s preferences and configurations.
This also includes sessions, and devices (if OMSS is enabled for the user) as illustrated
in Figure 2–2.
Figure 2–2 Self Service Launch Pad
2.5 Logging Into the Oracle Access Management Console
When accessing the Oracle Access Management Console, the WebLogic Server
(AdminServer) host and port must be specified in the URL. Let's assume the following
sample URL, https://wlsadminhost.example.com:7001/oamconsole. In this URL, the
following is true.
■HTTPS represents the Hypertext Transfer Protocol (HTTP) with the Secure Socket
Layer (SSL) enabled to encrypt and decrypt user page requests and the pages
returned by the Web server
■wlsadminhost.example.com refers to fully-qualified domain name of the computer
hosting the Oracle Access Management Console (AdminServer)
■7001 refers to the designated bind port for the Oracle Access Management
Console, which is the same as the bind port used for AdminServer (the WebLogic
Server Administration Console)
Logging Into the Oracle Access Management Console
2-8 Administrator's Guide for Oracle Access Management
■/oamconsole/ refers to the Oracle Access Management Console Log In page
When navigating to the /oamconsole URL, the default Oracle Access Management
Console Log In page is displayed. The following sections have details on logging into
the Oracle Access Management Console.
■Logging Into The Oracle Access Management Console
■Logging Into the Secure Oracle Access Management Console (HTTPS)
2.5.1 Logging Into The Oracle Access Management Console
Use this procedure to log into the Oracle Access Management Console.
1. In a browser window, enter the URL to the Oracle Access Management Console
using the appropriate protocol (HTTP or HTTPS). For example:
https://hostname:admin_server_port/oamconsole/
2. On the Log In page, enter the Oracle Access Management Console Administrator
credentials. For example:
Username: Admin_login_id
Password: Admin_password
Language: English (see "Choosing a User Login Language")
3. Click the Login button.
■Successful: The Oracle Access Management Console Welcome page is
displayed.
■Not Successful: See "Administrator Lockout" on page E-6.
2.5.2 Logging Into the Secure Oracle Access Management Console (HTTPS)
After enabling SSL on the Adminserver and OAM Managed Server, or after
configuring administration port (HTTPS), use the following procedure to add the CA
cert to the libOVD keystore. This will allow logging in without connection issues.
1. Change to the directory that contains the DemoIdentity.jks.
$ cd $MIDDLEWARE_HOME/wlserver_10.3/server/lib/
Note: If you specify an OAM Server host and port (as you would to
access the ODSM console), the AdminServer redirects to the managed
server which produces a 404 Not Found error.
Note: Ensure that you use the correct administrative credential to log
in. Initially, the LDAP group for the Oracle Access Management
Console Administrator is the same as the LDAP group defined for the
WebLogic Server Administration Console (
Administrators
) and the
common Default System User Identity Store store is the WebLogic
Embedded LDAP.
See Also: "About Oracle Access Management Administrators" on
page 2-3
Using the Oracle Access Management Console
Getting Started with Oracle Access Management 2-9
2. Export the CA certificate from the Weblogic keystore using the following
commands.
The
-list
command prints the contents of the keystore for reference.
DemoIdentityKeyStorePassPhrase is the default password for the keystore
DemoIdentity.jks.
$ keytool -list -keystore DemoIdentity.jks
-storepass DemoIdentityKeyStorePassPhrase
$ keytool -exportcert -keystore DemoIdentity.jks
-storepass DemoIdentityKeyStorePassPhrase -alias demoidentity
-file ~/demoidentity.cer
3. Change to the directory that contains the libOVD keystore.
cd $DOMAIN_HOME/config/fmwconfig/ovd/default
4. Import the Weblogic CA certificate to the libOVD keystore.
$ keytool -importcert -keystore adapter.jks -storepass New_Password
-alias demoidentity -file ~/demoidentity.cer
5. Print the contents of the keystore to verify the import.
$ keytool -list -keystore ./adapter.jks -storepass New_Password
6. Add the password for the imported keystore to trustStorePassword in the
server.os_xml file.
vim server.os_xml
server.os_xml: <keystore>keystores/adapters.jks</keystore>
server.os_xml: <trustStore>keystores/adapters.jks</trustStore>
<trustStore>keystores/adapters.jks</trustStore>
<trustStorePassword>New_Password</trustStorePassword/>
7. Change the value of ADMIN_URL in startManagedServer.sh to point to the SSL
port of the Weblogic server.
8. Restart both Adminserver and OAM Managed Server.
9. Log in as documented in Logging Into The Oracle Access Management Console.
2.6 Using the Oracle Access Management Console
The following sections describe common console functionality.
■Signing Out
■Accessing Online Help
■Conducting A Search
2.6.1 Signing Out
The Sign Out link appears in the upper-right corner of the Oracle Access Management
Console. Click the Sign Out link to conclude your session. Oracle recommends that
you also close the browser window after signing out.
Use this procedure to sign out of the Oracle Access Management Console.
Using the Oracle Access Management Console
2-10 Administrator's Guide for Oracle Access Management
1. Expand the drop down list under the name of the user that is logged in and select
Sign Out.
2. Close the browser window.
2.6.2 Accessing Online Help
At any time while using the Oracle Access Management Console, you can click the
Help link located in the drop down menu under the user name at the top of the
Launch Pad page to get more information. Online Help topics link to information in an
online version of this book.
Generally speaking, topics that are displayed by selecting Help in the Oracle Access
Management Console appear in only English and Japanese languages. Online Help is
not translated into the ADMIN languages.
You can click the Welcome tab to display a list of topics that describe actions you can
take. For specific help topics, use the following procedure.
Use this procedure to locate a specific help topic in the Oracle Access Management
Console.
1. From the Oracle Access Management Console, click a tab.
2. Click Help in the drop down menu under the user name in the upper-right corner.
3. Review the page that appears in a new window and select one of the following
links to:
–More—Click this link to view more information.
–How?—Click this link to see steps to perform a task related to your help
search.
–Contents—In the left Help pane, expand Contents to see all help topics as well
as all topics in the online manual.
– Search—Displays a search window where you can enter your help search
criteria.
4. Click the following buttons, as needed:
–View—Displays a set of viewing options.
– Arrows—Return to the previous page or go forward to the next page.
–Printer Icon—Prints the page.
–Envelope Icon—Emails the page.
2.6.3 Conducting A Search
The Oracle Access Management Console provides search controls for specific elements
such as Agents, Application Domains, and Resources. Figure 2–3 is a screen shot of a
Search page used for SSO Agent searches.
Logging, Auditing, Reporting and Monitoring Performance
Getting Started with Oracle Access Management 2-11
Figure 2–3 SSO Agent Search Page
Search pages differ depending on the entity you are trying to find. In all searches, you
can leave a field blank to display everything or use a wildcard (*) character if you do
not know the exact name you seek. Some search controls include the ability to save
your search criteria. From the search results table, you can choose an item to open for
viewing or editing.
2.7 Configuring with the Command-Line Tools
Several command-line tools are available to perform various tasks using the keyboard
rather than the Oracle Access Management Console. After using these commands, the
configurations will be available in the console.
■Remote registration tool,
oamreg
, enables remote registration of Agents, and
creation of default Application Domains.
■Upgrade Assistant (UA) enables you to transfer OSSO 10g configuration to Oracle
Access Management
■Oracle WebLogic Scripting Tool (WLST) provides a number of custom OAM
command-line alternatives for tasks you can perform in the Oracle Access
Management Console.
2.8 Logging, Auditing, Reporting and Monitoring Performance
Logging is the mechanism by which components write messages to a file. These
messages can be logged at different levels of granularity. Oracle Access Management
components use the same logging infrastructure and guidelines as any other
component in Oracle Fusion Middleware 11g. Administrators can monitor
performance and log messages for Access Manager and Security Token Service using
Oracle Fusion Middleware Control.
Note: The search tool is case insensitive.
See Also: Chapter 15, "Registering and Managing OAM 11g Agents"
See Also:
■Oracle Fusion Middleware Upgrade Guide for Oracle Identity and
Access Management
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Configuring Oracle Access Management Login Options
2-12 Administrator's Guide for Oracle Access Management
In Oracle Fusion Middleware, auditing provides a measure of accountability and
answers to the "who has done what and when" types of questions. Oracle Access
Management uses the Oracle Fusion Middleware Common Audit Framework to
support auditing for a large number of user authentication and authorization run-time
events, and administrative events (changes to the system). The Oracle Fusion
Middleware Common Audit Framework provides uniform logging and exception
handling and diagnostics for all audit events. For more information, see Part III,
"Logging, Auditing, Reporting and Monitoring Performance".
2.9 Configuring Oracle Access Management Login Options
The following sections contain information on configuring user login options.
■Administering the Forgot Password URL
■Choosing a User Login Language
■Understanding Persistent Login
2.9.1 Administering the Forgot Password URL
When a user clicks the Forgot Password link on the Oracle Access Management login
page, the user is taken to an Oracle Access Management Forgot Password page where
a new password can be set in the case of a forgotten one. The following sections
contain procedures for administering the Forgot Password URL.
■Setting a Forgot Password URL
■Retrieving a Forgot Password URL
2.9.1.1 Setting a Forgot Password URL
To set a new Forgot Password URL, run the following command:
curl --user weblogic:password
-w "%{http_code}"
-i -H
"Content-Type:application/json"
-H "Accept: */*"
-X PUT -d
'{"forgotPasswordURL":"http://oam-host:7777/identity/faces/forgotpassword"}'
http://host:7001/oam/admin/api/v1/configurationService/forgotPassword
If successful, the "Forgot Password URL configured successfully" message is displayed
in the output. If there is already a URL set for Forgot Password, running the command
overwrites the previous Forgot Password URL.
2.9.1.2 Retrieving a Forgot Password URL
To retrieve the Forgot Password URL, run the following command:
curl --user weblogic:password
-w “%{http_code}” \
-i \
http://host:7001/oam/admin/api/v1/configurationService/forgotPassword
See Also: Oracle Fusion Middleware Performance and Tuning
Guide
Configuring Oracle Access Management Login Options
Getting Started with Oracle Access Management 2-13
2.9.2 Choosing a User Login Language
Oracle Access Management supports language selection through a drop down list of
languages on the login form combined with use of the OAM_LANG_PREF language
preference cookie. Table 2–1 lists the supported languages and applicable language
codes. The Administrators column refers to languages supported by the Oracle Access
Management Console and the Language column refers to languages supported by the
Login Pages. If the language is supported by the Login Page, simply change the
browser's language and users should see a translated page.
Table 2–1 Language Codes For Login Pages
Language Code Language Administrators
ar Arabic
cs Czech
da Danish
de German German
el Greek
en English English
es Spanish Spanish
fi Finnish
fr French French
fr-CA Canadian French
he Hebrew
hr Croatian
hu Hungarian
it Italian Italian
ja Japanese Japanese
ko Korean Korean
nl Dutch
no Norwegian
pl Polish
pt-BR Brazilian Portuguese Brazilian Portuguese
pt Portuguese
ro Romanian
ru Russian
sk Slovak
sv Swedish
th Thai
tr Turkish
zh-CN Simplified Chinese Simplified Chinese
zh-TW Traditional Chinese Traditional Chinese
Configuring Oracle Access Management Login Options
2-14 Administrator's Guide for Oracle Access Management
To accomplish a very specific login experience, implement a custom login page using
the customization facilities in Oracle Access Management as described in Oracle Fusion
Middleware Developer's Guide for Oracle Access Management.
This section provides the following topics:
■Selecting A Language for Oracle Access Management Login
■Understanding the Language Preference Cookie
■Propagating Language Preference and Application Integration
2.9.2.1 Selecting A Language for Oracle Access Management Login
Oracle Access Management provides the language selection methods described in
Table 2–2. The order of these items in the table illustrate the preference order. Use the
configOAMLoginPagePref
WebLogic Scripting Tool (WLST) command to configure the
login page language preferences. Information regarding this WLST command can be
found in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Language preferences are disabled until explicitly enabled. By default, the login form
does not include the list of language values until the application locales are specified.
Note: Prior to the release of 11.1.2.1, Oracle Access Manager relied
on the Browser Language preference (Accept-Language HTTP
Header) to determine the language in which the login page was
rendered. The default, if the language could not determined, was
English (en-us). This behavior is supported going forward until
existing applications have migrated to the 11.1.2.1 model.
Table 2–2 Oracle Access Management Language Selection Methods
Method Description
Server Override Allows the OAM Server to determine the language. It is
intended to support scenarios where the User Agent cannot
reliably indicate its language preference(s) or where the
administrator needs to override other selection mechanisms for
operational reasons.
Preference Cookie A domain cookie (similar to ORA_FUSION_PREFS) that
contains the user's language preferences. It is intended to allow
lang preferences maintained by an application(s) personalization
facilities to be used.
Note: Multiple DNS domain support for the Preference Cookie
is a limitation today. The solution will include Resource
Webgates using the OAM Front-Channel protocol in
combination with local resource cookie enhancements to
manage preference cookie semantics across DNS domains.
See Also: "Understanding the Language Preference Cookie"
Browser Language Allows User Agents (Browsers, REST Clients, HTTP Clients) to
specify the user's language preference via an HTTP
Accept-Language header.
Default Language Used if Oracle Access Management cannot determine the user's
language preference based on the specified selection
mechanisms.
Configuring Oracle Access Management Login Options
Getting Started with Oracle Access Management 2-15
2.9.2.2 Understanding the Language Preference Cookie
The language preference cookie, OAM_LANG_PREF is a domain scoped cookie as
described in Table 2–3.
2.9.2.3 Propagating Language Preference and Application Integration
Oracle Access Management will propagate the language selected by the user to
applications as described in Table 2–4.
Note: Language Selection is only available in the ECC login page; it
is not currently available in the DCC login page.
Table 2–3 OAM_LANG_PREF Cookie
Parameters Description
Name OAM_LANG_PREF
Domain Domain-scoped cookie
Path /
Value [Cookie version] [separator] [UTF-8 BASE64(name-value pairs)]
For example:
v1.0~kqhkiG9w0BAQQFADCB0TELM
ExpirationTime Persistent | Session (default) – Specified in OAM configuration
Secure Flag No
preferredLanguage BCP47/RFC4647. Specifically, the value space should conform to what is
formally called the "language priority list".
defaultLanguageMarker true (reconcile cookie with application maintained preferences) |false
(read from cookie).
Cookie Lifecycle Oracle Access Management and other applications can perform create,
read, update, and delete operations.
Table 2–4 Application Integration for Language Preference
Method Description
HTTP Accept-Language Header This enables application to integration without code change. This is a
major advantage over the other options. We can expect this to be good
for most applications that respond to the browser locale setting. This
is the standard practice in internationalizing a Web application. We
expect this to be able to become the standard option for all ADF based
products, as well as any application that responds to browser locale.
Note: OAM Agents ensure that the Accept-Language reflects the
language selected. Also, ServletFilters could be used to make this
happen.
Access Manager Policy Response Access Manager stores the language selection in the attribute langPref
in the session namespace. For instance:
$session.langPref
.
This attribute can be passed to downstream applications using an
HTTP Header and/or Cookie through the Access Manager Policy
Response. The name of the Header and/or Cookie is a deployment
time assignment.
Preference Cookie When the language selected during login differs from the value stored
in the Preference Cookie, Oracle Access Management will update the
"
preferredLanaguage
" parameter in the Preference Cookie with the
newly selected language and set the defaultLanguageMarker"
parameter to "
false
".
Configuring Oracle Access Management Login Options
2-16 Administrator's Guide for Oracle Access Management
2.9.3 Understanding Persistent Login
With Access Manager, a user needs to re-authenticate after a period of session
inactivity defined by the Idle Timeout parameter (default is 15 minutes) and once the
session expires, due to the value of the Session Lifetime parameter (default is 8 hours).
The Persistent Login functionality offers administrators the option to skip user
re-authentication for a considerably longer period of time should the user opt in -
allowing a user two weeks or a month significantly improves convenience. Persistent
Login (sometimes referred to as Remember Me or Keep Me Signed In) can be enabled
or disabled with the period of time being configurable. It is disabled by default.
Persistent Login is enabled in the
oam-config.xml
global configuration file. The
appropriate Application Domain must also explicitly allow Persistent Login. When
enabled globally, the user login page will have a Keep Me Signed In checkbox and,
when checked, the user receives an RMToken. Once the user's session expires or times
out, a user with an RMToken will not be challenged if the resource is in the
Application Domain that allows Persistent Login and if its authentication level is
adequate. If the user tries to access a resource in an Application Domain that has not
opted in, the user will be challenged for credentials even if the authentication level is
adequate. (If the user does not opt in when logging in, reauthentication will be
prompted after a session expiration or inactive timeout.)
The following behaviors are pertinent to the Persistent Login functionality.
■If enabled for the user logged in to Access Manager from a device browser, closing
and reopening the browser does not require reauthentication within the defined
Persistent Login time period
■Session activities will be reflected in the Audit data.
■When the time period expires, the end user is asked to authenticate again.
■When attempting to access applications from a different device (or even a different
process/browser in the same device), the end user will be asked to authenticate
again.
■When the user clicks log out, the OAM_RM token is deleted and they user must
log in again. Session termination by an administrator will have the same effect.
■As the OAM_RM token is based on credentials entered at the time of token
creation, any event that changes the password status will invalidate the token and
force the user to re-authenticate. This includes:
–Password expiration
–Password reset by administrator
IdentityContext The language preference can be propagated as a custom claim in the
IdentityContext. Select "oracle:idm:claims:session:attributes" as the
claim name and then specify the session attribute using the following
notation: "
preferredLanguage=$session.langPref
.
The claim will be created with the name of
"
oracle:idm:claims:session:attributes:preferredLanguage
" and
value equal to the session's
langPref
attribute.
Note: If the Application Domain 'Session Idle Timeout' is specified,
Persistent Login cannot be enabled.
Table 2–4 (Cont.) Application Integration for Language Preference
Method Description
Configuring Oracle Access Management Login Options
Getting Started with Oracle Access Management 2-17
–Password changed by the user on a different device
–User deleted or locked by the administrator
■To address a stolen device scenario, the administrator can terminate all sessions for
all devices/browsers of a user. The user will need to re-authenticate but has the
option to enable Persistent Login on the login page
■Application triggered re-authentication forces the user to re-authenticate even if
Persistent Login is enabled as the application is intentionally challenging the user
before doing a sensitive operation.
■When a user navigates from an application which allows Persistent Login to one
that does not, although the user is logged in automatically, the application which
does not allow Persistent Login will challenge the user to enter credentials.
■Persistent Login is not available in application triggered login pages.
The following sections have additional details.
■Enabling Persistent Login
■Troubleshooting Persistent Login
2.9.3.1 Enabling Persistent Login
Follow this procedure to enable Persistent Login globally. The feature is not enabled by
default.
1. Connect to WebLogic Server using
connect()
.
Provide the username and password when prompted.
2. Run:
configurePersistentLogin(enable="true", validityInDays="30",
maxAuthnLevel="2", userAttribute="obPSFTID")
3. Create a new Authentication Scheme for Persistent Login using the values in the
following table.
Details can be found in Section 22.9, "Managing Authentication Schemes." The
'Keep me signed in' check box will be displayed only when accessing a resource
protected by this scheme.
4. Click the Application Domains link in the Launch Pad.
Attribute Value
Name PersistentLoginScheme (or any name)
Description any description
Authentication Level 2
Challenge Method FORM
Challenge Redirect URL /oam/server/
Authentication Module LDAPPlugin
Challenge URL /pages/login.jsp
Context Type default
Context Value /oam
Challenge Parameters enablePersistentLogin=true
Configuring Oracle Access Management Login Options
2-18 Administrator's Guide for Oracle Access Management
5. Click the Application Domain for which you will use this PersistentLoginScheme
and change its Authentication Scheme as documented in this sub procedure.
Details are in Section 25.6, "Defining Authentication Policies for Specific
Resources."
a. Click the Authentication Policies tab in the appropriate Application Domain.
b. Change the Authentication Scheme for the Protected Resource Policy to
PersistentLoginScheme. This allows persistent login for this policy.
6. Click the Application Domain under which you will create a Response for all
configured Authorization Policies as documented in this sub procedure.
There may be multiple authorization policies and this needs to be done for all.
Details are in Section 25.13.4, "About Constructing a Policy Response for SSO."
a. Click the Authorization Policies tab in the appropriate Application Domain.
b. One at a time, click an Authorization Policy in this Application Domain to
open its configuration tab.
c. Click Responses.
d. Click Add to create an Authorization Response in the Application Domain.
e. Enter the following values in the displayed Add Response pop-up and click
Add.
Perform this procedure for all Authorization Policies before moving on to the
next step.
7. Access a resource protected by this scheme.
The 'Keep me signed in' checkbox is displayed on the login page.
8. Provide valid credentials and select 'Keep me signed in'.
9. Close and re-open the browser.
10. Access the same resource.
You will be logged in automatically without asking for credentials.
Note: The Public Resource Policy should not be modified.
Attribute Value
Type Session
Name allowPersistentLogin
Value true
NOTE: To disable Persistent Login for an Application Domain you
must disable Authorization Responses by changing the value of the
Value attribute in the Add Response pop-up to false.
Note: Persistent Login can also be enabled and disabled using WLST.
See the Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference for details on the
configurePersistentLogin
command.
Configuring Oracle Access Management Login Options
Getting Started with Oracle Access Management 2-19
2.9.3.2 Troubleshooting Persistent Login
When enabling Persistent Login using WLST, an LDAP attribute named
obpsftid
is
defined to store the Persistent Login properties. When the user is locked, this attribute
needs to be updated but the
oamSoftwareUser
does not have sufficient LDAP rights
over it. Use the following procedure to give oamSoftwareUser permission.
1. Copy the LDIF data below and paste it into a file that you will save as
oam_user_
write_acl_users_obpsftid_template.ldif
.
##############################################################################
# Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
#
# NAME: idm_idstore_groups_acl_template.ldif
#
#
# DESCRIPTION:
#
# This file provides appropriate ACLs to user and group containers.
#
#
# SUBSTITUTION VARIABLES:
#
# %s_UsersContainerDN% : The container in which users reside
# %s_GroupsContainerDN% : The container in which groups reside
#
##############################################################################
dn: %s_UsersContainerDN%
changetype: modify
delete: orclaci
orclaci: access to attr=(obUserAccountControl, obLoginTryCount, obLockoutTime,
oblastsuccessfullogin, oblastfailedlogin, obpasswordexpirydate, obver,
obLastLoginAttemptDate, oblockedon) by
group="cn=orclFAOAMUserWritePrivilegeGroup,%s_GroupsContainerDN%"
(search,read,compare,write) by group="cn=orclFAUserReadPrivilegeGroup,%s_
GroupsContainerDN%" (search,read,compare) by
group="cn=orclFAUserWritePrivilegeGroup,%s_GroupsContainerDN%"
(search,read,compare,write)
-
add: orclaci
orclaci: access to attr=(obUserAccountControl, obLoginTryCount, obLockoutTime,
oblastsuccessfullogin, oblastfailedlogin, obpasswordexpirydate, obver,
obLastLoginAttemptDate, oblockedon, obpsftid) by
group="cn=orclFAOAMUserWritePrivilegeGroup,%s_GroupsContainerDN%"
(search,read,compare,write) by group="cn=orclFAUserReadPrivilegeGroup,%s_
GroupsContainerDN%" (search,read,compare) by
group="cn=orclFAUserWritePrivilegeGroup,%s_GroupsContainerDN%"
(search,read,compare,write)
2. Do the following in the created
oam_user_write_acl_users_obpsftid_
template.ldif
.
■Replace %s_UsersContainerDN% with User Search Base.
■Replace %s_GroupsContainerDN% with Group Search Base.
3. Change to the OID directory and run
ldapmodify
.
$ setenv ORACLE_HOME <OID_INSTALL_LOCATION>
$ cd $ORACLE_HOME/bin
$ ./ldapmodify -h <LDAP server> -p <LDAP port> -D <bind DN> -w <bindpassword>
-v -f oam_user_write_acl_users_obpsftid_template.ldif
Configuring Oracle Access Management Login Options
2-20 Administrator's Guide for Oracle Access Management
Part II
Par t II
Managing Common and System
Configurations
Part II provides information about managing common system-wide configuration
details for Oracle Access Management. This part contains the following chapters.
■Chapter 3, "Managing Common Services and Certificate Validation"
■Chapter 4, "Delegating Administration"
■Chapter 5, "Managing Data Sources"
■Chapter 6, "Managing Server Registration"
3
Managing Common Services and Certificate Validation 3-1
3
Managing Common Services and Certificate
Validation
[4]
This chapter explains how to configure properties that are used in common by the
services integrated into Oracle Access Management.
This chapter contains the following sections:
■Configuring Oracle Access Management
■Enabling or Disabling Available Services
■Managing Common Settings
■Managing Certificate Validation and Revocation
3.1 Configuring Oracle Access Management
This section introduces the Oracle Access Management options and settings
collectively called Configuration. Unless explicitly stated, these Configuration options
are shared by all Access Manager servers and services in the domain. Figure 3–1 shows
the Configuration options defined in the new Oracle Access Management Console.
You can access these settings by clicking Configuration at the top of the Console.
Configuring Oracle Access Management
3-2 Administrator's Guide for Oracle Access Management
Figure 3–1 Oracle Access Management Configuration Options
Table 3–1 describes the Configuration options. The items listed apply to all services in
the suite.
Table 3–1 Configuration Options
Node Description
Available Services See "Enabling or Disabling Available Services" on page 3-3.
User Identity Stores See "Registering and Managing User Identity Stores" in Chapter 5,
"Managing Data Sources."
Administration See Chapter 4, "Delegating Administration."
Certificate Validation Provides access to the certificate revocation list and OCSP/CDP
settings.
See: "Managing Certificate Validation and Revocation" on page 3-7.
Server Instances Provides access to all registered OAM Server instances.
See: Chapter 6, "Managing Server Registration"
Settings > Common
Settings
Provides configurations that apply to all Oracle Access
Management services including Session properties, Oracle
Coherence, Auditing, and Default and System Identity Stores.
See: "Managing Common Settings" on page 3-5.
Settings > Access
Manager
Provides access to Access Manager operation configurations.
See "Managing Common and System Configurations"
Settings > Social Identity Provides access to configurations for the Social Identity features of
Oracle Access Management Mobile and Social.
See "Managing Oracle Access Management Mobile and Social"
Enabling or Disabling Available Services
Managing Common Services and Certificate Validation 3-3
3.2 Enabling or Disabling Available Services
Figure 3–2 shows the Available Services page of the Common Configuration section,
which provides the status of services, and controls to enable or disable a service.
Initially, only Access Manager services are enabled. Oracle Access Management
Administrators must enable a service in the Oracle Access Management Console to use
the related functionality. The exception to this is Identity Context, which is enabled by
default and does not have any controls to disable it.
Figure 3–2 Available Services
Settings > Federation Provides access to configurations for Oracle Access Management
Identity Federation.
See Chapter 38, "Managing Identity Federation Partners,"
Chapter 39, "Managing Settings for Identity Federation" and
Chapter 40, "Managing Federation Schemes and Policies."
Settings > Security Token
Service
Provides access to configurations for Oracle Access Management
Security Token Service.
See "Managing Oracle Access Management Security Token Service"
Settings > Access Portal
Service
Provides access to configurations for Oracle Access Portal.
See "Managing Oracle Access Management Oracle Access Portal"
Table 3–1 (Cont.) Configuration Options
Node Description
Enabling or Disabling Available Services
3-4 Administrator's Guide for Oracle Access Management
A green check mark in the Status field beside the service name indicates the service is
enabled. A red circle with a cross through it indicates that the corresponding service is
disabled.
Follow this procedure to enable or disable an available service. The WebLogic
AdminServer and OAM Server must be running. (For details. see Starting and
Stopping Servers in Your Deployment.)
1. From the Oracle Access Management Console Launch Pad, click Available Services
under Configuration.
2. Click Enable beside the desired service name (or confirm that the Status check
mark is green).
Table 3–2 Common Services
Service Description
Access Manager Access Manager functionality is enabled by default. Access Manager
Service is required to set SSO policies, configure Access Manager, as
well as Common Configuration, and when REST Services are enabled.
Default: Enabled
No other services are required for Access Manager and Common
Configuration.
Adaptive Authentication Service Required for adaptive authentication functionality.
Default: Enabled
See Also: Part VIII, "Managing the Adaptive Authentication Service
and Oracle Mobile Authenticator".
Identity Federation Must be enabled to manage the federation partners.
Default: Disabled
Note: The Access Manager service must also be enabled because
Identity Federation is another authentication module.
See Also: Part IX, "Managing Oracle Access Management Identity
Federation".
Security Token Service Enable this service to use Security Token Service functionality.
Default: Disabled
Access Manager service is not required.
See Also: Part X, "Managing Oracle Access Management Security
Token Service".
Access Portal Service Must be enabled to manage the Access Portal Service.
Default: Disabled
See Part XIII, "Managing Oracle Access Management Oracle Access
Portal"
Mobile and Social Mobile and Social Services can be deployed in either of two ways:
■As part of Oracle Access Management, where Access Manager is
enabled by default and Mobile and Social must be enabled
manually to operate together with Access Manager.
■Oracle Access Management and Mobile and Social only. Here
only Mobile and Social is enabled by default to work on its own
(or use a remote Access Manager).
See Also: Part XI, "Managing Oracle Access Management Mobile and
Social"
Mobile Security Service Required for mobile security functionality, which governs secure
access to mobile applications and devices. This includes features like
Mobile Security Manager, Mobile Security Access Server, Mobile
Authentication and Mobile OAuth Services.
Default: Enabled
See Also: Part XI, "Managing Oracle Access Management Mobile and
Social"
Managing Common Settings
Managing Common Services and Certificate Validation 3-5
3. Click Disable beside the desired service name (or confirm that the Status check
mark is red).
3.3 Managing Common Settings
Common Settings apply to all services within the suite. Figure 3–3 shows the named
sections on the Common Settings page, which can be expanded to reveal related
elements and values.
Figure 3–3 Common Settings Page (Collapsed View)
Oracle Access Management Administrators can control and specify parameters used
by the entire suite, not just a single service, as introduced in Table 3–3.
Table 3–3 Common Settings
Tab Name Description
Session Session configuration refers to the process of managing the lifecycle requirements of
a session, and notification of events to enable global logout. Global logout is
required for OSSO Agents (mod_osso) to ensure that logging out of a session on any
entity propagates the logout to all entities.
Coherence Common Oracle Coherence settings shared by all OAM Servers differ from those
for individual OAM Servers. However, in both cases Oracle recommends that you
make no adjustments to these settings unless instructed to do so by an Oracle
Support Representative.
Audit Configuration Oracle Access Management supports auditing for a large number of administrative
and run-time events, uniform logging and exception handling, and the diagnostics
of all audit events. Oracle Access Management auditing configuration is recorded in
oam-config.xml
.
See Also: "Using the Oracle Access Management Console for Audit Configuration"
on page 8-22.
Default and System
Identity Stores
This section identifies the default identity and system stores, which can be one in
the same (or different).
See Also: Details for other operations common to all OAM
components:
■Chapter 7, "Logging Component Event Messages"
■Chapter 11, "Monitoring Performance and Health"
Managing Common Settings
3-6 Administrator's Guide for Oracle Access Management
The following sections have more information.
■Managing Common Settings
■Viewing Common Coherence Settings
3.3.1 Managing Common Settings
Users with valid Oracle Access Management Administrator credentials can perform
the following task to display the Common Settings page and perform changes. To
manage common settings, the OAM Server must be running. (For details. see Starting
and Stopping Servers in Your Deployment.)
1. At the top of the Console, click Configuration.
2. In the Configuration Launch Pad, select Common Settings from the View menu in
the Settings section.
3. Session:
a. On the Common Settings page, expand the Session section.
b. Click the arrow keys beside each list to increase or decrease session lifecycle
settings as needed:
Session Lifetime (minutes)
Idle Timeout (minutes)
Maximum Number of Sessions per User
c. Database Persistence: Check the box to enable Database Persistence for Active
Sessions (or clear it to disable Database Persistence).
d. Click Apply to submit your changes.
e. See Also: Chapter 16, "Maintaining Access Manager Sessions".
4. Coherence: See "Viewing Common Coherence Settings" on page 3-7.
5. Audit Configuration:
a. Expand the Audit Configuration section.
b. In the Audit Configuration section, enter appropriate details for your
environment:
Maximum (Log) Directory Size
Maximum (Log) File Size
Filter Enabled
Filter preset (select from the list to define verbosity of audit data)
Audit Configuration Table: Use Add (+) or Delete (x) buttons to specify users.
c. Click Apply to submit the Audit Configuration (or close the page without
applying changes).
d. See Also: Chapter 8, "Auditing Administrative and Run-time Events".
6. Default Store and System Stores:
a. Expand the Default and System Identity Stores section.
b. Click the name of the System Store (or Default Store) to display the
configuration page.
Managing Certificate Validation and Revocation
Managing Common Services and Certificate Validation 3-7
c. See Section 5.2.2, "Using the System Store for User Identities" for more
information.
3.3.2 Viewing Common Coherence Settings
Follow this procedure to expand and view the Coherence settings.
1. At the top of the Console, click Configuration.
2. In the Configuration Launch Pad, select Common Settings from the View menu in
the Settings section.
3. On the Common Settings page, expand the Coherence section.
4. Close the page when you finish; do not make any changes.
Figure 3–4 shows the Common Settings page with the Coherence section expanded.
Figure 3–4 Common Coherence Settings
Table 3–4 describes these settings.
3.4 Managing Certificate Validation and Revocation
The Certificate Validation module is used by the Security Token Service to validate
X.509 tokens and to verify whether or not the certificates have been revoked. It
supports the following options.
■A Certificate Revocation List (CRL) is a list of certificates (identified by serial
numbers) that have been revoked. Revoked certificates are listed with a reason, an
issue date, and the issuing entity. (In addition, each list contains a proposed date
for the next release.) Entities presenting these (revoked) certificates should no
longer be trusted. When a potential user attempts to access a server, the server
allows or denies access based on the CRL entry for the particular user. For more
information, see "Enabling the Certificate Revocation List Functionality."
■The Online Certificate Status Protocol (OCSP) was developed as an alternative to
CRLs. OCSP specifies how the client application that requests information on a
certificate's status will obtain it from the server that responds to the request. An
Note: Oracle strongly recommends that you do not alter these
settings without the assistance of Oracle Support.
Table 3–4 Common Coherence Settings
Element Description
Port Value between 1 and 65535 is supported.
Multicast (Cluster) Address Value between 224.1.255.0 to 239.255.255.255 is allowed.
Time to Live (number of hops) Value between 0 and 255 is supported.
Multicast (Cluster) Port Value between 1 and 65535 is supported.
Managing Certificate Validation and Revocation
3-8 Administrator's Guide for Oracle Access Management
OCSP responder can return a signed response signifying that the certificate
specified in the request is either good, revoked or unknown. If the OCSP cannot
process the request, it returns an error code. For more information, see "Enabling
OCSP Certificate Validation" and "Additional OCSP Configurations."
■A CRL Distribution Point extension (CDP extensions) contains information
regarding the location of Certificate Revocation Lists (CRLs) and OCSP servers.
You can use the Administration Console to define these points. For more
information, see "Enabling CRL Distribution Point Extensions."
3.4.1 Enabling the Certificate Revocation List Functionality
Users with Oracle Access Management Administrator credentials can use the
following procedure to enable the CRL functionality and import a current Certificate
Authority Certificate Revocation List (CA CRL). Before beginning, you should have
your CA CRL ready to import.
1. In the Configuration Launch Pad section of the Oracle Access Management
Console, click Certificate Validation.
The Certificate Revocation List tab is displayed.
2. Confirm that the Enabled box is checked.
3. Add or remove a CRL.
■Add: Click the Add (green plus sign) button, browse for the CRL file, select it,
and click Import.
■Remove: Click the name of the list in the table, click the Delete (x) button, and
confirm when asked.
Figure 3–5 is a screenshot of the pop-up window used to add a CA CRL to the
CRL List using the Administrative Console.
Figure 3–5 Certificate Revocation List Dialog Box
4. Click Apply to save the configuration.
Managing Certificate Validation and Revocation
Managing Common Services and Certificate Validation 3-9
5. Proceed to "Enabling OCSP Certificate Validation".
3.4.2 Enabling OCSP Certificate Validation
Users with Oracle Access Management Administrator credentials can use the
following procedure to enable the OCSP. Before you begin, you should have the URL
of the OCSP service ready to import.
1. Under the Configuration section of the Oracle Access Management Console, click
Certificate Validation.
The Certificate Revocation List page is displayed. Confirm that the Enabled box is
checked.
2. Click the OCSP/CDP tab.
a. Enable OCSP.
b. Enter the URL of the OCSP Service.
c. Enter the Subject DN of the OCSP Service.
d. Save this configuration.
Figure 3–6 illustrates how to add an OCSP URL using the Administration Console.
See "Using WLST to Update the OCSP Configuration" for details on how to do this
using the WLST command.
Figure 3–6 OCSP/CDP Settings
3. Proceed to "Enabling CRL Distribution Point Extensions".
3.4.3 Enabling CRL Distribution Point Extensions
Users with Oracle Access Management Administrator credentials can use the
following procedure to add CRL distribution points in issued certificates.
Note: To search for CRLs in the table, enable Query by Example from
the View drop-down. Enter filter strings in the header fields displayed
and hit Enter.
Managing Certificate Validation and Revocation
3-10 Administrator's Guide for Oracle Access Management
1. Under the Configuration section of the Oracle Access Management Console, click
Certificate Validation.
The Certificate Revocation List page is displayed. Confirm that the Enabled box is
checked.
2. Open the OCSP/CDP tab.
a. Enable CDP.
b. Save this configuration.
Figure 3–6 illustrates this.
3.4.4 Additional OCSP Configurations
Support for HTTP Proxy and multiple OCSP Responder configurations have been
added for this 11g Release 2 (11.1.2.3) version of Oracle Access Manager. Example 3–1
illustrates the current Certificate Validation Module configuration.
Example 3–1 Certificate Validation Module Configuration
<Setting Name="CertValidationModule" Type="htf:map">
<Setting Name="certpathvalidationocspcertsubject"
Type="xsd:string"></Setting>
<Setting Name="certpathvalidationocspurl" Type="xsd:string"></Setting>
<Setting Name="certvalidationcrlstorelocation"
Type="xsd:string">/scratch/maymaria/installed/wlsHome/user_projects/
domains/base_domain/config/fmwconfig/amcrl.jar</Setting>
<Setting Name="defaulttrustcastorelocation"
Type="xsd:string">/scratch/maymaria/installed/wlsHome/user_projects/
domains/base_domain/config/fmwconfig/amtruststore</Setting>
<Setting Name="defaulttrustcastoretype" Type="xsd:string">jks</Setting>
<Setting Name="certpathvalidationcdpenabled"
Type="xsd:boolean">false</Setting>
<Setting Name="certpathvalidationcrlenabled"
Type="xsd:boolean">false</Setting>
<Setting Name="certpathvalidationocspenabled"
Type="xsd:boolean">false</Setting>
</Setting>
The following sections contain configuration information for these new features.
■Using WLST to Configure HTTP Proxy
■Using WLST to Update the OCSP Configuration
■Configuring Multiple OCSP Responders
3.4.4.1 Using WLST to Configure HTTP Proxy
The Oracle Access Manager OCSP checker can perform authentication against OCSP
responders that are outside an enterprise's intranet via HTTP Proxy.
Use the
updateHTTPProxyConfig
WLST command to configure the proxy.
3.4.4.1.1 Using the updateHTTPProxyConfig WLST Command Online command that
configures the OAM OCSP checker to use HTTP proxy.
3.4.4.1.2 Description Adds or updates proxy information.
3.4.4.1.3 Syntax
updateHTTPProxyConfig(proxyHost, proxyPort, conTimeOut)
Managing Certificate Validation and Revocation
Managing Common Services and Certificate Validation 3-11
3.4.4.1.4 Example
updateHTTPProxyConfig(proxyHost="hostname.example.com", proxyPort="8888",
conTimeOut="600")
3.4.4.2 Using WLST to Update the OCSP Configuration
Online command that updates the OAM OCSP configuration including:
■Updates or adds an OCSP responder URL and subject details to the
"certpathvalidationocspurltocamap"
■Clear the newly added configuration; for example,
"certpathvalidationocspurltocamap"
■Set or unset the "useJDKOCSP" flag to enable or disable JDK OCSP
3.4.4.2.1 configureOAMOSCSPCertValidation Online command that updates the OAM
OCSP configuration.
3.4.4.2.2 Description Updates the OAM OCSP configuration by adding/modifying the
OCSP responder URL and subject details in the certpathvalidationocspurltocamap
property and enabling/disabling the use of the JDK OCSP Checker.
3.4.4.2.3 Syntax
configureOAMOCSPCertValidation(url, subject, clear (optional),
display (optional), useJDKOCSP (optional))
3.4.4.2.4 Examples The following example enables the OAM OCSP and sets the
Responder URL and subject.
configureOAMOCSPCertValidation(url="http://sample:9898",
subject="cert-subject-detail")
The following example enables the OAM OCSP and updates the Responder URL and
subject.
configureOAMOCSPCertValidation(url="http://sample:9898",
subject="details changed/updated")
The following example disables and clears the OAM OCSP.
configureOAMOCSPCertValidation(url="http://sample:9898", subject="subject-detail",
Argument Definition
proxyHost
Mandatory. The host name of the proxy.
proxyPort
Mandatory. The port number of the proxy.
conTimeOut
Mandatory. The connection timeout in milliseconds.
Argument Definition
url
Mandatory. Takes as a value the valid URL.
subject
Mandatory. Takes the details being modified.
clear
Optional. Takes a value of true or false.
display
Optional. Takes a value of true or false.
useJDKOCSP
Optional. Takes a value of true or false.
Managing Certificate Validation and Revocation
3-12 Administrator's Guide for Oracle Access Management
clear="true")
The following example enables/disables the JDK OCSP.
configureOAMOCSPCertValidation(url="http://sample:9898",
subject="details changed/updated", useJDKOCSP="true")
3.4.4.3 Configuring Multiple OCSP Responders
Certificate authentication currently supports authentication against a single OCSP
responder as documented in "Enabling OCSP Certificate Validation" on page 3-9.
Support for multiple OCSP responders has been added since the responder URL is
now part of the certificate's Authority Information Access Extension. To support
multiple OCSP Responders, the three lines of configuration in Example 3–2, "Multiple
OCSP Responder Configuration" must be added to the top of the Certificate Validation
Module configuration section (illustrated in Example 3–1).
Example 3–2 Multiple OCSP Responder Configuration
<Setting Name="CertValidationModule" Type="htf:map">
<Setting Name="certpathvalidationocspurltocamap" Type="htf:map">
<Setting Name="<url_value>" Type="xsd:string">
<ocsp_responder_subject></Setting>
</Setting>
<Setting Name="useJDKOCSP" Type="xsd:string">false</Setting>
...
</Setting>
Configure the first and second lines to enable multiple OCSP responders.
■Set
certpathvalidationocspenabled
to true.
■Update the
certpathvalidationocspurltocamap
configuration. It is of type Map,
the key is the OCSP Responder URL (URL Encoded) and the value is the OCSP
Responder's Certificate subject.
<Setting Name="certpathvalidationocspurltocamap" Type="htf:map">
<Setting Name=" http%3A%2F%2Flocalhost%3A9797" Type="xsd:string">
emailAddress=sagar@pspl.com,CN=ps2436,OU=OBLIX-QA,O=PSPL,
L=PUNE,ST=MAHA,C=MY</Setting>
</Setting>
■(Optionally) set values for
certpathvalidationocspcertsubject
and
certpathvalidationocspurl
.
The Responder URLs will be fetched first from the AuthorityInformationAccess
extension of the user's X.509 certificate and second from Modules/Plugin
(CertValidation). The Responder Subjects will be fetched first from the defined
configuration map and second from the Module/Plugin (CertValidation)
configuration. In cases where these configurations are not found, the OCSP validation
will fail.
Configure the third line to provide backward compatibility for those who want to use
JDK OCSP validation rather than the new OAM OCSP Checker. By default, the JDK
OCSP Checker is enabled. When configuring the OAM OCSP Checker using the WLST
command, the flag is set to false. For more information on the WLST command, see
Section 3.4.4.2, "Using WLST to Update the OCSP Configuration."
Depending on the Certificate Validation Module configuration there are three different
options as documented in Table 3–5.
Managing Certificate Validation and Revocation
Managing Common Services and Certificate Validation 3-13
To enable OCSP validation to be done using one configured responder URL, set the
certpathvalidationcrlenabled
and
certpathvalidationocspenabled
properties to
true and set values for the
certpathvalidationocspcertsubject
and
certpathvalidationocspurl
properties. If these properties are not set, OCSP
validation will be done using the responder URL defined within the user certificate's
AIA Extension. If no URL is defined, OCSP validation will fail.
Table 3–5
Configuration
OCSP
Configuration
(certpathvalidationo
cspenabled)
CRL Configuration
(certpathvalidation
crlenabled)
JDK/OAM OCSP
Configuration
(useJDKOCSP)
No OCSP Checking
Simple certificate validation
is performed during OAM
X-509 authentication
False False False
OAM OCSP
X-509 authentication
performs certificate
validation with OCSP
checking using the new
OAM OCSP Checker.
True True/False
(does not matter)
False
JDK OCSP
X-509 authentication
performs certificate
validation with OCSP
checking using the JDK
OCSP Checker.
True True True
Managing Certificate Validation and Revocation
3-14 Administrator's Guide for Oracle Access Management
4
Delegating Administration 4-1
4
Delegating Administration
[5]
Delegating administration allows a high-level administrator to grant responsibilities to
other, more local administrators. This is useful in large organizations where it may be
necessary to administer thousands or millions of users. With this release of Oracle
Access Management, a System Administrator can delegate administration of
Application Domains to other administrators. An Application Domain Administrator
role has been developed towards this end.
This chapter contains an overview of delegating administration; in effect, determining
what rights you want to grant to another user. It contains the following sections.
■Understanding Administrator Roles
■Delegating the Identity Store
■Assigning Roles Using the Administration Console
■Using the Container Security Framework and MBeans
■Using the Remote Registration Utility
■Auditing Reports
4.1 Understanding Administrator Roles
After installation, Access Manager has a set of pre-defined roles that can be assigned to
administrators. The Access Manager System Administrator (as described in
Section 2.2, "About Oracle Access Management Administrators") can administer the
following:
■All Application and component policy objects (including Resources,
Authentication Policies, Authorization Policies, and Token Issuance Policies)
■Shared components (including Authentication Schemes, Host Identifiers, and
Resource Types)
■System configuration (including Common Configuration, Access Manager settings
and Authentication Modules, Security Token Service Settings, Custom Tokens,
Endpoints, Templates and Profiles, and Access Manager Agents and Security
Token Service Partners)
■Agents and partners
A System Administrator can grant the rights to administer an Application Domain to
an Application (Domain) Administrator. (A virtual Access Manager Administrator
group is defined and mapped to the Application Administrator role.) An Application
Administrator can further delegate the rights to administer one or more of their
Application Domains to other Application Administrators. An Application
Delegating the Identity Store
4-2 Administrator's Guide for Oracle Access Management
Administrator can create and edit Resources, Authentication Policies and
Authorization Policies. These rights are scoped to one or more Application Domains.
The System Administrator, Application Administrator and Help Desk Administrator
roles are mutually exclusive; that is, a group or user can be assigned to only one such
administrator role. However, the Application Administrator and Agent Administrator
roles can be assigned to the same user or group. Table 4–1 documents details about the
pre-defined administrator roles.
For information on the Oracle Access Management Console, see Section 2.3, "About
the Oracle Access Management Console and the Policy Manager Console" and
Section 2.4, "Understanding the Oracle Access Management Console."
4.2 Delegating the Identity Store
The Access Manager System Identity Store is used to enforce authentication and
authorization during the execution of administrative operations. The LDAP Directory
defined as the System Identity Store will contain all the administrators having access
to the Administration Console. An administrator can define a new User Identity Store
and select one of the existing profiles as the System Identity Store but only the System
Administrator can modify the current System Identity Store or switch to a new one.
When migrating to a new Identity Store, if users from the new store are assigned
Access Manager roles, those privileges become active and are enforced by Access
Manager. The administrator will be responsible for removing any delegated
administration privileges for the new Identity Store and the Access Manager
Administrator group will be mapped to the Administrator role of the new identity
store.
Note: Only the System Administrator can assign roles to users; users
cannot further delegate that role to others.
Table 4–1 Roles for Delegating Administration
Role Name Description
System Administrator Access to entire Oracle Access Management Console including
policy creation and system configuration; encompasses the
privileges to manage all system configurations, policy objects,
Access Manager Settings, Agents, Authentication Modules,
Authentication Schemes, Host Identifiers, Resource Types,
Federation Partners and Enterprise Single Sign-on policies.
Additionally, Security Token Service Settings, Partners, Custom
Tokens, Endpoints, Templates and Profiles can be managed.
NOTE: The System Administrator does not support seamless
failover. If one server goes offline, the System Administrator can
re-login and continue on the other server(s) in the cluster.
Application Administrator Access to policy creation and resources in the specified
Application Domain. This role has access to the Application
Registration Quick Wizard link.
Help Desk Administrator Access to the Help Desk console.
Agent Administrator Access to the Agent configuration pages. This role has access to
the Agent Registration Quick Wizard link.
Authenticated User Access to the Self Service Launch Pad and pages.
Using the Container Security Framework and MBeans
Delegating Administration 4-3
4.3 Assigning Roles Using the Administration Console
The System Administrator can use the Oracle Access Management Console to assign
roles to users or groups that cover specific Application Domains. Users can be
assigned multiple roles as long as the functionality doesn't overlap. For example, if
user X is assigned Global Policy Administrator, the user cannot be granted Policy
Administrator for the HR domain because the latter is a child of the former.
From a high level:
1. When delegating administration for a specific policy object or a set of policy
objects, the delegator selects the item(s) and assigns the user(s), group(s), LDAP
Search Filter(s) or Domain System role(s) to it.
2. When delegating administration for all objects of a specific type, the delegator will
select the user(s), group(s), LDAP Search Filter(s) or Domain System role(s) and
grant the rights to administer the objects of that type to the selected. In this case,
the administrator can't select objects for which administration is being delegated;
the administrator will select a role that is granted to the appropriate delegatee
with a specific right.
4.4 Using the Container Security Framework and MBeans
MBeans that enforce authentication and authorization using the container security
framework are published using the Portable JMX Framework.
■The Configuration Service MBeans are used for configuring the Certificate
Validation Module, the STS Endpoints, Templates & Profiles, and the STS Settings
& Custom Tokens.
■The Partner and Trust Store Service MBeans are used for managing the STS
Partners.
At runtime, the JMX Framework will authenticate the client during the connection
operation and ensure that the client belongs to the role specified in the MBean security
annotations. Because of this, the Access Manager System Identity Store needs to be
configured as an Authentication Provider in the security realm of the domain.
Additionally, users accessing the MBeans will need to be assigned the following role
depending on the container:
■WebLogic: Admin
Note: If the user currently logged in does not have the necessary
administrator roles in the new system store, the Administration
Console will log out or refresh so that it is compliant with the roles
assigned to the current administrator.
Note: Roles can be assigned only to users or groups from the
system/default store.
Note: Customers using Oracle Identity Manager (or Oracle Identity
Manager XE) may want to define Enterprise Roles that are common to
all of IDM and use OIM to assign users and groups to these Enterprise
Roles. The Administration Console allows for this.
Using the Remote Registration Utility
4-4 Administrator's Guide for Oracle Access Management
■WebSphere: Admin or Configurator
4.5 Using the Remote Registration Utility
The Remote Registration Utility (RREG) is also governed by the roles assigned to the
user invoking them. When using RREG to remotely register agents, the administrator
provides credentials that allows the RREG client to successfully connect and
authenticate to the RREG Access Manager Server; this, in turn, propagates the client's
identity to the Access Manager components that will enforce the appropriate
administration roles. The following might occur when running the RREG based on the
administrator's role:
■In a creation operation:
a. A new agent entry can be provisioned.
b. A HostID for that Agent can be created.
c. An Application for that agent might be created.
d. Resources might be added to the new Application using the newly created
HostID.
■In an update operation:
a. Agent settings can be changed.
b. A HostID for that agent can be changed.
c. An Application for that agent can be created if it does not exist.
d. Resources can be added to the Application.
The RREG administrator must be assigned roles to ensure successful completion of the
administrative operations.
■The System Administrator role to create/update an Agent.
■The OAM Shared Component Administrator / System Administrator role to
create/update an HostID entry.
■The OAM Domain Administrator role / System Administrator to create/update
an Application and create/configure Resources.
After executing the RREG command, the administrator will be set as the delegated
administrator for the created Application, Agent and HostID.
4.6 Auditing Reports
Auditing becomes even more critical when administration has been delegated to
several users. All policy object and system configuration operations performed by
administrators through the Administration Console or programmatically are logged
and informational reports can be generated. For more information, see Chapter 8,
"Auditing Administrative and Run-time Events."
5
Managing Data Sources 5-1
5
Managing Data Sources
[6]
The term data source is a Java Database Connectivity (JDBC) term used within Oracle
Access Management to refer to a collection of user identity stores or a database for
policies. These data sources must be registered using the Oracle Access Management
Console in order to be accessed.
This chapter provides the steps to register and administer data sources using the
Oracle Access Management Console. The information is common to all services
available through the Oracle Access Management Console.
■About the Data Sources
■Registering and Managing User Identity Stores
■Managing the Identity Directory Service User Identity Stores
■Understanding Administrator Roles
■Managing the Policy and Session Database
■Introduction to Oracle Access Management Keystores
■Integrating a Supported LDAP Directory with Oracle Access Manager
5.1 About the Data Sources
Oracle Access Management supports several types of data sources that are typically
installed for the enterprise. Each data source is a storage container for the various
types of information described in Table 5–1.
Table 5–1 Data Sources for Oracle Access Management
Data Source Description
Database A collection of information that is organized and stored so that its content
can be easily accessed, managed, and updated.
■Access Manager policy data, including password management data,
must be stored in a database that is extended with the Access
Manager-specific schema and registered with Access Manager. See
"Managing the Policy and Session Database" on page 5-29.
■Session Store: By default, Access Manager session data is stored
within in-memory caches that is migrated to the policy store. In
production environments, you can have an independent database for
policy data and another for session data. For details about sessions
and session data, see Chapter 16.
■Audit Store: Audit data can be stored either in a file or in a separate
database (not the policy store database). For information on auditing
administrative and run time events, see Chapter 8.
About the Data Sources
5-2 Administrator's Guide for Oracle Access Management
Table 5–2 contains the Oracle Access Management services and links to information
about the data sources used for each.
User Identity Store Central LDAP storage in which an aggregation of user-oriented data is
kept and maintained in an organized way. (Access Manager does not
include identity services; there is no native user, group, or role store.) The
identity store must be installed and registered with Access Manager to
enable authentication when a user attempts to access a protected resource
(and during authorization, to ensure that only authorized users can access
a resource). During the initial deployment process, described in the Oracle
Fusion Middleware Installation Guide for Oracle Identity and Access
Management, the embedded LDAP store is used as the User Identity
Store.
Oracle recommends that you use only the Oracle Access Management
Console or WebLogic Scripting Tool (WLST) commands for changes; do
not edit oam-config.xml.
By default, Access Manager uses the Embedded LDAP in the WebLogic
Server domain as the user identity store. However, a number of other
external LDAP repositories can also be registered as user identity stores. In
this case, one store must be designated as the System Store that contains
Administrator roles and users.
Oracle Access Management
configuration data file:
oam-config.xml
During the initial deployment process, described in the Oracle Fusion
Middleware Installation Guide for Oracle Identity and Access
Management, Oracle Access Management configuration data is stored in
an XML file: oam-config.xml.
See "About the oam-config.xml Configuration Data File" on page 5-3.
Keystores Several keystores are associated with Oracle Access Management services
as described in "Introduction to Oracle Access Management Keystores" on
page 5-31.
■Embedded Java Keystore: Used for certificates for Simple or
Certificate-based communication between OAM Servers and
Webgates. The keystore bootstrap occurs upon initial AdminServer
startup after running the Configuration Wizard.
See: "About Access Manager Security Keys and the Embedded Java
Keystore" on page 5-31
■Security Token Service Keystores: Access Manager and Security
Token Service keystore should always be different. For more
information, see "About Access Manager Keystores" on page 5-32.
■Identity Federation Keystores: Keystore settings enable you to create
aliases (a short hand notation) for keys in the keystore.
See: "About Identity Federation Keystore" on page 5-34
Table 5–2 Data Sources for Oracle Access Management Services
Service Description
Access Manager Access Manager supports multiple Identity Stores and provides SSO
authentication using data sources:
■"Registering and Managing User Identity Stores"
■"Managing the Policy and Session Database"
■"About the oam-config.xml Configuration Data File"
■"About Access Manager Security Keys and the Embedded Java Keystore"
Identity Federation Identity Federation supports multiple Identity Stores which can be assigned on a
per Identity Partner basis. Each Identity Store must be registered with Access
Manager. If no Identity Store is defined in the Identity Partner, the designated
Default Store is used.
■"Using Multiple Identity Stores"
■"About Identity Federation Keystore"
■Section 38.3, "Administering Identity Federation As A Service Provider"
Table 5–1 (Cont.) Data Sources for Oracle Access Management
Data Source Description
About the Data Sources
Managing Data Sources 5-3
The following sections contain additional details.
■About the oam-config.xml Configuration Data File
■About the Default LDAP Group
5.1.1 About the oam-config.xml Configuration Data File
Oracle Access Management provides an XML file (
oam-config.xml
) containing all
Access Manager-related system configuration data. Any changes made to the Access
Manager deployment configuration, including server and agent registration, are stored
in oam-config.xml and are automatically propagated to each Access Manager server.
Each Access Manager server has a local copy of the latest configuration XML file.
Whether you have failover configured in a high-availability environment or not, all
Access Manager servers always have the latest oam-config.xml file.
Oracle recommends not editing oam-config.xml directly. Manual changes to this file
could result in lost data or overwriting of the file during data sync operations.
However, if you must edit oam-config.xml, use the following guidelines:
■Back up oam-config.xml in: $DOMAIN_HOME/config/fmwconfig/ and store the
copy in a different location for use if needed.
■Make your changes on the node running the AdminServer to minimize possible
conflicts that another AdminConsole user might make.
■If Access Manager Servers are running, increment the configuration version
number at the top of the file to associate your change and enable automatic
propagation and dynamic activation across all OAM Servers. For example, see the
next to last line of this example (existing value + 1):
<Setting Name="Version" Type="xsd:integer">
<Setting xmlns="http://www.w3.org/2001/XMLSchema"
Name="NGAMConfiguration" Type="htf:map:>
<Setting Name="ProductRelease" Type="xsd:string">11.1.1.3</Setting>
Security Token Service Security Token Service uses only the designated Default Store for user identities.
■"About Access Manager Keystores"
■"Configuration overview: Identity Propagation with the Username Token".
■Chapter 44, "Managing Security Token Service Certificates and Keys"
Mobile and Social Mobile and Social provides its own Identity Directory Service configuration that
points to directory servers for user authentication and/or user profile services.
There is no dependency on the global data sources upon which Access Manager
and other Oracle Access Management services rely.
■Chapter 49, "Configuring Mobile and Social Services"
See Also:
■"Managing Global Password Policy" and "Configuring 11g
WebGates and Authentication Policy for DCC"
■"Using the System Store for User Identities" on page 5-5
■Chapter 16 for details about sessions stored in-memory using
Oracle Coherence and propagated to Oracle Database
■Chapter 8 for details about Audit data stored within audit files or
a separate Oracle Database
Table 5–2 (Cont.) Data Sources for Oracle Access Management Services
Service Description
Registering and Managing User Identity Stores
5-4 Administrator's Guide for Oracle Access Management
<Setting Name="Version" Type="xsd:integer">2</Setting>
</Setting>
5.1.2 About the Default LDAP Group
The default LDAP group,
Administrators
, is set during initial deployment using the
Oracle Fusion Middleware Configuration Wizard, as described in "About Oracle
Access Management Administrators" on page 2-3.
5.2 Registering and Managing User Identity Stores
A User Identity Store is a centralized LDAP repository in which an aggregation of
Administrator and user-oriented data is stored and maintained in an organized way.
Oracle Access Management supports multiple LDAP vendors, and multiple LDAP
stores can be registered for use by Oracle Access Management and its services. Oracle
Access Management addresses each user population and LDAP directory store as an
identity domain. Each identity domain maps to a configured LDAP User Identity Store
that must be registered with Oracle Access Management. This section provides the
information you need to register and manage user identity stores using the Oracle
Access Management Console.
■Understanding User Identity Stores
■Using the System Store for User Identities
■Using Multiple Identity Stores
■Defining the User Identity Store Registration Settings
■Registering a New User Identity Store
■Viewing or Editing a User Identity Store Registration
■Deleting a User Identity Store Registration
5.2.1 Understanding User Identity Stores
During initial WebLogic Server domain configuration using the Oracle Fusion
Middleware Configuration Wizard, the Embedded LDAP is configured as the one and
only user identity store for Oracle Access Management. Within the Embedded LDAP,
the Administrators group is created with
weblogic
seeded as the default
Administrator.
Note: Oracle recommends that you use the Identity Directory Service
Profiles to access identity data stores rather than the legacy OAM ID
Stores function as it will be deprecated in a future release. The Identity
Directory Service is documented in Section 5.3, "Managing the
Identity Directory Service User Identity Stores."
Note: The Embedded LDAP performs best with fewer than 10,000
users. With more users, consider a separate enterprise LDAP server. In
a highly available configuration, Oracle recommends that an external
LDAP is used as the User Identity Store. See Oracle Fusion
Middleware Securing Oracle WebLogic Server.
Registering and Managing User Identity Stores
Managing Data Sources 5-5
When attempting to access an Access Manager-protected resource, a user can be
authenticated against any store, not simply the designated Default Store. That said,
there are a few considerations:
■System Store: Only one User Identity Store can (and must) be designated as the
System Store. This is used to authenticate Administrators signing in to use the
Oracle Access Management Console, remote registration tools, and custom
administrative commands in WLST. Thus, Administrators using the Oracle Access
Management Console or remote registration utility must have credentials stored in
the System Store. Once you define a remote User Store as the System Store, you
must change the
OAMAdminConsoleScheme
to use an LDAP Authentication Module
that references the same remote user store (the System Store). For details, see
"Using the System Store for User Identities."
■Default Store: As the name implies, the LDAP store designated as the Default
Store is the automatic choice for use by LDAP authentication modules unless you
configure use of a different store for the module or plug-in.
In the Oracle Access Management Console, User Identity Store registrations are
organized under the Configuration Launch Pad. Administrators can register, view,
modify, and delete User Identity Store registrations using either the Oracle Access
Management Console or custom WLST commands described in Oracle Fusion
Middleware WebLogic Scripting Tool Command Reference.
5.2.2 Using the System Store for User Identities
Users with valid Oracle Access Management System Administrator credentials can
designate a registered user identity store as either the Default Store, the System Store
or both. You can select the Default and System Identity Store configurations using the
Oracle Access Management Console as documented in "Managing the Identity
Directory Service User Identity Stores."
UserIdentityStore1 is the embedded Access Manager LDAP store. After installation,
the Oracle Access Management Console and OAM Policy Manager are protected by
the IAM Suite Agent. The IAM Suite Application Domain is seeded with the OAM
Admin Console Authentication Policy which uses the OAMAdminConsoleScheme
authentication scheme. In turn, the OAMAdminConsoleScheme uses the LDAP
Authentication module, and the System Store and the LDAP authentication module
both use the WebLogic Embedded Identity Store (UserIdentityStore1). The Access
Manager Administrator roles are mapped to the enterprise groups and users that
belong to the System Store.
Changing the System Store impacts the entire identity management (IAM Suite)
domain. When you want to change the System Store to a remote identity store, you
need to create an Authentication Provider in WebLogic for this remote store. The
remote store provider should be displayed after the IAMSuiteAgent provider in the
list of providers in the WebLogic console. Additionally:
Note: Users attempting to access an Access Manager-protected
resource can be authenticated against any user identity store that is
registered and defined in the authentication scheme while the Security
Token Service uses only the Default User Identity Store. For example,
when adding User Conditions to a Token Issuance Policy, the identity
store from which the users are chosen must be the Default Store.
Registering and Managing User Identity Stores
5-6 Administrator's Guide for Oracle Access Management
■Ensure the control flags for all providers preceding the new remote store provider
are set to SUFFICIENT or OPTIONAL.
■Assign ADMIN, the WebLogic global role, to the enterprise groups or users from
this remote store. This can be done by following the steps to prepare the remote
store using IDM Config Tool and by referring to the WebLogic documentation.
■If using Oracle Unified Directory as a system store, create IPlanetAuthenticator in
WebLogic.
The above configuration should be done and tested before you change the System
Store to a remote store. You will also have to change the LDAP authentication module
configuration to use the remote store. The remote store can be configured using OAM
Identity Store or IDS Profile.
When you want to use a WebGate to protect the Oracle Access Management Console
(on the AdminServer) and the Policy Manager Console (on the OAM Server), in
addition to the above procedure, create an OAM Identity Asserter in WebLogic and
enable OAM as the SSO provider in JPS using WLST commands. For details, see
Appendix A, "Integrating Oracle ADF Applications with Access Manager SSO." You
will also have to whitelist the OAM Policy Manager Console host name and port, and
delete the IAMSuiteAgent provider from WebLogic to fully enable WebGate
protection.
The supported method of configuring the identity Store for a WebSphere installation is
documented in the Oracle Fusion Middleware Third-Party Application Server Guide for
Oracle Identity and Access Management. Information regarding administrator roles can
be found in "Understanding Administrator Roles."
5.2.3 Using Multiple Identity Stores
Administrators can install and register multiple user identity stores for Oracle Access
Management. Each identity store can rely on a different LDAP provider. When more
than one identity store is registered, an Administrator must define:
■The System Store: Administrators can login against the System Store only.
■The Default Store: Comes into play during patching and when using Identity
Federation, and Security Token Service.
–Patching: Oracle recommends that before patching, you designate
UserIdentityStore1 as the Default Store and also update LDAP Authentication
Modules to use UserIdentityStore1(the Embedded LDAP of Weblogic Server).
For more information see, Oracle Fusion Middleware Upgrade Guide for Oracle
Identity and Access Management.
–Identity Federation: Supports multiple identity stores, on a per IdP Partner
basis. The specified identity store must be registered like any other store. If no
identity store is defined in the IdP Partner, the Default Store is used. For
details, see Section 38.3, "Administering Identity Federation As A Service
Provider."
Note: Administrator login works only when the LDAP
Authentication Module (used by the
OAMAdminConsoleScheme)
also
uses the System Store. If you set another store as a remote store,
ensure that the
OAMAdminConsoleScheme
is modified to avoid a
lockout.
Registering and Managing User Identity Stores
Managing Data Sources 5-7
–Security Token Service: An LDAP server is required for Security Token Service
to map the Username token referencing the user to an LDAP User record, and
thus use that record to populate the outgoing token. Ensure that the desired
LDAP server is registered and configured as the Oracle Access Management
Default Identity Store, as described in "Using the System Store for User
Identities" on page 5-5. For more information, see "Configuration overview:
Identity Propagation with the Username Token".
■The specific store to use with each LDAP authentication module or plug-in (and
Form or Basic authentication schemes)
External LDAP repositories can provide user, role, and group membership
information. A user's group memberships, for example, are calculated at login time
and stored for the duration of the session. Information is used as follows:
■When evaluating policies during authentication
■When evaluating identities for authorization conditions in a policy
■When using LDAP to search for identities for conditions in an authorization policy
Registering user identity stores is required to provide connectivity with OAM Servers.
After registering the identity store, Administrators can reference it in one or more
authentication modules that form the basis for authentication schemes.
Oracle Access Management addresses each user population and directory as an
identity domain. Each identity domain simply maps to a configured identity store
name.
In the first Oracle Access Manager 11g release, users were identified using a simple
user name/id field both internally and externally. Support for multiple identity realms
requires cross-realm representation of a user or a group or any entity that resides
within the identity store. This representation, referred to as a canonical identifier,
serves as a unique identifier to various run time and administrative components of
Oracle Access Management:
■External Representation: Qualifies the simple user name with identity domain
information.
For instance, in Oracle Access Management Console a table that lists user names
includes a column that displays the identity domain of the respective user. Identity
domains map to identity store names. All functional components (the console,
Policies, Responses, Logging, Session management, Auditing, and so on) that
display user information will begin to qualify the same with the identity domain
information.
■Internal Representation: To support disambiguation, OAM stores and uses the
fully-qualified name (or uses both fields, as-is, to form a composite key).
For instance, The Session Management Engine does this to eliminate the need to
store composite). In any case, the fully-qualified name is not visible.
Table 5–3 documents the various run time and administrative components of Oracle
Access Management that use identity stores.
Note: There is no way to flush a user's group memberships
information to force Oracle Access Management to recalculate it at a
later date.
Registering and Managing User Identity Stores
5-8 Administrator's Guide for Oracle Access Management
5.2.4 Defining the User Identity Store Registration Settings
This topic describes the various user identity store settings under the System
Configuration tab. Figure 5–1 illustrates the Create User Identity Store Page, which
provides fields where you enter details for your store and default settings that you can
edit for your environment. The Store Type drop-down list provides supported choices.
Table 5–3 Components That Use Identity Stores
Component Description
Authorization Policy
Administration
Authorization policy administration allows authoring of grants to
users or groups. Administrators can search within specific identity
stores, selecting certain users or groups and granting or denying them
access. Search results provide canonical identifiers for users and
groups such that those values are stored as principals of the Identity
Condition type of an Access Manager Authorization policy. The
console displays the names and the Identity Store of origin.
Run Time Authentication and Authorization relies on the Policy run time
component.
OAMIdentity
is the runtime representation of the
authenticated user and any groups that the user is a member of (if
any). During policy evaluation, information present within the
OAMIdentity
is matched with what is stored as part of authorization
policy's Identity Constraint. The domain is asserted as a Name
Qualifier within the token.
For OAM Proxy, in addition to the existing OAM_REMOTE_USER
header, a second OAM_IDENTITY_DOMAIN header is set on every
request for an authenticated user, such that a consuming application
can disambiguate the user if needed.
Sessions Session Management searches inform Administrators as to the user
Identity Store, which is listed in the search results table.
Auditing and Logging The user Identity Store against which the user has been authenticated
is accounted for during auditing and logging.
See Also:
■"Defining the User Identity Store Registration Settings"
■"Understanding Administrator Roles"
■"Using the System Store for User Identities"
■Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference for Identity and Access Management
Registering and Managing User Identity Stores
Managing Data Sources 5-9
Figure 5–1 Creating User Identity Store Registration
Required settings are identified by the asterisk (*) on the page. Table 5–4 describes
each element and is organized by element types.
Table 5–4 User Identity Store Elements
Elements Description
Store Name A unique name for this registration. Use up to 30 characters for the name.
Registering and Managing User Identity Stores
5-10 Administrator's Guide for Oracle Access Management
Store Type A list of all supported LDAP providers from which you can choose. You can
have multiple identity stores, as described in "Using Multiple Identity Stores" on
page 5-6.
See Also: Table 24–6, " Location of Oracle-provided LDIFs for LDAP Providers".
Description Optional.
Enable SSL Click to check this box and indicate that SSL is enabled between the directory
server and OAM Server.
Using the keytool command line interface, you must also import the
appropriate CA root certificate and server certificate to the default JDK keystore
(located at $JAVA_HOME/lib/security/cacerts).
NOTE: The CA root certificate can be added to any keystore as long as the
appropriate values regarding that keystore are set for the following Java
properties. To do this, start the OAM Admin Server and Managed Server
instances with the appropriate values and the -D option.
■javax.net.ssl.trustStore=trust.jks
■javax.net.ssl.trustStorePassword=<trustPass>
■javax.net.ssl.keyStore=keystore.p12
■javax.net.ssl.keyStoreType=pkcs12
■javax.net.ssl.keyStorePassword=<keyStorePass>
Prefetched Attributes List of comma-separated user attributes; for example, email, phone, mobile. The
OAM server will cache the list of user attributes in memory while it
authenticates the user against the identity store. The cached values will be used
to compute the Authentication response headers, Authorization policy response
headers and Authorization policy conditions. Pre-fetched attributes provide
huge performance improvements by avoiding a round trip to the user identity
store. The OAM Administrator has to make sure all the user attributes used in
Authentication and Authorization policy response headers and Authorization
conditions are defined as prefetched attributes in the user identity store profile.
User Native ID Store This enables getting the authentication code for natively locked/disabled/pw_
must_change code in the LDAP authentication module.
Location and Credentials Description
Location The URL for the LDAP host, including the port number. Oracle Access
Management 11g support multiple LDAP URLs with failover capability. The
Identity Assertion Provider fails over to the next LDAP URL based on the order
in which these appear.
Enter one (or more) LDAP URLs in
host:port
format, Multiple URLs must be
separated by a space or new line. There is no need to specify ldap:// or
ldaps://(which supports SSL_NO_AUTH) in the URL value:
localhost:myhost:7001
Note: The number of characters a supported URL can have is based on the
browser version. Ensure that your applications do not use URLs that exceed the
length that Oracle Access Management and the browser can handle.
Table 5–4 (Cont.) User Identity Store Elements
Elements Description
Registering and Managing User Identity Stores
Managing Data Sources 5-11
Bind DN The user DN for the connection pool over which all other BINDs occur. Oracle
recommends a non administrative user with appropriate Read and Search
privileges for the user and group base DNs.
For example:
uid=amldapuser,ou=people,o=org
Password The password of the Principal, which is encrypted for security.
Users and Groups Description
Login ID Attribute The attribute that identifies the login ID (user name).
For example:
uid
User password attribute The attribute in the user identity store (LDAP directory) which stores the user’s
password. This is made configurable for added flexibility.
User Search Base The node in the directory information tree (DIT) under which user data is
stored, and the highest possible base for all user data searches.
For example:
ou=people,ou=myrealm,dc=base_domain
User Filter Object
Classes
The object classes to be included in search results for users, in a
comma-separated list of user object class names. For example:
user,person
.
Group Name Attribute The attribute that identifies the group name.
Default: cn
Group Search Base Currently only static groups are supported, with the
uniquemember
attribute.
The node in the directory information tree (DIT) under which group data is
stored, and the highest possible base for all group data searches.
For example:
ou=groups,ou=myrealm,dc=base_domain
Group Filter Classes The object classes to be included in the search results for groups, in a
comma-separated list of group object classes. For example:
groups,groupOfNames.
Enable Group
Membership Cache
Boolean value for group cache: true or false.
Default: true
Group Cache Size Integer for the group cache size.
Default: 10000
Group Cache
Time-to-Live (seconds)
Integer (in seconds) for Time to Live for group cache elements.
Default: 0
Connection Details Description
Minimum Pool Size The smallest size set for the connection pool.
Default: 10
Maximum Pool Size The greatest size set for the connection pool.
Default: 50
Wait Timeout The number (in seconds) that connection requests can wait before timing out in
the event of a fully utilized pool.
Default: 120
Inactivity Timeout The number (in seconds) that connection requests can be inactive before timing
out in the event of a fully utilized pool.
Results Time Limit
(seconds)
The time limit (in seconds) for LDAP searches and bind operations on the
connection pool.
Default: 0
Table 5–4 (Cont.) User Identity Store Elements
Elements Description
Registering and Managing User Identity Stores
5-12 Administrator's Guide for Oracle Access Management
Figure 5–2 shows the Default and System Store designations. Notice the Access System
Administrators section. You can add or remove Administrator roles only within the
defined System Store and the store itself.
Figure 5–2 System Store Registration
5.2.5 Registering a New User Identity Store
Users with valid Oracle Access Management Administrator credentials can use this
procedure to register a new user identity store using the Oracle Access Management
Console. After you register the identity store, you can reference it in one or more
Retry Count The number of time that the connection is retried when there is a connection
failure.
Default: 3
Referral Policy One of these values:
■follow: Follows referrals during an LDAP search (Default)
■ignore: Ignores referral entries during an LDAP search
■throw: Results in a Referral Exception, which can be caught by the
component user.
Enable Password
Management
Enables password policy enforcement against the attribute values listed below.
The corresponding options in the password policy must be configured as well.
Use Oblix User Schema Enables the use of OBLIX schema instead of standard Oracle schema.
Global Common ID
Attribute
Specifies the User ID attribute name. This attribute will be used as part of the
password policy to check that the user ID is not part of the password.
First Name Attribute Specifies the First Name attribute name. This attribute will be used as part of the
password policy to check that the user’s first name is not part of the password.
Last Name Attribute Specifies the Last Name attribute name. This attribute will be used as part of the
password policy to check that the user’s last name is not part of the password.
Email Address Attribute Not currently supported.
Challenge Questions
Attribute
Not currently supported.
Challenge Answers
Attribute
Not currently supported.
See Also: Details about classifying users in Chapter 25, "Managing
Policies to Protect Resources and Enable SSO"
Table 5–4 (Cont.) User Identity Store Elements
Elements Description
Registering and Managing User Identity Stores
Managing Data Sources 5-13
authentication modules that form the basis for authentication schemes. You can also
reference a specific identity store within Identity Conditions in Authorization Policies.
Before you begin:
■Install the user identity store that you intend to register with Oracle Access
Management.
■Extend the LDAP directory schema for Access Manager, as described in Oracle
Fusion Middleware Installation Guide for Oracle Identity and Access
Management.
■Create Users and Groups in the LDAP directory, as described in your vendor
documentation.
Follow this procedure to register a new identity store definition.
1. At the top of the Oracle Access Management Console, click Configuration.
2. In the Configuration console, click User Identity Stores.
3. In the OAM ID Stores section, click Create.
4. Fill in the form with appropriate values for your deployment (Table 5–4), then
click Apply to submit the registration.
5. Tes t C on ne c t i on : Click Test Connection to confirm connectivity, then close the
Confirmation window.
6. Close the registration page.
7. Add Administrators: See "Understanding Administrator Roles" on page 5-26.
a. In the navigation tree, double-click the store name to open the registration
page.
b. In the Access System Administrators section, click the + above the table.
c. Fill in the Add System Administrator Roles dialog box (...).
d. Click Apply.
8. Set Default Store: See "Using the System Store for User Identities" on page 5-5.
9. Click Apply to submit the registration and close the page.
10. Configure one or more authentication modules or plug-ins to use this store, as
described in:
■"Native LDAP Authentication Modules" on page 22-25
■"Orchestrating Multi-Step Authentication with Plug-in Based Modules" on
page 22-29
5.2.6 Viewing or Editing a User Identity Store Registration
Users with valid Oracle Access Management Administrator credentials can view or
modify the registration of a user identity store. The user identity store that you intend
to register must be installed and running.
1. At the top of the Oracle Access Management Console, click Configuration.
2. In the Configuration console, click User Identity Stores.
3. In the OAM ID Stores list, select the target identity store and click Edit.
4. Modify values as needed (see Table 5–4).
5. Click Apply to update the registration (or close the tab without applying changes).
Managing the Identity Directory Service User Identity Stores
5-14 Administrator's Guide for Oracle Access Management
6. Test Connection: Click Test Connection button to confirm connectivity, then close
the Confirmation window.
7. Set as System or Default Store: See "Using the System Store for User Identities".
8. Manage Administrator Roles: See "Understanding Administrator Roles".
9. Configure one or more authentication modules or plug-ins to use this store, as
described in:
■"Native LDAP Authentication Modules" on page 22-25
■"Orchestrating Multi-Step Authentication with Plug-in Based Modules" on
page 22-29
10. Close the page when you finish.
5.2.7 Deleting a User Identity Store Registration
Users with valid Oracle Access Management Administrator credentials can use this
procedure to delete a user identity store registration using the Oracle Access
Management Console.
1. Edit LDAP Authentication Modules that reference the store to be deleted (to
ensure a valid identity store is referenced within the module).
2. At the top of the Oracle Access Management Console, click Configuration.
3. In the Configuration console, click User Identity Stores.
4. In the OAM ID Stores list, select the target identity store and click Delete.
5. In the confirmation dialog that appears, click Delete to confirm the deletion (or
click Cancel to dismiss the window and retain the instance).
6. Confirm that the definition is no longer listed in the navigation tree.
5.3 Managing the Identity Directory Service User Identity Stores
Identity Directory Service (IDS) is a flexible and configurable service used by Access
Manager as the means for accessing multiple identity data stores. The purpose of IDS
is to allow the management of users or groups from identity stores not deployed with
Access Manager itself. The following sections contain the details.
■Using Identity Directory Services
■Creating an Identity Directory Service Profile
■Editing or Deleting an Identity Directory Service Profile
■Creating a Form-fill Application Identity Directory Service Profile
■Understanding the Pre-Configured Identity Directory Service Profile
■Creating an Identity Directory Service Repository
Note: You cannot delete the Default Store or System Store
registration.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-15
5.3.1 Using Identity Directory Services
Identity Directory Service offers a consistent and rationalized technology to access
identity stores that eliminates redundant configurations and simplifies Identity
Management operations. IDS provides the following benefits:
1. Support for different types of user directories including integration with native
user/password state managed by the directory.
2. Consistent administration user interface and a paradigm for working with
different identity stores across Oracle Identity Management components.
3. Built in failover and load balancing capabilities.
4. Logical to physical attribute mapping and entity relationships.
The following list of directory servers are among those supported.
■Microsoft Active Directory
■Novell eDirectory
■Oracle Directory Server Enterprise Edition
■Oracle Internet Directory
■Oracle Unified Directory
■Oracle Virtual Directory
■OpenLDAP
■IBM Tivoli Directory Server
■WebLogic Server Embedded LDAP
Figure 5–3 is a screen capture of the Identity Directory Service console page.
Note: Oracle recommends that you use the Identity Directory Service
Profiles to access identity data stores rather than the legacy OAM ID
Stores function as it will be deprecated in a future release.
Managing the Identity Directory Service User Identity Stores
5-16 Administrator's Guide for Oracle Access Management
Figure 5–3 Identity Directory Service Console Page
Configuring an Identity Directory Service store involves configuring parameters for an
IDS Profile and an IDS Repository. The IDS Profile specifies the full scope of traits for a
particular type of identity store. It is the logical configuration for the repository and
contains the following data.
■Entity definition
■Entity relationship definition
■Default operational configuration (including the tenant search/create base, the
tenant filter, timeouts and cache configuration)
Note: Note this page contains the configuration panel for the legacy
OAM ID Stores. Oracle recommends that you use the Identity
Directory Service Profiles to access identity data stores rather than the
legacy OAM ID Stores function as it will be deprecated in a future
release.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-17
The IDS Repository configuration defines the actual location of the store. The IDS
Repository is a physical configuration that containing the following data.
■Connection details (including the host machine, port number and credentials)
■Connection pool details
■High-availability/failover configuration
■Entity attribute mapping
5.3.2 Creating an Identity Directory Service Profile
To create an Identity Directory Service profile, proceed as follows.
1. At the top of the Oracle Access Management Console, click Configuration.
2. In the Configuration console, click User Identity Stores.
3. In the IDS Profiles section, click Create.
The Create IDS Profile page is displayed as in Figure 5–4.
Managing the Identity Directory Service User Identity Stores
5-18 Administrator's Guide for Oracle Access Management
Figure 5–4 Create IDS Profile Page
4. Provide the following values for the new Identity Directory Service profile.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-19
■Name - Type a unique name for this User Profile Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
5. Configure the Repository properties by selecting Create New or Use Existing.
Create New defines a new Repository object (that is, a reference to an LDAP
directory server) for the Identity Directory Service connection. Click Tes t
Connection after you have defined the values in the Repository section to verify
they are correct. This option is only available when defining a new Identity
Directory Service connection. Use Existing allows you to choose a previously
defined Repository object by selecting it from the drop down menu.
■(Repository) Name - Enter a new unique name to create, or choose an existing
one from the menu. After entering a new name, configure properties for the
Identity Directory Service connection.
■Directory Type - Select the type of directory server software hosting the
Repository; for example, Microsoft Active Directory or Oracle Internet Directory.
If your directory is not listed, leave this field empty. If you are not defining a
new Identity Directory Service connection or creating a new repository, this
field is read-only.
■Host Information - Contains information about the host computer on which
the Identity Directory Service Repository is located. Add multiple hosts if the
directory server is part of a cluster. Click Add to add a new host to the table. In
the Host Name column type either the IP Address or the name of the
computer (or virtual computer) on which the Directory server is running. In
the Port column, type the port number that the directory server is configured
to use. If the hosts are part of a cluster, in the Load Distribution column type
the load amount as a percentage that should be directed to each host. For
multiple hosts, the amount should add up to 100%. To delete a host, select its
row in the table and click Remove. If you are not defining a new Identity
Directory Service connection or creating a new repository, this field is
read-only.
■Availability - Choose Failover if the cluster is configured for failover
operation, or choose Load balanced if the cluster distributes the load across
multiple hosts. This field is read-only if you are using an existing repository.
■SSL - Select Enabled if the connection is configured for SSL. (See the Oracle
Fusion Middleware Application Security Guide for SSL configuration details.)
Managing the Identity Directory Service User Identity Stores
5-20 Administrator's Guide for Oracle Access Management
■Bind DN - Type the distinguished name (DN) of the LDAP Administrator
used to authenticate to the Directory server.
■Bind Password - Type the Bind DN password used to authenticate to the
Directory server.
■Base DN - Type the base distinguished name (DN) where User and Group
data is located.
■Password Management - selecting Enable Password Management enables
password policy enforcement against the attribute values listed in Table 5–4.
The corresponding options in the password policy must be configured as well.
6. Configure the User properties to configure the LDAP User object in Mobile and
Social User Profile services.
■Object Classes - Click Add to add a custom object class that represents people
in an organization as defined on your directory server.
■RDN Attribute - Type the relative distinguished name attribute (for example,
cn) designated for the User object on the directory server.
■Base DN - Type the base DN (in LDAP form) for the User object on the
directory server.
■Login ID Attribute - Type the LDAP attribute from which the login ID
specifying the User will be extracted.
■Global Common ID Attribute - Type the global common user ID attribute.
7. Configure the Group properties to configure the LDAP group object in Mobile and
Social User Profile services.
■Object Classes - Click Add to add a custom object class that represents a
group of people in an organization as defined on your Directory server.
Note: Follow this procedure to add the SSL certificates required for
setting the TLS connection.
1. Create the LibOVD keystore by running this command.
MW_HOME/oracle_common/bin/libovdconfig.sh -host WLS_ADMIN_HOST
-port WLS_ADMIN_PORT -userName weblogic
-domainPath WLS_DOMAIN_PATH -createKeystore
-contextName ids
Enter the AdminServer password and the password used for the
LibOVD keystore when requested.
2. Import the OID server certificate into the LibOVD keystore.
keytool -importcert
-keystore DOMAIN_HOME/config/fmwconfig/ovd/
ids/keystores/adapters.jks
-storepass KEYSTORE_PASSWORD -alias ALIAS_NAME
-file FULL_PATH_TO_CERTFILE -noprompt
Note: These fields are read-only if using an existing Identity
Directory Service connection.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-21
■RDN Attribute - Type the relative distinguished name attribute (for example,
cn) designated for the Group object on the directory server.
■Base DN - Type the base DN (in LDAP form) for the Group object on the
directory server.
■ID Attribute - Type the LDAP attribute from which the ID designated for the
Group object will be extracted.
8. Click Create.
The profile is displayed in the IDS Profiles table.
5.3.3 Editing or Deleting an Identity Directory Service Profile
To edit or delete an IDS Profile, select the name in the table and click Edit or Delete in
the tool bar. Editing the profile allows for additional configuration properties for the
Identity Directory Service connection.
■Name - Choose an Identity Directory Service connection to associate with the User
Profile Service Provider from the drop down menu.
–If you choose either of the default Identity Directory Services (either
userrole
or
idxuserrole
) you cannot view or edit the configuration values.
–If you choose an Identity Directory Service connection that you or another
Administrator created, you can view and edit the configuration values as
needed.
■General and Repository - Use the fields under this tab to edit the Directory
Service and Repository configuration values that Mobile and Social uses to
connect to the Directory Service.
– Repository Name - Choose from the menu a repository to associate with the
Identity Directory Service connection. After choosing a repository, configure
its properties using the following form fields.
–Directory Type - Displays the type of Directory server software hosting the
Repository, for example Microsoft Active Directory, Oracle Internet Directory, and
so on. This field is read-only.
– Host Information - Displays information about the host computer where the
Identity Directory Service Repository is located. Add multiple hosts if the
Directory server is part of a cluster. Click Add to add a new host to the table.
In the Host Name column type either the IP Address or the name of the
computer (or virtual computer) that the Directory server is running on. In the
Port column, type the port number that the Directory server is configured to
use. If the hosts are part of a cluster, in the Load Distribution column type the
load amount as a percentage that should be directed to each host. For multiple
hosts, the amount should add up to 100%. To delete a host, select its row in the
table and click Remove. If you are not defining a new Identity Directory
Service connection or creating a new repository, this field is read-only.
– Availability - Choose Failover if the cluster is configured for failover
operation, or choose Load balanced if the cluster distributes the load across
multiple hosts. This field is read-only if you are using an existing repository.
–SSL - Select Enabled if the connection is configured for SSL. Otherwise clear
the option box. See SSL in Section 5.3.2, "Creating an Identity Directory
Service Profile" for information on how to add the SSL certificates required for
the TLS connection.
Managing the Identity Directory Service User Identity Stores
5-22 Administrator's Guide for Oracle Access Management
– Bind DN - Type the distinguished name (DN) of the LDAP Administrator
used to authenticate to the Directory server.
– Bind Password - Type the Bind DN password used to authenticate to the
Directory server.
–Base DN - Type the base distinguished name (DN) where User and Group
data is located.
– Password Management - selecting Enable Password Management enables
password policy enforcement against the attribute values listed in Table 5–4.
The corresponding options in the password policy must be configured as well.
■Entity Attributes - Use the fields under this tab to view or edit the attributes that
Mobile and Social uses to navigate the corporate directory service schema. Click
Add to add an attribute to the table or click Remove to delete an attribute.
– Name - The attribute name.
– Physical Attribute - The name of the corresponding physical attribute type in
the underlying Repository.
–Type - The attribute's data type.
– Description - A brief description of the attribute.
–Sensitive - Select to mark that the attribute contains sensitive information
such as a password.
–Read-only - Select to protect the attribute from modification.
■Entities / User Properties - Use the fields under the User sub head to configure
how Mobile and Social interacts with the User entities on the LDAP server.
–Create Base - Specifies the base DN (the top level of the LDAP directory tree)
at which Users are defined.
– Search Base - Specifies the search base DN for Users. Only entries at or below
the search base DN are considered when processing the search operation.
– Create Object Classes - Specifies the object class under which attributes
associated with a person are stored.
– RDN Attribute - Specifies the relative distinguished name attribute, for
example cn.
– ID Attribute - Specifies the attribute that uniquely identifies the User, such as
the uid attribute or the loginid attribute.
– Filter Object Classes - Specifies the object class by which to filter.
–Attributes Configuration - Specify the User attributes that should be available
to, and searchable by, the User Profile Service Provider.
*Used - Specifies if the attribute is used for Users in the directory service.
* Attribute Name - Specifies the name of the attribute as defined on the
Entity Attributes tab.
*In Results - Select if the specified attribute should be returned in search
results.
* Searchable - Select if the specified attribute should be available for search
operations.
* Search Operator - Select a search operator from the menu to restrict how
the specified attribute is searched.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-23
– Operations Configuration - Select from Create, Update, Delete, and Search to
enable those operations at the User entity level. Clear the option boxes to
disable them.
■Entities / Group Properties - Use the fields under the Group sub head to configure
how Mobile and Social interacts with the Group entities on the LDAP server.
–Create Base - Specifies the base DN (the top level of the LDAP directory tree)
at which Users are defined.
– Search Base - Specifies the search base DN for Groups. Only entries at or
below the search base DN are considered when processing the search
operation.
– Create Object Classes - Specifies the object class under which attributes
associated with a Group are stored.
– RDN Attribute - Specifies the relative distinguished name attribute; for
example, cn.
– ID Attribute - Specifies the LDAP attribute that uniquely identifies the Group.
– Filter Object Classes - Specifies the object class by which to filter.
–Attributes Configuration - Specify the Group attributes that should be
available to, and searchable by, the User Profile Service Provider.
*Used - Specifies if the attribute is used for Users in the directory service.
* Attribute Name - Specifies the name of the attribute as defined on the
Entity Attributes tab.
*In Results - Select if the specified attribute should be returned in search
results.
* Searchable - Select if the specified attribute should be available for search
operations.
* Search Operator - Select a search operator from the menu to restrict how
the specified attribute is searched.
– Operations Configuration - Select from Create, Update, Delete, and Search to
enable those operations at the Group entity level. Clear the option boxes to
disable them.
■Relationships - Use the fields under this tab to configure the relationship between
attributes for this Identity Directory Service.
– Name - The relationship name.
– (From) Entity - Choose User to select from User attributes or choose Group to
select from Group attributes in the (From) Attribute column.
– (From) Attribute - Choose the attribute from which you are mapping.
– Relation - Choose the menu option that describes the relationship between the
specified attribute in the From column and the specified attribute in the To
column.
– (To) Entity - Choose User to select from User attributes or choose Group to
select from Group attributes in the (To) Attribute column.
– (To) Attribute - Choose the attribute to which you are mapping.
–Recursive - Select if the relationship extends down the directory tree to
include nested child entities or up the directory tree to include parent entities.
Managing the Identity Directory Service User Identity Stores
5-24 Administrator's Guide for Oracle Access Management
■Relationship Configuration - Type the URI segment used to access the
corresponding column in the Identity Directory Service. Use Add to add a new
relationship or Remove to remove a configured relationship.
– Access URI - Type a URI segment that will be used to access a corresponding
data column in the Identity Directory service. For example, if
memberOf
is the
Access URI, then:
http://host:port/.../idX/memberOf
would be the URI to access related entities of an entity with ID
idX
.
– Identity Directory Service Relation - Choose the Directory Service
relationship that is to be accessed by the Access URI segment. You can
configure relationships on the Relationships tab in the Identity Directory
Service configuration section provided that the Identity Directory Service is
not the pre-configured UserProfile Identity Provider. (You cannot configure
Identity Directory Service relationships for the UserProfile Service Provider.)
– Entity URI Attribute - Type the JSON attribute name to be used in the URI
response sent from the Mobile and Social server. For example, if person-uri is
the specified entity URI attribute, the URI response would be as follows:
{ {"person-uri":uriY1, ...}, {"person-uri":uriY2, ...}, ... }
where
uriY1
and
uriY2
are the direct URIs to access each of the related
entities.
– Scope for Requesting Recursion - Use Scope attribute values with the scope
query parameter to retrieve a nested level of attributes in a relationship search.
To access related entities recursively, type the value to be used. The Mobile
and Social default configuration uses two scope attribute values:
toTop
and
all
. If the Scope for Requesting Recursion value is the attribute value
all
,
then the following REST URI example is used to make the request:
http://host:port/.../idX/reports?scope=all
In this example, the URI returns the entities related to the entity with ID
idX
,
as well as all further related entities.
5.3.4 Creating a Form-fill Application Identity Directory Service Profile
To create an Identity Directory Service Profile for a Form-fill Application, click the
Create Form-fill Application IDS Profile button on the left of the User Identity Stores
console page. (See Figure 5–3.)
Section 5.3.2, "Creating an Identity Directory Service Profile" and Section 5.3.3, "Editing
or Deleting an Identity Directory Service Profile" contain definitions for most of the
Form-fill attributes. Additional definitions for the Entity Search Bases section specific
to this type of profile are listed below.
■User Search Base - Full DN for the node at which enterprise users are stored in the
directory; for example, cn=Users,realm_DN.
■App Template Search Base - Full DN for the node from which searches for the
Application Templates will begin.
■Top Search Base - Full DN for the node from which searches will begin; for
example, cn=realm_DN.
Managing the Identity Directory Service User Identity Stores
Managing Data Sources 5-25
5.3.5 Understanding the Pre-Configured Identity Directory Service Profile
Mobile and Social provides a pre-configured IDS Profile named UserIdentityStore1.
This profile allows lookup and update tasks to be performed on directory objects using
Mobile and Social.
5.3.6 Creating an Identity Directory Service Repository
To create an Identity Directory Service repository, proceed as follows.
1. At the top of the Oracle Access Management console, click Configuration.
2. In the Configuration console, click User Identity Stores.
3. Click Create under IDS Repository.
The Create IDS Repository page is displayed as in Figure 5–5.
Figure 5–5 Create IDS Repository Page
4. Provide the following values for the new Identity Directory Service repository.
■Name: the entry must be a unique.
■Select the Directory Type from the drop down choices.
Understanding Administrator Roles
5-26 Administrator's Guide for Oracle Access Management
5. Click Add to configure the physical location of the repository (Host name, Port
number and Load Weightage percentage).
6. Configure the Repository properties as follows:
■(Repository) Name - Enter a new unique name to create, or choose an existing
one from the menu. After entering a new name, configure properties for the
Identity Directory Service connection.
■Directory Type - Select the type of directory server software hosting the
Repository; for example, Microsoft Active Directory or Oracle Internet Directory.
If your directory is not listed, leave this field empty. If you are not defining a
new Identity Directory Service connection or creating a new repository, this
field is read-only.
■Host Information - Contains information about the host computer on which
the Identity Directory Service Repository is located. Add multiple hosts if the
directory server is part of a cluster. Click Add to add a new host to the table. In
the Host Name column type either the IP Address or the name of the
computer (or virtual computer) on which the Directory server is running. In
the Port column, type the port number that the directory server is configured
to use. If the hosts are part of a cluster, in the Load Distribution column type
the load amount as a percentage that should be directed to each host. For
multiple hosts, the amount should add up to 100%. To delete a host, select its
row in the table and click Remove. If you are not defining a new Identity
Directory Service connection or creating a new repository, this field is
read-only.
■Availability - Choose Failover if the cluster is configured for failover
operation, or choose Load balanced if the cluster distributes the load across
multiple hosts. This field is read-only if you are using an existing repository.
■SSL - Select Enabled if the connection is configured for SSL. See SSL in
Section 5.3.2, "Creating an Identity Directory Service Profile" for information
on how to add the SSL certificates required for the TLS connection. (See the
Oracle Fusion Middleware Application Security Guide for SSL configuration
details.)
■Bind DN - Type the distinguished name (DN) of the LDAP Administrator
used to authenticate to the Directory server.
■Bind Password - Type the Bind DN password used to authenticate to the
Directory server.
■Base DN - Type the base distinguished name (DN) where User and Group
data is located.
■Password Management - selecting Enable Password Management enables
password policy enforcement against the attribute values listed in Table 5–4.
The corresponding options in the password policy must be configured as well.
7. Click Test Connection to confirm the values are correct.
8. Click Create.
The repository is displayed in the IDS Repositories table.
5.4 Understanding Administrator Roles
By default, the Oracle Access Management Administrators role is the same as the
WebLogic Administrators role (Administrators). You can register another User Identity
Understanding Administrator Roles
Managing Data Sources 5-27
Store (Oracle Internet Directory, for example); however, user
weblogic
must be defined
with at least one user in the registered store to authenticate against. Administrator
login works only when the Authentication Scheme (and assigned Authentication
Module) used by the IAMSuiteAgent, also uses the System Store. This section provides
the following topics:
■Adding Administrator Roles
■Managing Administrator Roles
5.4.1 Adding Administrator Roles
Your enterprise might require independent sets of Administrators: one set of users
responsible for Access Manager and another for Security Token Service. All
Administrator roles, users, and groups must be stored in the System Store. If the
System Store changes, appropriate Administrator roles must be added to the new
System Store. If, when editing an Identity Store registration, you designate a store as
the System Store the Access System Administrator section appears.
You can add new Administrator roles when adding or editing a User Identity Store
registration. Figure 5–6 shows the page and controls to use.
Figure 5–6 Add System Administrator Roles
5.4.2 Managing Administrator Roles
This section explains how to define or remove Oracle Access Management
Administrator roles which must be stored in the User Identity Store designated as the
System Store. First, define the desired LDAP group to use for Administrators and then
ensure that your Administrators group is available in the group search base. (See
Using the System Store for User Identities.) To add or remove an Administrator role
from the System Store, follow this procedure.
1. View System Store Registration: Perform the following steps (or find a different
System Store in the Data Sources node to designate as the System Store).
Understanding Administrator Roles
5-28 Administrator's Guide for Oracle Access Management
a. At the top of hte Oracle Access Management Console, click Configuration.
b. In the Configuration console, click Administration.
The registered System Store can not be changed from this page.
c. Search the System Store to find configured administrators.
2. Add User Roles:
a. Click the Grant (+) button above the Access System Administrators table to
display the Add Users and Groups dialog box.
b. Select User in the Type list and click Search.
c. In the results list, click the desired user, then click Add Selected.
d. Repeat as need to add desired Administrator User roles.
e. Click Apply to submit user roles.
3. Add Group Roles:
a. Click the Grant (+) button above the Access System Administrators table to
display the Add Users and Groups dialog box.
b. Select Group in the Type list and click the Search button.
c. In the results list, click the desired Group and then click the Add Selected
button.
d. Repeat as need to add desired Administrator Group roles.
e. Click Apply to submit Group roles.
4. Remove Administrator Roles:
a. In the Access System Administrators table, click the row containing the user or
group to remove.
b. Click the Delete (x) button above the table.
c. Confirm removal when asked.
d. Click Apply to submit the removal.
5. Correct any authentication plug-ins that use the System Store (if this is a new
store).
This procedure is described in "Orchestrating Multi-Step Authentication with
Plug-in Based Modules" on page 22-29
6. Test the New Role: Close the browser window, then re-open it.
a. Sign out of the Oracle Access Management Console and close the browser
window.
b. Start up the Oracle Access Management Console and attempt to log in using
the previous Administrator role to confirm that this attempt fails.
c. Log in using the new Administrator role to confirm that this attempt is
successful.
Login Failure: See "Administrator Lockout" on page E-6.
Managing the Policy and Session Database
Managing Data Sources 5-29
5.5 Managing the Policy and Session Database
Oracle Access Management requires a database to store Access Manager policy data,
password management data, and Access Manager sessions in a production
environment.
This section includes the following topics:
■About the Database Store for Policy, Password Management, and Sessions
■About Database Deployment
■Configuring a Separate Database for Access Manager Sessions
5.5.1 About the Database Store for Policy, Password Management, and Sessions
The following data is maintained in the policy store database by default:
■Policy data, including authentication modules and schemes, Application Domains,
and policies.
■Password Management data, which includes password policy type for each
configured User Identity store as well as the policy that governs password
requirements, expiry, notification,
■Sessions, as a persistent backup to distributed in-memory storage
5.5.2 About Database Deployment
Oracle requires a single database as the policy store in production environments. This
single database can also be used to store session data. Using the database as the
session store provides greater scalability and fault-tolerance (against a power event
taking all servers down).
The policy database must be installed according to vendor instructions. The policy
database is configured for use in a Oracle WebLogic Server domain using Oracle
Fusion Middleware Configuration Wizard and policy store Database configuration
template.
Note: At most, your deployment can have one policy store database
(which serves password management) and one session store. By
default, a single JDBC data source is used for both.
Note: The preferred mode for audit data storage in production
environments is writing audit records to a stand-alone RDBMS
database for audit data only. This is done using a separately
configured audit store. The policy store is not used for audit data.
See Also: "Managing the Policy and Session Database" on page 5-29
Note: You can have up to two databases: one policy database and
one session database. Access Manager is agnostic with respect to the
actual back end repository and does not manage this policy store
configuration directly.
Managing the Policy and Session Database
5-30 Administrator's Guide for Oracle Access Management
During initial deployment with the WebLogic Configuration Wizard, the following
database details are requested:
■Database login ID and password
■Database Service name and location
An Administrator must extend the database with the Access Manager-specific schema
using RCU, as described in Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management. Basic schema creation occurs when the RCU is
invoked. The RCU prepares the database to accept Access Manager policy, password
management, and session data.
Using the WebLogic Configuration Wizard you can register and test the connection to
the database.
Actual Access Manager policy elements are created the first time the WebLogic
AdminServer is started with the Oracle Access Management Console deployed.
5.5.3 Configuring a Separate Database for Access Manager Sessions
Access Manager includes a data source named
oamDS
which is configured against the
database instance extended with the Access Manager Schema. The following
pre-defined Java Naming and Directory Interface (JNDI) names are used by the OAM
Server to refer the data source.
jdbc/oamds (used by both the policy layer and session layer to access database)
You can use the following procedure to create a separate database instance for session
data using the WebLogic Administration Console. There is no support for this action in
the Oracle Access Management Console.
1. Install and configure the database for session data and then use RCU with the
Access Manager-specific schema to set up the database as a session data store.
2. Create a new Data Source instance for session data:
a. From the WebLogic Administration Console, Domain Structure panel, expand
the domain name, Services node.
b. Expand JDBC, Data Source.
c. Create a new Data Source with the JNDI name
jdbc/oamsession
.
d. Save the changes.
e. Stop the OAM Servers and the AdminServer to avoid potential loss of data
during the next step.
f. In oam-config.xml, edit the value of the
DataSourceName
attribute to the one
configured in step 1. For example:
domain-home/config/fmwconfig/oam-config.xml
From:
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management
Note: In this rare instance, Oracle recommends that you carefully
edit oam-config.xml as described in Step 2f.
Introduction to Oracle Access Management Keystores
Managing Data Sources 5-31
<Setting Name="SmeDb" Type="htf:map">
<Setting Name="URL" Type="xsd:string">jdbc:oracle:thin://amdb.example.
com:2001/AM</Setting>
<Setting Name="Principal" Type="xsd:string">amuser</Setting>
<Setting Name="Password" Type="xsd:string">password</Setting>
<Setting Name="DataSourceName" Type="xsd:string">jdbc/oamds</Setting>
</Setting>
To:
<Setting Name="SmeDb" Type="htf:map">
<Setting Name="URL" Type="xsd:string">jdbc:oracle:thin://amdb.example.
com:2001/AM</Setting>
<Setting Name="Principal" Type="xsd:string">amuser</Setting>
<Setting Name="Password" Type="xsd:string">password</Setting>
<Setting Name="DataSourceName"
Type="xsd:string">jdbc/oamsession</Setting>
</Setting>
3. Restart AdminServer and OAM Servers.
5.6 Introduction to Oracle Access Management Keystores
This section provides the following topics:
■About Access Manager Security Keys and the Embedded Java Keystore
■About Access Manager Keystores
■About Identity Federation Keystore
5.6.1 About Access Manager Security Keys and the Embedded Java Keystore
Keystores are created and configured during Access Manager installation. The
password and the key entries password were randomly generated.
The preferred keystore format is JKS (Java keystore). A Java keystore is associated with
Access Manager behind the scenes and is used to store cryptographic security keys
that are generated to encrypt agent traffic and session tokens:
■Every OAM Agent and OSSO Agent has a secret key that other agents cannot
read.
■There is a key to encrypt Oracle Coherence-based session traffic.
■During agent and application registration, a key is generated for encrypting and
decrypting SSO Cookies (for Webgates and mod_osso).
Administrators use the Oracle-provided
importcert
tool for several different
procedures related to keystores, keys, and certificates, as described in Appendix C.
The WLST
resetKeystorePassword
method allows you to set the .oamkeystore
password and any key entries with a password identical to the .oamkeystore password
to a new value. See Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference.
Table 5–5 identifies the generated Access Manager cryptographic keys.
Introduction to Oracle Access Management Keystores
5-32 Administrator's Guide for Oracle Access Management
Keystores are not accessible using the Oracle Access Management Console. You can
manage keystores and certificates as described in Appendix C, "Securing
Communication".
5.6.2 About Access Manager Keystores
Table 5–6 provides a summary of keystores used for Access Manager.
Table 5–5 Access Manager Keys and Storage
Keys and Storage Description
Access Manager
Cryptographic keys
■One per agent secret key shared between 11g Webgate and OAM Server
One global shared secret key used by all your 10g Webgates
■One OAM Server key
Key storage ■Agent side: A per-agent key is stored locally in the Oracle Secret Store in a wallet file. Client
keystore/scratch/clientTrustStore.jks and /scratch/clientKey.jks can be used.
■OAM Server side: .oamkeystore contains a per-agent key, and server key, are stored in the
credential store on the server side.
See Also: "About Identity Federation Keystore" on page 5-34
■"About Communication Between OAM Servers and WebGates" on
page 6-4
■Oracle Fusion Middleware Administrator's Guide for details
about the SSL automation tool and managing ports for WebLogic
Server, Oracle HTTP Server, and Oracle Fusion Middleware
Table 5–6 Keystores for Access Manager and Security Token Service
Keystore Description
System Keystore / Partner
Keystore
.oamkeystore
The container for keys and certificates associated with OAM
Server instances (OAM secret keys and Security Token Service
private keys for signing and encryption).
The container for keys and certificates that are used to
establish trust with partners, clients, and agents. The partner
keys and certificates are stored in.oamkeystore with sensitive
information encrypted.
Only one System Keystore of type JCEKS can be present:
.oamkeystore.
$
DOMAIN_HOME/config/fmwconfig/.oamkeystore
The certificate alias and password can be configured using the
Oracle Access Management Console.
See Also:
■Table 43–1, " Security Token Service Settings"
■Chapter 44, "Managing Security Token Service Certificates
and Keys"
Introduction to Oracle Access Management Keystores
Managing Data Sources 5-33
Trust Keystore
amtrustkeystore
The Trust Keystore is used to validate keys and certificates
presented by clients to establish trust in entities interacting
with OAM Server instances.
$
DOMAIN_HOME/config/fmwconfig/amtruststore
amtruststore is created during installation, and must include at
least one trusted anchor.
The Trust Keystore is managed by using the JRE's keytool
application. Security Token Service can use a custom trust
keystore.
See Also:
■"Managing the Trust Anchors Store (amtruststore)" on
page 44-9
■"Using a Custom Trust Anchor Store for Security Token
Service" on page 44-10
Certificate Revocation Lists
(CRL)
amcrl.jar
Certificate revocation information lists are stored in a ZIP
archive on the filesystem. These are used by OAM Servers
when performing CRL-based certificate revocation checking.
amcrl.jar contains CRL files in the DER format:
$DOMAIN_HOME/config/fmwconfig/amcrl.jar
The OAM Server defines a notification listener for the
Keystores and the CRL Zip file. Any changes to these files
causes Security Token Service to reload the keystore/crl-zip at
runtime, without requiring any restarts.
amcrl.jar is created by installation and can be modified using
the Oracle Access Management Console.
See Also:
■"Managing Certificate Validation and Revocation" on
page 3-7
■"Managing Certificate Revocation Lists" on page 44-10
Oracle WSM Agent Keystore
default-keystore.jks
The Oracle WSM Agent uses this keystore for various
cryptographic operations. For these operations, the Oracle
WSM Agent uses the keystore configured for Oracle WSM
tasks.
Oracle strongly recommends that the Oracle WSM Agent
keystore and the Access Manager and Security Token Service
keystore always be different. Otherwise, keys could be
available to any modules authorized by OPSS to access the
keystore and Access Manager/Security Token Service keys
might be accessed.
See Also:
"About the Oracle Web Services Manager Keystore
(default-keystore.jks)" on page 44-3
OPSS Keystore For special cases where clients use referencing schemes such as
SKI (as opposed to a certificate token being received as part of
the web service request), the requester's certificates need to be
populated in the OPSS Keystore.
This is an uncommon scenario that requires manually
provisioning keys to the OPSS keystore.
See Also:
■"About Agents and Security Token Service" on page 43-4
■Oracle Fusion Middleware Application Security Guide.
Table 5–6 (Cont.) Keystores for Access Manager and Security Token Service
Keystore Description
Integrating a Supported LDAP Directory with Oracle Access Manager
5-34 Administrator's Guide for Oracle Access Management
5.6.3 About Identity Federation Keystore
Identity Federation and Access Manager store key pairs and certificates that are used
for digital signatures and encryption operations. Identity Federation uses keys to:
■Sign outgoing assertions
■Decrypt incoming XML encrypted data contained inside the SAML message
The following keystore is used to store the encryption and signing certificates:
$DOMAIN_HOME/config/fmwconfig/.oamkeystore
Identity Federation uses CSF to securely store keystore passwords, as well as server
credentials such as HTTP Basic Authentication usernames and passwords.
5.7 Integrating a Supported LDAP Directory with Oracle Access Manager
This section describes how to enable a centralized LDAP store for use with Oracle
Access Manager post-installation. Oracle Internet Directory is featured in this
discussion however the tasks are the same regardless of your chosen LDAP directory.
Oracle Access Manager addresses each user population and LDAP directory store as
an identity domain. Each identity domain maps to a configured LDAP User Identity
Store that is registered with Oracle Access Manager. Multiple LDAP stores can be used
with each one relying on a different supported LDAP provider.
During initial WebLogic Server domain configuration, the Embedded LDAP is
configured as the one and only User Identity Store for Oracle Access Manager. Within
the Embedded LDAP, the Administrators group is created, with
weblogic
seeded as
the default Administrator:
■Only the User Identity Store designated as the System Store is used to authenticate
Administrators signing in to use the Oracle Access Management Console, remote
registration, and custom administrative commands in WLST.
■Users attempting to access an OAM-protected resource can be authenticated
against any store, not necessarily the only one designated as the Default User
Identity Store.
■Security Token Service uses only the Default User Identity Store. When adding
User constraints to a Token Issuance Policy, for instance, the identity store from
which the users are to be chosen must be Default User Identity Store.
After registering a User Identity Store with Access Manager, administrators can
reference the store in one or more authentication modules, which form the basis for
Oracle Access Manager Authentication Schemes and Policies. When you register a
.cohstore.jks This is used to store the SSL Key and Certificate that is used to
encrypt SSL communication between Coherence nodes. For
information on securing Coherence communications, see the
Oracle Coherence Security Guide.
See Also:
■"About Communication Between OAM Servers and WebGates" on
page 6-4
■"Defining Keystore Settings for Federation" on page 39-4
Table 5–6 (Cont.) Keystores for Access Manager and Security Token Service
Keystore Description
Integrating a Supported LDAP Directory with Oracle Access Manager
Managing Data Sources 5-35
partner (either using the Oracle Access Management Console or the remote
registration tool), an application domain can be created and seeded with a policy that
uses the designated default Authentication Scheme. When a user attempts to access an
Oracle Access Manager-protected resource, she is authenticated against the store
designated by the authentication module. For more information, see Oracle Fusion
Middleware Integration Guide for Oracle Identity Management Suite.
Integrating a Supported LDAP Directory with Oracle Access Manager
5-36 Administrator's Guide for Oracle Access Management
6
Managing Server Registration 6-1
6
Managing Server Registration
[7]
Managed server instances must be registered in order to interact with Oracle Access
Management. (In this book, these managed servers are referred to as OAM Servers.)
Accomplish this registration task using the Oracle Access Management Console.
This chapter contains the following sections:
■Before You Register
■Understanding OAM Server Registration and Management
■Managing Individual OAM Server Registrations
6.1 Before You Register
Ensure that the following environmental considerations are met:
■A new Managed Server has been added to the domain using either the Oracle
WebLogic Server Administration Console or WLST commands.
■The Oracle JRF Template was applied to the Managed Server (or cluster) if needed.
For details, see Oracle Fusion Middleware Administrator's Guide.
Oracle recommends that you review "Understanding OAM Server Registration and
Management".
6.2 Understanding OAM Server Registration and Management
The Oracle Access Management Console is a Java EE application that must be installed
and run on the same computer as the WebLogic Administration Server. Other key
applications that run on the WebLogic Administration Server include the WebLogic
Server Administration Console and Enterprise Manager for Fusion Middleware
Control.
The Oracle Access Management runtime instance deployed on Oracle WebLogic
Managed Servers is referred to as an OAM Server. Each OAM Server must be
registered with Access Manager to enable communication with registered agents
during authentication, authorization, and resource access.
Note: The Oracle Access Management Console might be referred to
as the OAM Administration Server. However, this is not a peer of the
OAM Server deployed on a WebLogic Managed Server.
Understanding OAM Server Registration and Management
6-2 Administrator's Guide for Oracle Access Management
Administrators can extend the WebLogic Server domain and add more OAM Server
instances whenever needed, using either:
■The WebLogic Server Administration Console, after which you manually register
the OAM Server instance using the Oracle Access Management Console
■The WebLogic Configuration Wizard
■Customized Oracle WebLogic Scripting Tool (WLST) commands as described in
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference
The last two methods automatically register the OAM Server instance, which appears
in the Oracle Access Management Console; no additional steps are required.
This section introduces OAM Server instance registration and management using the
Oracle Access Management Console:
■About Individual OAM Server Registrations
■About the Embedded Proxy Server and Backward Compatibility
■About 11g SSO, Legacy 10g SSO in Combination with OSSO 10g
■About Communication Between OAM Servers and WebGates
6.2.1 About Individual OAM Server Registrations
Administrators can add one or more Managed Servers to the WebLogic Server domain
for Oracle Access Management.
When using the WebLogic Configuration Wizard, the OAM Server is automatically
registered. However, if the configuration wizard was not used, the OAM Server must
be registered manually to open a communication channel.
Alternatively. You can use custom WLST commands for OAM to display, edit, or
delete a server registration Any changes are automatically propagated to the Oracle
Access Management Console and to every OAM Server in the cluster.
Only OAM Servers are registered with Oracle Access Management. The Oracle Access
Management Console (on the WebLogic Administration Server) is not registered with
itself.
Regardless of the method used to register an OAM Server, details for each instance are
located on the System Configuration tab, Common Configuration section in the Oracle
Access Management Console, including:
■Server name, Host, Port
■Proxy: Performs as the legacy Access Server and defines the communication
security mode. For more information, see:
–About the Embedded Proxy Server and Backward Compatibility
–About 11g SSO, Legacy 10g SSO in Combination with OSSO 10g
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management.
See Also: Table 1–3 for a comparison of Access Manager 11g versus
Oracle Access Manager 10g.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Understanding OAM Server Registration and Management
Managing Server Registration 6-3
–About Communication Between OAM Servers and WebGates
■Oracle Coherence: Provides a distributed cache for various OAM services,
including session data.
Administrators can search for a specific instance registration, register a newly installed
OAM Server, view, modify, or delete server registrations using the Oracle Access
Management Console. For more information, see "About the OAM Server Registration
Page" on page 6-5.
6.2.2 About the Embedded Proxy Server and Backward Compatibility
Oracle Access Management server-side components include Proxy servers to maintain
backward compatibility with Oracle Access Manager 10g policy-enforcement agents
(10g Webgates and Access Clients) and OracleAS SSO 10g mod_osso (known as OSSO
Agents in 11g), as well as OpenSSO Agents.
Legacy 10g SSO: The OAM Proxy can accept requests from multiple Access clients
concurrently and enables all Webgates and AccessGates (known as Access Clients in
11g) to interact with Access Manager. For more information, see "OAM Proxy Settings"
on page 6-6.
Legacy OracleAS 10g (OSSO): The integrated OSSO proxy handles token generation
and validation in response to token requests during authentication using OSSO Agents
with Access Manager. The OSSO proxy needs no configuration. Simply register the
OSSO agent as described in Chapter 14 and Chapter 15.
6.2.3 About 11g SSO, Legacy 10g SSO in Combination with OSSO 10g
You can upgrade OracleAS SSO to use Access Manager SSO when you have a legacy
deployment where Oracle Access Manager 10g is integrated and used in combination
with OracleAS (OSSO) 10g.
After upgrading OSSO to use Access Manager 11g, you can have 10g Webgates
operating with Access Manager 11g SSO the same deployment. In this situation, the
OAM Proxy forwards requests to either the 10g Access Server or to Access Manager
11g as needed.
The Oracle Access Manager 10g ObSSOCookie is an encrypted session-based single
sign-on cookie that is generated when a user authenticates successfully. The 10g
ObSSOCookie stores user identity information, which you can cache if needed.
The integrated OAM Proxy supports the AES encryption algorithm of the 10g
ObSSOCookie to enable backward compatibility with release 10g Webgates. The 10g
Access Server can decrypt the cookie created by the OAM Proxy (and vice versa). This
allows Access Manager 11g to perform authentication and Oracle Access Manager 10g
to perform authorization (and vice versa).
For more information, see "OAM Proxy Settings" on page 6-6.
See Also: "About 11g SSO, Legacy 10g SSO in Combination with
OSSO 10g"
Note: An Access Manager 11g ObSSOCookie created by OAM Proxy
is compatible with the 10g ObSSOCookie created by Access Server.
Understanding OAM Server Registration and Management
6-4 Administrator's Guide for Oracle Access Management
6.2.4 About Communication Between OAM Servers and WebGates
Communication modes for the OAP channel include:
■Open: Use this unencrypted mode if communication security is not an issue in
your deployment.
■Simple: Use this Oracle-signed certificate mode if you have some security
concerns, such as not wanting to transmit passwords as plain text, but you do not
manage your own Certificate Authority (CA).
■Cert: Use if you want different certificates on OAM Servers and WebGates and
you have access to a trusted third-party CA.
On each individual OAM Server registration, the security mode is defined on the
Proxy tab, as described in "About the OAM Server Registration Page" on page 6-5.
Simple and Cert modes also require:
■Security passwords that are common to all OAM Servers and WebGates, as
described in "Managing the Access Protocol for OAM Proxy Simple and Cert
Mode Security" on page 13-6.
■Appropriately signed X.509 digital certificates, as described in Appendix C,
"Securing Communication".
At least one OAM Server instance must be running in the same mode as the agent
during agent registration. Otherwise, agent registration fails. After agent registration,
however, you can change the communication mode of the OAM Server.
Communication between the agent and server would continue to work as long as the
Webgate mode is at least at the same level as the OAM Server mode or higher. The
agent mode can be higher but cannot be lower. For example, of OAM Server mode is
Open, agents can communicate in any of the three modes. If OAM Server mode is
Simple, agents can use Simple or Cert mode. If OAM Server mode is Cert, agents must
use Cert mode.
6.2.5 About Restarting Servers After Configuration Changes
Most Oracle Access Management functional services take up changes made through
the Oracle Access Management Console without restarting OAM Server. Table 6–1
identifies conditions that do require a server restart.
See Also: Appendix C, "Securing Communication"
Table 6–1 Conditions Requiring Server Restart
Event Description
Session persistence change A change from database to in-memory (or vice versa) session
persistence requires an OAM Server restart.
Oracle Coherence port
number
A change to the port number requires an OAM Server restart.
Load balancer server
definition
A change requires an OAM Server restart.
Managed Server port number A change requires an OAM Server restart.
New Managed Server Adding a new managed server to the cluster requires
restarting the AdminServer to policy enable uptake.
OAM Servers must be restarted to reinitialize Oracle
Coherence security configuration with the new server
included.
Managing Individual OAM Server Registrations
Managing Server Registration 6-5
6.3 Managing Individual OAM Server Registrations
This section describes how to register and manage OAM Server instances using the
Oracle Access Management Console. Topics here include:
■About the OAM Server Registration Page
■Registering a Fresh OAM Server Instance
■Viewing or Editing Individual OAM Server Registrations and Proxy Settings
■Deleting an Individual Server Registration
6.3.1 About the OAM Server Registration Page
Users with valid Administrator credentials can register a freshly installed Managed
Server (OAM Server instance) or modify an existing OAM Server registration using
the Oracle Access Management Console.
Alternatively: You can use custom WLST commands to register and manage OAM
Server instances. Changes are reflected in the Oracle Access Management Console and
are automatically propagated to every OAM Server in the cluster.
Figure 6–1 illustrates a typical OAM Server registration page when viewed within the
Oracle Access Management Console. To access the OAM Server registration page
using the Oracle Access Management Console, click Configuration in the top right of
the console and then click the Server Instances link on the Configuration page. From
the resulting Server Instances search page, click Create in the Search Results table to
display the Create: OAM Server page. See Section 6.3.2, "Registering a Fresh OAM
Server Instance" for details on how to configure this page.
Figure 6–1 OAM Server Registration Page with Proxy Tab Displayed
Individual server registration settings are described in Table 6–2.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Managing Individual OAM Server Registrations
6-6 Administrator's Guide for Oracle Access Management
6.3.1.1 OAM Proxy Settings
An integrated proxy server (OAM Proxy) is installed with each Managed Server for
OAM Server. The OAM Proxy is used as a legacy Access Server to provide backward
compatibility for 10g Agents that are registered with Access Manager 11g. The Agent
can be freshly installed or currently operating within an Oracle Access Manager 10g
SSO deployment.
Each OAM Proxy instance requires a different port. The proxy starts listening when
the application starts. Registered access clients can immediately communicate with the
proxy.
The OAM Proxy handles both configuration and run-time events. Each OAM Proxy
can accept requests from multiple access clients concurrently. Each OAM Proxy
enables access clients to interact with Access Manager 11g. This includes:
■10g (10.1.4.3) WebGates
■10g (10.1.4.2.0) WebGates
■10g (10.1.4.0.1) WebGates
■11g WebGates (needs no proxy)
OAM Proxy settings are documented in Table 6–3.
Table 6–2 OAM Server Instance Settings
Element Definition
Server name The identifying name for this server instance, which was defined during initial
deployment in the WebLogic Server domain.
Host The full DNS name (or IP address) of the computer hosting the server instance. For
example: host2.domain.com.
Port The port on which this server communicates (listens and responds).
Default: 5575
Note: If both the SSL and Open ports of the Managed Server are enabled, then the
Managed Server is set to the SSL port by default. If you must use the non-SSL port,
the credential collector URL of the authentication scheme must be set to the absolute
URL which points to
http
as the protocol and non-SSL port.
See Also: Appendix C, "Securing Communication"
Proxy See "OAM Proxy Settings" on page 6-6
Coherence See "Coherence Settings for Individual Servers" on page 6-7
See Also: "Managing Individual OAM Server Registrations" on
page 6-5
Note: For Access Clients, Access Manager 11g provides
authentication and authorization functionality only. Policy
modification through Access Clients is not supported.
Table 6–3 OAM Proxy Settings for an Individual OAM Server
OAM Proxy Setting Value
Port The unique port on which this OAM Proxy instance is listening.
On a default installation, the port is 5575.
Managing Individual OAM Server Registrations
Managing Server Registration 6-7
OAM Proxy Logging: Oracle Access Management services use the same logging
infrastructure as any other Oracle Fusion Middleware 11g component, as described in
Chapter 8. However, OAM Proxy uses Apache log4j for logging.
6.3.1.2 Coherence Settings for Individual Servers
Coherence provides replicated and distributed (partitioned) data management and
caching services on top of a reliable, highly scalable peer-to-peer clustering protocol.
Coherence has no single points of failure; it automatically and transparently fails over
and redistributes its clustered data management services when a server becomes
inoperative or is disconnected from the network.
When a new server is added, or when a failed server is restarted, it automatically joins
the cluster and Coherence fails back services to it, transparently redistributing the
cluster load. Coherence includes network-level fault tolerance features and transparent
soft re-start capability to enable servers to self-heal.
Coherence modules consist of the values, and types for the individual server instance,
as shown in Figure 6–1.
Proxy Server ID The identifier of the computer on which the OAM Proxy (and this OAM Server
instance) resides. DNS hostname is preferred; however, you can use any valid
and relevant string.
On a default installation, the Proxy Server ID is AccessServerConfigProxy.
Mode OAM channel transport security for the OAM Proxy can be one of the following
(the agent mode must match during registration and can be higher after
registration):
■Open: No encryption.
■Simple: The data passed between the OAM Agent and OAM Server is
encrypted using OAM self-signed certificates.
Before specifying Simple mode, you must specify the global passphrase.
■Cert: The data between the OAM Agent and OAM Server is encrypted
using Certificate Authority (CA) signed X.509 certificates.
Note: Before specifying Cert mode, you must acquire signed certificates
from a trusted third party Certificate Authority.
On a default installation, the Mode is Open.
Note: Simple and Cert transport security modes are governed by information
defined on the OAM Server Common Properties OAM Proxy tab, as described in
"Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security"
on page 13-6.
See Also: Appendix C if you are configuring Simple or Cert transport security
modes.
WARNING: Oracle recommends that you do not modify Oracle
Coherence settings for an individual server unless you are
requested to do so by an Oracle Support Representative.
Table 6–4 Default Coherence Settings for Individual OAM Servers
Coherence
Module Type of Entry Description and Default Values
LogLevel String The Coherence log level (from 0 to 9) for OAM Server events.
LogPort int (integer) The listening port for Coherence logging on the WebLogic Server.
Table 6–3 (Cont.) OAM Proxy Settings for an Individual OAM Server
OAM Proxy Setting Value
Managing Individual OAM Server Registrations
6-8 Administrator's Guide for Oracle Access Management
Coherence Logging: Appears only in the WebLogic Server log. There is no bridge from
Oracle Coherence logging to Oracle Access Management logging. For Oracle Fusion
Middleware 11g logging infrastructure details, see Chapter 7.
6.3.2 Registering a Fresh OAM Server Instance
Users with valid Administrator credentials can perform the following task to register a
new Managed Server (OAM Server) instance using the Oracle Access Management
Console.
Before you begin, the new Managed Server instance must be configured in the Oracle
WebLogic Server domain, but not yet started.
1. Install the new Managed Server instance and configure it in the Oracle WebLogic
Server domain, but do not start this instance.
2. Log in to the Oracle Access Management Console and click Configuration in the
top bar.
3. In the Configuration console, click Server Instances.
4. In the tab that appears, click Create OAM Server.
The OAM Server registration page illustrated in Figure 6–1 is displayed.
5. On the Create: OAM Server page, enter details for your instance, as described in
Table 6–2:
■Server name
■Host
■Port
6. Proxy: Enter or select details for this OAM Proxy instance, as described in
Table 6–3:
■Port
■Proxy Server ID
■Mode (Open, Simple, or Cert)
7. Coherence: Oracle recommends that you do not modify Oracle Coherence settings
for an individual server instance unless you are requested to do so by an Oracle
Support Representative.
LogLimit String The Coherence log limit
Note: Each OAM Server must be registered to communicate with
agents.
See Also: Appendix C if you are using Simple or Cert mode
See Also: "Using Coherence" on page E-29
Table 6–4 (Cont.) Default Coherence Settings for Individual OAM Servers
Coherence
Module Type of Entry Description and Default Values
Managing Individual OAM Server Registrations
Managing Server Registration 6-9
8. Click Apply to submit the configuration, which should appear in the navigation
tree (or close the page without applying changes).
9. Start the newly registered server.
6.3.3 Viewing or Editing Individual OAM Server Registrations and Proxy Settings
Users with valid Administrator credentials can perform the following task to view or
modify settings for an individual server instance using the Oracle Access Management
Console. (For instance, you might need to change the listening port or the Proxy
communication transport security mode.) Changes made are immediately visible in
the Oracle Access Management Console and propagated to all OAM Servers in the
cluster.
1. At the top of the Oracle Access Management Console, click Configuration.
2. In the Configuration console, click Server Instances.
3. In the page that appears, click Search, then double-click the target instance to
display its configuration, and then proceed as follows:
■View Only: Close the page when you finish viewing details.
■Modify: Perform remaining steps to edit the configuration.
4. On the OAM Server page, change details for your instance, as described in
Table 6–2.
5. Proxy: Change details for this OAM Proxy instance, as described in Table 6–3.
6. Coherence: Oracle recommends that you do not modify Oracle Coherence settings
for an individual server instance unless you are requested to do so by an Oracle
Support Representative.
7. Click Apply to submit the changes (or close the page without applying change).
6.3.4 Deleting an Individual Server Registration
Users with valid Administrator credentials can perform the following task to delete an
OAM server registration, effectively disabling it.
See Also:
■Oracle Fusion Middleware Installation Guide for Oracle Identity
and Access Management
■"About the OAM Server Registration Page" on page 6-5
See Also:
■"About the OAM Server Registration Page" on page 6-5
■Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference
■Moving Identity Management to a New Production Environment
in the Oracle Fusion Middleware Administrator's Guide
See Also: Appendix C if you are using Simple or Cert mode
See Also: "Using Coherence" on page E-29
Managing Individual OAM Server Registrations
6-10 Administrator's Guide for Oracle Access Management
1. At the top of the Oracle Access Management console, click Configuration.
2. In the Configuration console, click Server Instances.
3. In the tab that appears, double-click the target instance to confirm its details, then
close the tab.
4. In the list of instances, select the target instance, click Delete in the tool bar, and
confirm removal in the dialog that appears.
5. Confirm that the instance has been removed from the instance list.
6. Remove the deleted instance from the WebLogic Server Administration Console.
The Node Manager on Managed Server host handles the rest automatically.
Part III
Part III
Logging, Auditing, Reporting and Monitoring
Performance
Part III provides information to help you perform logging, auditing, and performance
monitoring for Oracle Access Management services. It contains the following chapters:
■Chapter 7, "Logging Component Event Messages"
■Chapter 8, "Auditing Administrative and Run-time Events"
■Chapter 9, "Logging WebGate Event Messages"
■Chapter 10, "Reporting"
■Chapter 11, "Monitoring Performance and Health"
■Chapter 12, "Monitoring Performance and Logs with Fusion Middleware Control"
7
Logging Component Event Messages 7-1
7
Logging Component Event Messages
[8]
Logging is the mechanism by which components and services write messages to a log
file in order to capture critical component events, processes, and state information.
Administrators can configure logging to provide information at various levels of
granularity using the same logging infrastructure and guidelines as any other
component in Oracle Fusion Middleware 11g:
java.util.logging
(standard and
available in all Java environments).
Configuring logging and locating log files are the focus of this chapter which contains
the following sections.
■About Oracle Access Management Logging
■Logging Component Event Messages
■Configuring Logging for Access Manager
■Configuring Logging for Security Token Service and Identity Federation
■About Mobile and Social Logging
■Understanding Logging for the Access Portal Service
■Validating Run-time Event Logging Configuration
7.1 About Oracle Access Management Logging
The logging system writes output to flat files only. Logging to an Oracle Database
instance is not supported. Unless explicitly stated, information in this chapter is the
same whether using any of the services in Oracle Access Management. Additionally:
■You can use a custom Oracle WebLogic Scripting Tool (WLST) command to change
logging levels.
■Diagnosing problems using the information in log files is outside the scope of this
chapter.
■Before you can perform tasks in this chapter ensure that the Oracle Access
Management Console and a managed OAM Server are running.
Oracle also recommends that you review Chapter 6, "Managing Server Registration."
7.2 Logging Component Event Messages
The logging infrastructure records messages that can be used for problem diagnosis.
Security Token Service is a J2EE Web application, part of the Access Manager J2EE
Application. Both use OJDL for logging purposes. Security Token Service captures the
interactions between itself and Partners with timestamps.
Logging Component Event Messages
7-2 Administrator's Guide for Oracle Access Management
The Administrator controls the amount of information that is logged in a message by
specifying log levels for each component for which a logger is defined.
Oracle Access Management makes use of the files in Table 7–1.
Oracle Access Management uses the WebLogic container's logging defaults in
Table 7–2.
For more information, see:
■About Component Loggers
■Sample Logger and Log Handler Definition
■About Logging Levels
Note: Generally, you enable logging to produce files that you send to
Oracle Technical Support for problem diagnosis. Documentation for
log messages is not available. In some cases, you might be able to
diagnose problems on your own by reading log files.
Table 7–1 Logging Files
File Type Description
Logging Configuration
File
Provides logging level and other configuration information for logging. This file
is stored in the following path:
$DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml
Note: By default, Security Token Service and Identity Federation messages are
logged in the OAM Server's log file. However, for convenience, you can edit
logging.xml to direct Security Token Service or Identity Federation information
to a separate log file, as described in "Configuring Logging for Security Token
Service and Identity Federation" on page 7-8.
Log File Logged information is stored in the following location:
$DOMAIN_HOME/servers/SERVER-NAME/logs/
SERVER-NAME-diagnostics.log
Table 7–2 Logging Defaults
Description
Events The following events are logged automatically:
■OAM Server events (managed run-time servers)
■Administrative events (generated for configuration changes made
using the console)
Levels By default, the log level for all Oracle Access Management components
is the Notification level. Logging at the Error level produces a small
amount of output while other log levels can result in voluminous
logging output, which can impact performance. In production
environments, logging is usually either disabled or the log level is set
to a level that results in a small volume of logging output (the error
level, for example).
See Also:
■Chapter 12 for details about how you can configure and view logs
using Fusion Middleware Control
■Logging information in the Oracle Fusion Middleware
Application Security Guide
Logging Component Event Messages
Logging Component Event Messages 7-3
7.2.1 About Component Loggers
This section introduces component loggers for Security Token Service and Access
Manager. There are differences.
Security Token Service has only a single logger: oracle.security.fed. For more
information, see "Configuring Logging for Security Token Service and Identity
Federation" on page 7-8.
Each Access Manager component is associated with its own logger name, as listed in
the following tables:
■Table 7–3, " Oracle Access Management Server-Side Component Loggers"
■Table 7–4, " Oracle Access Management Shared-Service Engine Component
Loggers"
■Table 7–5, " Oracle Access Management Foundation API Component Loggers"
Table 7–3 Oracle Access Management Server-Side Component Loggers
Component Name OAM Logger Name Description
Protocol Binding oracle.oam.binding Responsible for marshalling/unmarshalling wire
protocol request and response to a Java Object
representation.
SSO Controller oracle.oam.controller.sso Responsible for managing the user session
lifecycle and orchestrating the SSO and logout
flows.
OAM Proxy oracle.oam.proxy.oam Responsible for interacting with OAM Webgates
by marshalling/unmarshalling OAP protocol
requests and responses and performing the
data/message transformation necessary to help
the OAM Server process OAP
requests/responses.
OSSO Proxy oracle.oam.proxy.osso Responsible for interacting with OSSO Agents by
marshalling/unmarshalling requests and
responses and doing the data/message
transformation necessary to help the OAM Server
process mod_osso requests/responses.
OpenSSO Proxy oracle.oam.proxy.opensso Responsible for interacting with OpenSSO Web
and Java Agents by marshalling/unmarshalling
requests and responses and performing the
data/message transformation necessary to help
the OAM Server process OpenSSO agent
requests/responses.
Credential Collector oracle.oam.credcollector Responsible for interacting with the user to
acquire the necessary information required by the
Authentication Scheme.
Remote Registration of Partners oracle.oam.engine.remotereg Responsible for registering partners with the
OAM Server and managing associated protected
policies.
Oracle Access Management Console oracle.oam.admin.console Console that supports administration and
monitoring of the Access Management
deployment.
Admin-Service Config oracle.oam.admin.service.config Module used by the UI Console to manage the
configuration.
Diagnostics and Monitoring oracle.oam.diag Provides instrumentation used by the OAM
Server components to enable Diagnostic and
Monitoring.
Logging Component Event Messages
7-4 Administrator's Guide for Oracle Access Management
7.2.2 Sample Logger and Log Handler Definition
This topic provides a sample for Access Manager only.
Example 7–1 illustrates the configuration of an Access Manager logger and a log
handler in the file
logging.xml
.
Example 7–1 Configuring Access Manager Loggers and Log Handlers
<logging_configuration>
<log_handlers>
<log_handler name='oam-handler' class='oracle.core.ojdl.logging.
ODLHandlerFactory'>
<property name='path' value='oam/diagnostic'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
</log_handler>
</log_handlers>
<loggers>
<logger name='oracle.security.am' level='NOTIFICATION:1'>
Table 7–4 Oracle Access Management Shared-Service Engine Component Loggers
Component Name OAM Logger Name Description
Authentication Engine oracle.oam.engine.authn Supports establishing the identity of the user by
validating the credentials and other data as
required by the specified Authentication scheme.
Policy Service Engine oracle.oam.engine.policy Supports management of Authentication,
Authorization and Token Issuance Policies. In
addition, it also provide a policy decision service
to support runtime processing.
Session Management Engine oracle.oam.engine.session Supports managing user session and token
context information with support for
user/administrator-initiated and time-out based
events.
Token Engine oracle.oam.engine.token Supports managing the entire token life cycle
from generation to cancellation.
SSO Engine oracle.oam.engine.sso Supports the single sign-on experience by
managing the lifecycle of the user login
session(s).
PartnerTrustMetadata Engine oracle.oam.engine.ptmetadata Supports management of partner metadata and
trust information.
Authorization Engine oracle.oam.engine.authz Wrapper that provides methods that map
directly to OAP runtime request operations.
Table 7–5 Oracle Access Management Foundation API Component Loggers
Component Name OAM Logger Name Description
Session Access oracle.oam.session.access ** Not useful unless your are decompiling code.
Session Access Implementation oracle.oam.session.accessimpl ** Not useful unless your are decompiling code.
Policy Access oracle.oam.policy.access ** Not useful unless your are decompiling code.
Note: Security Token Service has only one logger and log handler, as
described in "Configuring Logging for Security Token Service and
Identity Federation" on page 7-8.
Configuring Logging for Access Manager
Logging Component Event Messages 7-5
<handler name='oam-handler'/>
...
</logger>
</loggers>
</logging_configuration>
7.2.3 About Logging Levels
This topic applies to Oracle Access Management.
The amount of data output by a logger is controlled by its level; the higher the level,
the more information is logged. The level of a logger is specified with the element
<logger> in the file logging.xml with the following format:
<logger name="loggerName" level="notifLevel"/>
where loggerName is a logger name (see "About Component Loggers"), and notifLevel is
either an ODL message level or a Java message level.
Table 7–6 shows the correspondence between ODL message levels and Java message
levels, in increasing order:
Any other Java level value not listed above (that is, one outside the interval
[SEVERE.intValue()+100 - FINEST] is mapped to the ODL level UNKNOWN.
7.3 Configuring Logging for Access Manager
This section describes tasks for only Access Manager.
See Also: For more information about Java EE application logging,
see Appendix I, section I.1.1, in Oracle Fusion Middleware
Application Security Guide.
Table 7–6 Mapping of ODL to Java Levels
ODL Message Level Java Message Level
INCIDENT_ERROR:1 SEVERE.intValue()+100
ERROR:1 SEVERE (logs exceptions)
WARNING:1 WARNING (logs exceptions)
NOTIFICATION:1 INFO (default)
NOTIFICATION:16 CONFIG
NOTIFICATION:32 INFO and CONFIG
TRACE:1 FINE (occasionally recommended in production environments)
TRACE:16 FINER (not recommended in production environments)
TRACE:32 FINEST (not recommended in production environments)
Note: If you define a filter to log messages at the finest level for the
oracle.security.fed package and sub-package (classes for Security
Token Service), after restarting the server you would see logs for the
OAM Server. For more information, see "Configuring Logging for
Security Token Service and Identity Federation" on page 7-8.
Configuring Logging for Access Manager
7-6 Administrator's Guide for Oracle Access Management
There is no graphical user interface available to change logger levels; only WLST
commands can be used. This section provides the following topics:
■Modifying the Logger Level for Access Manager
■Adding an Access Manager-Specific Logger and Log Handler
7.3.1 Modifying the Logger Level for Access Manager
Administrators can use custom WLST commands for Access Manager to change
logger settings as described in the following procedure. Your deployment and choices
will be different.
Follow this procedure to modify the OAM logger level.
1. Confirm that the OAM Server is running.
2. Acquire the custom WLST script for Access Manager. For example:
$ORACLE_HOME/common/bin/wlst.sh
3. Connect to the WebLogic Server and log in as the WebLogic Administrator. For
example:
connect([username, password])
4. List available loggers for the OAM Server. For example:
wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",
target="oam_server1")
wls:/WLS_IDM/serverConfig> listLoggers(pattern="oracle.oam.*",
target="oam_policy_mgr1")
Here pattern= represents the oam.controller component and target= represents the
desired OAM Server as it was specified during registration.
5. View the list of Access Manager loggers associated with this OAM Server. For
example:
Logger | Level
--------------------------------------------+-----------------
oracle.oam | <Inherited>
oracle.oam.admin.foundation.configuration | <Inherited>
oracle.oam.agent-default | <Inherited>
oracle.oam.audit | <Inherited>
oracle.oam.binding | <Inherited>
oracle.oam.commonutil | <Inherited>
oracle.oam.config | <Inherited>
oracle.oam.controller | <Inherited>
oracle.oam.default | <Inherited>
See Also: "Configuring Logging for Security Token Service and
Identity Federation"
Note: Use the WLST command
help("fmw diagnostics")
.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Configuring Logging for Access Manager
Logging Component Event Messages 7-7
oracle.oam.diagnostic | <Inherited>
oracle.oam.engine.authn | <Inherited>
oracle.oam.engine.authz | <Inherited>
oracle.oam.engine.policy | <Inherited>
oracle.oam.foundation.access | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.user.identity.provider | <Inherited>
6. Modify the log level based on your requirements. For example, this sequence
changes the log level of the oam.controller to TRACE:32 with no persistence:
wls:/base_domain/serverConfig> domainRuntime()
wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam.controller",
level="TRACE:32", persist="0", target="oam_server1")
wls:/WLS_IDM/domainRuntime> setLogLevel(logger="oracle.oam", level="TRACE:32",
persist="0", target="oam_policy_mgr1")
7. Repeat step 4 to list the loggers again and verify the log level change. For example:
wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",target="oam_
server1")
Logger | Level
--------------------------------------------+-----------------
oracle.oam | <Inherited>
oracle.oam.admin.foundation.configuration | <Inherited>
oracle.oam.agent-default | <Inherited>
oracle.oam.audit | <Inherited>
oracle.oam.binding | <Inherited>
oracle.oam.commonutil | <Inherited>
oracle.oam.config | <Inherited>
oracle.oam.controller | TRACE:32
oracle.oam.default | <Inherited>
oracle.oam.diagnostic | <Inherited>
oracle.oam.engine.authn | <Inherited>
oracle.oam.engine.authz | <Inherited>
oracle.oam.engine.policy | <Inherited>
oracle.oam.foundation.access | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.idm | <Inherited>
oracle.oam.user.identity.provider | <Inherited>
8. Verify the generated log file to confirm the controller is logged at the TRACE:32
level:
$DOMAIN_HOME/server/SERVER_INSTNCE_NAME/logs/
9. Proceed to "Validating Run-time Event Logging Configuration" on page 7-11.
7.3.2 Adding an Access Manager-Specific Logger and Log Handler
Administrators can use the following procedure to specify a log file path and
necessary attributes.
In the following procedure, you will identify the target OAM Server, rotation and
retention periods, a path to the log file, the handler, and logger. Your deployment and
choices will be different.
Configuring Logging for Security Token Service and Identity Federation
7-8 Administrator's Guide for Oracle Access Management
Skip steps 1 through 3 if the following items are true:
■The OAM Server is running
■You have the WLST script
■You have connected to the server and logged in
Follow this procedure to specify the OAM logger. level and log handler.
1. Confirm that the OAM Server is running.
2. Acquire the WLST script. For example:
$ORACLE_HOME/common/bin/wlst.sh
3. Connect to the WebLogic Server and log in as the WebLogic Administrator. For
example:
sh wlst.sh wls:/offline> connect
4. Add an Access Manager logger and level for the OAM Server. For example:
wls:/base_domain/serverConfig> domainRuntime()
wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam",
level="WARNING", persist="0", target="oam_server1")
5. Add a custom log handler and associate it with the Access Manager logger. For
example:
wls:/base_domain/domainRuntime> configureLogHandler(name="oam-log-handler",
target="oam_server1", rotationFrequency="daily", retentionPeriod="week",
path="${domain.home}/oamlogs" , maxFileSize ="10485760", maxLogSize =
"104857600", addHandler="true", handlerType="oracle.core.ojdl.logging
.ODLHandlerFactory", addToLogger="oracle.oam")
wls:/base_domain/domainRuntime>configureLogHandler(name="oam-log-handler",
addProperty="true", propertyName="supplementalAttributes", propertyValue=
"OAM.USER, OAM.COMPONENT", target="oam_server1")
6. Verify all the logs in the $DOMAIN_HOME/oamlogs directory:
$DOMAIN_HOME/oamlogs/
7.4 Configuring Logging for Security Token Service and Identity
Federation
By default Security Token Service and Identity Federation messages are logged into
the OAM Server's log files. You can view and configure these logs in Fusion
Middleware Control. However, you can also edit
logging.xml
and direct Security
Token Service and Identity Federation information to a separate log file, as described
in this section. The files involved in this procedure are:
Note: Use the WLST command
help("fmw diagnostics")
to get
more information.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Configuring Logging for Security Token Service and Identity Federation
Logging Component Event Messages 7-9
■Logging Configuration File: Provides logger names and other configuration
information for logging. This file is stored in: $DOMAIN_
HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml.
■Log File: $DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log, for
example.
Security Token Service and Identity Federation do not categorize log handlers as
Access Manager does. Instead, there is only one logger that affects the log levels for
Security Token Service and Identity Federation. Table 7–7 provides details for this
logger, which are required in the WLST command.
For details, see:
■Configuring Logging for Security Token Service or Identity Federation
■Defining Log Level and Log Details for Security Token Service or Identity
Federation
7.4.1 Configuring Logging for Security Token Service or Identity Federation
Administrators can use the following procedure to separate Security Token Service or
Identity Federation log messages from OAM Server message logs.
1. Locate and open logging.xml: $DOMAIN_
HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml.
2. Add the following to create the independent message log for Security Token
Service and Identity Federation:
<log_handler name='stsfed-handler' class='oracle.core.ojdl.logging.ODLHand
lerFactory'>
<property name='path' value='sts/log'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
</log_handler>
<logger name='oracle.security.fed' level='TRACE:32'>
<handler name='stsfed-handler'/>
</logger>
3. Save the file.
4. Proceed with "Defining Log Level and Log Details for Security Token Service or
Identity Federation".
Table 7–7 Oracle Security Token Service and Identity Federation Loggers
Component Name Logger Name Log Handler Name Log Class
Security Token Service or
Identity Federation
oracle.security.fed stsfed-handler class=oracle.core.ojdl.loggi
ng.ODLHandlerFactory
See Also:
■Chapter 12 for details about how you can configure and view logs
using Fusion Middleware Control
■Logging information in the Oracle Fusion Middleware
Application Security Guide
Configuring Logging for Security Token Service and Identity Federation
7-10 Administrator's Guide for Oracle Access Management
7.4.2 Defining Log Level and Log Details for Security Token Service or Identity
Federation
Administrators can use custom WLST commands for Oracle Access Management to
change logger settings for Security Token Service as described here. This specifies an
independent output file for only Security Token Service log messages.
Skip steps 1 through 3 if the following items are true:
■The OAM Server is running
■You have the WLST script
■You have connected to the server and logged in
This sample procedure for Security Token Service logging is very similar to the one for
Access Manager. However, there are a few differences. Your deployment choices will
be different.
1. Confirm that the OAM Server is running.
2. Acquire the custom WLST script for Oracle Access Management:
$ORACLE_HOME/common/bin/wlst.sh
3. Connect to the WebLogic Server and log in as the WebLogic Administrator. For
example:
sh wlst.sh wls:/offline> connect adminID password
4. Modify the log level of
oracle.security.fed
based on your requirements. For
example, this sequence changes the log level to WARNING with no persistence:
wls:/base_domain/serverConfig> domainRuntime()
wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.security.fed",
level="WARNING", persist="0", target="oam_server1")
5. Specify the target OAM Server, as well as rotation and retention periods, path to
the log file, the handler, and logger. For example:
wls:/base_domain/domainRuntime> configureLogHandler(name="osts-log-handler",
target="oam_server1", rotationFrequency="daily", retentionPeriod="week",
path="${domain.home}/ostslogs", maxFileSize ="10485760", maxLogSize
="104857600", addHandler="true",handlerType="oracle.core.ojdl.logging.ODL
HandlerFactory", addToLogger="oracle.security.fed")
6. Verify the generated log file to confirm the controller is logged at the WARNING
level:
$DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log
$DOMAIN_HOME/oiflogs/SERVER-NAME-diagnostics.log
7. Proceed to "Validating Run-time Event Logging Configuration" on page 7-11.
Note: Use the WLST command
help("fmw diagnostics")
.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Validating Run-time Event Logging Configuration
Logging Component Event Messages 7-11
7.5 About Mobile and Social Logging
For information about Fusion Middleware logging, see the "Monitoring Oracle Fusion
Middleware" chapter in the Oracle Fusion Middleware Administrator's Guide.
For information about Fusion Middleware auditing, see the "Configuring and
Managing Auditing" chapter in the Oracle Fusion Middleware Application Security Guide.
7.6 Understanding Logging for the Access Portal Service
The Access Portal Service logs five events to the Oracle Access Management table.
■CredentialAdded
■CredentialDeleted
■ CredentialModified
■Login
■CredentialChange_Password
The Access Portal Service uses the Common Audit Framework (CAF) for auditing. To
enable CAF, set the
UseCAF
property in the
oam-config.xml
file to
true
.
7.7 Validating Run-time Event Logging Configuration
You can use the following procedure to test your run-time event logging configuration.
Before you begin:
■Configure logging using WLST commands as described in this chapter.
■Ensure the Agents and Servers are running.
■Configure an Application Domain to protect the resource as described in
Chapter 25, "Managing Policies to Protect Resources and Enable SSO".
1. In a browser, enter the URL to a protected resource and sign in using an invalid
credential.
2. Sign in again using the proper credential.
3. On the physical server, verify all the logs appear in:
$DOMAIN_HOME/oamlogs/
$DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log
$DOMAIN_HOME/oiflogs/SERVER-NAME-diagnostics.log
4. Open the log file and look for the last entries to confirm authentication failure and
success, respectively.
Validating Run-time Event Logging Configuration
7-12 Administrator's Guide for Oracle Access Management
8
Auditing Administrative and Run-time Events 8-1
8
Auditing Administrative and Run-time Events
[9]
In Oracle Fusion Middleware, auditing refers to the process of collecting for review
specific information related to administrative, authentication, and run-time events.
Auditing can help you evaluate adherence to polices, user access controls, and risk
management procedures, and provides a measure of accountability and answers to the
"who has done what and when" types of questions. Audit data can be used to create
dashboards, compile historical data, and assess risks. Analyzing recorded audit data
allows compliance officers to perform periodic reviews of compliance policies.
(Analyzing and using audit data is outside the scope of this chapter.)
This chapter describes the administrative and run-time events that can be audited for
Oracle Access Management services as well as information on configuring common
auditing settings and validating your auditing configuration.
■Introduction to Oracle Fusion Middleware Auditing
■Understanding Oracle Access Management Auditing
■Access Manager Events You Can Audit
■Mobile and Social Events You Can Audit
■Identity Federation Events You Can Audit
■Security Token Service Events You Can Audit
■Setting Up Auditing for Oracle Access Management
■Validating Auditing and Reports
8.1 Introduction to Oracle Fusion Middleware Auditing
Review the following sections in the Oracle Fusion Middleware Application Security Guide
to gain an understanding of auditing and the Audit Framework in Oracle Fusion
Middleware.
■Introduction to Oracle Fusion Middleware Audit Framework
■Setting up Oracle Business Intelligence Publisher
■Customizing Audit Reports
■"Auditing the Security Token Service" on page 43-21
■Oracle Fusion Middleware Audit Framework Reference for details about how the
Audit database is laid out
Understanding Oracle Access Management Auditing
8-2 Administrator's Guide for Oracle Access Management
8.2 Understanding Oracle Access Management Auditing
Many businesses must now be able to audit identity information and user access on
applications and devices. Compliance audits help an enterprise conform with
regulatory requirements—Sarbanes-Oxley or the Health Insurance Portability and
Accountability Act (HIPAA) are two examples.
Oracle Access Management uses the Oracle Fusion Middleware Common Audit
Framework to support auditing for a large number of user authentication and
authorization run-time events, and administrative events (changes to the system). The
Oracle Fusion Middleware Common Audit Framework provides uniform logging and
exception handling and diagnostics for all audit events.
Auditing is based on configuration parameters set using the Oracle Access
Management Console which enables data capture for a user or set of users. While
auditing can be enabled or disabled, it is normally enabled in production
environments. Audit data can be written to either a single, centralized Oracle Database
instance or to flat files known as bus-stop files.
Auditing has minimal performance impact, and the information captured by auditing
can be useful (even mission-critical). The audit log file helps the audit Administrator
track errors and diagnose problems if the audit framework is not working properly.
This section contains the following topics.
■About Oracle Access Management Auditing Configuration
■About Audit Record Storage
■About Audit Reports and Oracle Business Intelligence Publisher
■About the Audit Log and Data
8.2.1 About Oracle Access Management Auditing Configuration
An Administrator controls certain auditing parameters using the Oracle Access
Management Console. This auditing configuration is recorded in the
oam-config.xml
file. Additional auditing configuration is required through the Common Audit
Framework.
Note: There is nothing specific or separate related to auditing
OpenSSO Agents or Identity Context. Unless explicitly stated,
information in this chapter is the same for all Oracle Access
Management services.
Note: The Oracle Fusion Middleware Common Audit Framework
database audit store does not include Access Manager policy or
session-data and is not configured through the Oracle Access
Management Console.
Note: Oracle recommends that you use only the Oracle Access
Management Console or WebLogic Scripting Tool (WLST) commands
for changes; do not edit the
oam-config.xml
file directly.
Understanding Oracle Access Management Auditing
Auditing Administrative and Run-time Events 8-3
Event configuration (mapping events to levels) occurs in the
component_events.xml
file. An audit record contains a sequence of items that can be configured to meet
particular requirements.
Within the Oracle Access Management Console, you can set the maximum log file and
log directory size. Audit policies (known as Filter Presets declare the types of events to
be captured by the audit framework for particular components.
Audit policies cannot be configured using Fusion Middleware Control. Oracle Access
Management does not use JPS infrastructure to configure the audit configuration.
There are no WebLogic Scripting Tool (WLST) commands for auditing.
8.2.2 About Audit Record Storage
Audit data can be written to either a single, centralized Oracle Database instance or to
flat files known as bus-stop files. By default, audit data is recorded to the file but
administrators can change the configuration to log audit data to a database. Although
the formats differ, audit data content is identical in both the flat file and the database.
■Audit Bus-stop: Local files containing audit data records before they are pushed to
the audit data store. In the event that no audit data store is configured, audit data
remains in these bus-stop files. The bus-stop files are simple text files that can be
queried easily to look up specific audit events. When an audit data store is in
place, the bus-stop acts as an intermediary between the component and the audit
data store. The local files are periodically uploaded to the audit data store based
on a configurable time interval.
Bus-stop files for Java components are located in:
$DOMAIN_HOME/servers/$SERVER_NAME/logs/auditlogs/OAM/audit.log
Bus-stop files for system components are located in:
$ORACLE_INSTANCE/auditlogs/OAM/oam_server1/audit.log
■Database Logging: Implements the Common Auditing Framework across a range
of Oracle Fusion Middleware products. The benefit is audit-function commonality
at the platform level.
■Database Audit Store: In production environments, Oracle recommends using a
database audit store to provide scalability and high-availability for the Common
Audit Framework. A key advantage of the audit data store is that audit data from
multiple components can be correlated and combined in reports; for example,
authentication failures in all Middleware components and instances. Audit data is
cumulative and grows over time so ideally this is a stand-alone RDBMS database
for audit data only and not used by other applications.
To switch to a database as the permanent store for your audit records, you must
first use the Repository Creation Utility (RCU) to create a database schema for
audit data. The RCU seeds that database store with the schema required to store
See Also:
■"Access Manager Events You Can Audit" on page 8-6
■"Security Token Service Events You Can Audit" on page 8-16
Note: The preferred mode in production environments is writing
audit records to a stand-alone RDBMS database for audit data only.
Understanding Oracle Access Management Auditing
8-4 Administrator's Guide for Oracle Access Management
audit records in a database. After the schema is created, configuring a database
audit store involves:
■Creating a data source that points to the audit schema you created
■Configuring the audit store to point to the data source
Figure 8–1 provides a simplified view of the audit architecture with a supported
database. As previously documented, the Oracle Fusion Middleware Audit
Framework schema is provided by the RCU.
Figure 8–1 Audit to Database Architecture
An independent audit loader process reads the flat log file and inserts records in
the log table of the Oracle database. The audit store allows Administrators to
expose audit data with Oracle Business Intelligence Publisher using a variety of
out-of-the-box reports.
8.2.3 About Audit Reports and Oracle Business Intelligence Publisher
Oracle Access Management integrates with Oracle Business Intelligence Publisher,
which provides a pre-defined set of compliance reports through which the data in the
database audit store is exposed. These reports allow you to drill down the audit data
based on various criteria, such as user name, time range, application type, and
execution context identifier (ECID). Out-of-the-box, there are several sample audit
reports available with Oracle Access Management and accessible with Oracle Business
Intelligence Publisher. You can also use Oracle Business Intelligence Publisher to create
your own custom audit reports.
Oracle BI Enterprise Edition (Oracle BI EE) is a comprehensive set of enterprise
business intelligence tools and infrastructure, including a scalable and efficient query
and analysis server, an ad-hoc query and analysis tool, interactive dashboards,
proactive intelligence and alerts, real-time predictive intelligence, and an enterprise
See Also:
■"Configuring and Managing Auditing" in the Oracle Fusion
Middleware Application Security Guide
■"Setting Up the Audit Database Store" on page 8-21
Understanding Oracle Access Management Auditing
Auditing Administrative and Run-time Events 8-5
reporting engine. The components of Oracle BI EE share a common service-oriented
architecture, data access services, analytic and calculation infrastructure, metadata
management services, semantic business model, security model and user preferences,
and administration tools. Oracle BI EE provides scalability and performance with
data-source specific optimized analysis generation, optimized data access, advanced
calculation, intelligent caching services, and clustering.
For an overview of how to prepare Oracle BI EE for use with auditing reports for
Oracle Access Management, see "Preparing Oracle Business Intelligence Publisher EE"
on page 8-21.
Oracle BI EE reports contain enumerated fields, the data fields and labels of which are
self-explanatory. Content of reports is described in Table 8–1 (taken from Knowledge
Base Doc ID 1495333.1 on My Oracle Support.
For more information, see the following topics:
■Access Manager Events You Can Audit
■Identity Federation Events You Can Audit
■Security Token Service Events You Can Audit
8.2.4 About the Audit Log and Data
An audit log file helps the audit administrator track errors and diagnose problems
when the audit framework is not working properly. An audit log file records several
fields including (but not limited to) Date, Time, Initiator, EventType, EventStatus,
See Also: Using Audit Analysis and Reporting in the Oracle Fusion
Middleware Security Guide
Table 8–1 Oracle Business Intelligence Enterprise Edition Reports for OAM
Report Type Description
Account Management User ID | Timestamp | Component/ Application Name | Event Details
Authentication_Statistics Authentication_statistics
Failure | Userid | Number of Events
AuthenticationFromIPByUser
IP Address | Distinct User Count | Total Attempts | Users
AuthenticationPerIP
IP Address | Distinct Users | Total Number of Attempts
AuthenticationStatisticsPerServer
Server Instance Name | Success Count | Failure Count
Errors_and_Exceptions All_Errors_and_Exceptions
User ID | Timestamp | Component/Application Name | Client IP Address |
Message Event | Event Details
Authentication_Failures
User ID | Timestamp | Component/ Application Name | Client IP Address |
Authentication Method | Message Event Details | Authorization_Failures
Users_Activities
Authentication_History
User ID | Timestamp | Component/ Application Name | Client IP Address |
Authentication Method | Message Event Details | Authorization_Failures
Multiple_Logins_From_Same_IP
IP Address | Usernames Used
Access Manager Events You Can Audit
8-6 Administrator's Guide for Oracle Access Management
MessageText, ECID, RID ContextFields, SessionId, TargetComponentType,
ApplicationName, and EventCategory.
8.3 Access Manager Events You Can Audit
This section provides the following topics:
■Access Manager Administrative Events You Can Audit
■Access Manager Run-time Events You Can Audit
■Auditing Authentication Events
8.3.1 Access Manager Administrative Events You Can Audit
Administrative events are those generated when the Oracle Access Management
Console is used. The Access Manager-specific administrative events that can be
audited and the details captured for them are listed in Table 8–2. These event
definitions and configurations are implemented as part of the audit service in Oracle
Platform Security Services.
See Also: The topic on audit logs in the chapter on configuring and
managing auditing in the Oracle Fusion Middleware Security Guide
See Also:
■Identity Federation Events You Can Audit on page 8-14
■Security Token Service Events You Can Audit on page 8-16
Note: The amount and type of information that is logged is
controlled by choosing a filter preset from the Audit Configuration
section. Auditable events for each filter preset are fixed in the
read-only
component_events.xml
file. Editing or customizing this file
is not supported.
Table 8–2 Access Manager Administrative Audit Events
Administrative Event Event Data Include
Oracle Access Management Console Login
success/failure
■User name
■Remote IP
■Roles
Authentication Policy Creation ■Policy name
■Authentication scheme details
■Resource details
■Policy type (authentication or authorization)
Authentication Policy Modification ■Policy name
■Authentication scheme details
■Resource details
■Policy type (authentication or authorization
■Old Policy name
■Old Authentication scheme details
■Old Resource details
Access Manager Events You Can Audit
Auditing Administrative and Run-time Events 8-7
Authentication Policy Removal ■Policy name
■Authentication scheme details
■Resource details
■Policy type (authentication or authorization
Resource Creation ■Resource name
■URI
■Operation
■Resource type
Resource Modification ■Resource name
■URI
■Operation
■Resource type
■Old Resource name
■Old URI
■Old Operation
Resource Removal ■Resource name
■URI
■Operation
■Resource type
Authentication Scheme Creation ■Scheme name
■Authentication modules
■Level
Authentication Scheme Modification ■Scheme name
■Authentication modules
■Level
■Old Scheme name
■Old Authentication modules
■Old Level
Authentication Scheme Removal (Delete) ■Scheme name
■Authentication modules
■Level
Response Creation ■Response name
■Response key
■Data source
■Response Type
Response Modification ■Response name
■Response key
■Data source
■Response Type
■Old Response name
■Old Response key
■Old Data source
Response Removal (Delete) ■Response name
■Response key
■Data source
■Response Type
Table 8–2 (Cont.) Access Manager Administrative Audit Events
Administrative Event Event Data Include
Access Manager Events You Can Audit
8-8 Administrator's Guide for Oracle Access Management
8.3.2 Access Manager Run-time Events You Can Audit
Run-time events are those generated by some of the events the Access Manager
component engines issue when interacting with one another. The run-time events that
can be audited, when they are issued, and the details captured for them are listed in
Table 8–3. These event definitions and configurations are implemented as part of the
audit service in Oracle Platform Security Services.
Partner Addition ■Partner name
■Partner ID
■Partner URL
■Logout URL
Partner Modification ■Partner name
■Partner ID
■Partner URL
■Logout URL
■Old Partner name
■Old Partner URL
■Old Logout URL
Partner Removal ■Partner name
■Partner ID
■Partner URL
■Logout URL
Conditions creation ■Condition Name
■Condition type
■Condition data
Conditions Modification ■Condition Name
■Condition type
■Condition data
■Old Condition name
■Old Condition type
■Old Condition data
Conditions Removal ■Condition Name
■Condition type
■Condition data
Server Domain creation ■Domain Name
Server Domain Modification ■Domain Name
■Old Domain Name
Server Domain Removal ■Domain Name
Server configuration change ■New details
■Old details
■Instance Name
■Application Name
■User Name
■Remote ID
■Roles
■Date and time
Table 8–2 (Cont.) Access Manager Administrative Audit Events
Administrative Event Event Data Include
Access Manager Events You Can Audit
Auditing Administrative and Run-time Events 8-9
Note: The amount and type of information that is logged is
controlled by choosing a filter preset in the Audit Configuration.
Auditable events for each filter preset are fixed in the read-only
component_events.xml
file. Editing or customizing this file is not
supported.
Table 8–3 Access Manager Run-time Audit Events
Run-time Event Issued When Event Details Include
Authentication
Attempt
A user attempts to access a protected
resource and the request arrives at the SSO
server; this event might be followed by the
events credential submit and authentication
success or failure.
■Remote IP
■Resource ID
■Partner ID
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
Authentication
Success
A client submits credentials and credential
validation is successful.
■Remote IP
■User Name
■User DN
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
■Partner ID
Authentication
Failure
A client submits credentials and credential
validation fails.
■Remote IP
■User Name
■User DN
■Resource ID
■Authentication Scheme ID
■Failure Error Code
■Retry count
■Authentication Policy ID
■Partner ID
Session Creation Authentication succeeds. ■SSO Session ID
■User Name
■User DN
■Remote IP
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
Session Destroy Authentication succeeds. ■SSO Session ID
■User Name
■User DN
■Partner ID
Access Manager Events You Can Audit
8-10 Administrator's Guide for Oracle Access Management
Login success A client finishes the login procedure and it
is forwarded to the agent.
■Remote IP
■User Name
■User DN
■Authentication level
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
■Partner ID
Login failure A client fails to login; this event is issued
only when all the retry authentication
attempts allowed have failed or when the
account is locked.
■Remote IP
■User Name
■Authentication level
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
■Partner ID
Logout success A client finishes the logout procedure and
is forwarded to the agent.
■Remote IP
■User DN
■Authentication level
■SSO Session ID
■Partner ID
Logout failure A client fails to logout. ■Remote IP
■User DN
■SSO Session ID
■Failure details
■Partner ID
Credential
Collection
A client is redirected to the credential
collection page.
■Remote IP
■Resource Name
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
Credential Submit A client submits credentials. ■Remote IP
■User Name
■Resource ID
■Authentication scheme ID
■Authentication Policy ID
Authorization
Success
A client has been authorized to access a
resource.
■Remote IP
■User DN
■Resource ID
■Authorization Policy ID
Authorization
Failure
A client has not been authorized to access a
resource.
■Remote IP
■User DN
■Resource ID
■Authorization Policy ID
Server Start Up The server starts up. ■Date and time
■Instance Name
■Application Name
■User Name
Table 8–3 (Cont.) Access Manager Run-time Audit Events
Run-time Event Issued When Event Details Include
Mobile and Social Events You Can Audit
Auditing Administrative and Run-time Events 8-11
8.3.3 Auditing Authentication Events
Auditing events during authentication can help Administrators scrutinize security
weaknesses in their systems. The events that an Administrator can configure for
auditing during authentication are:
■Authentication success
■Authentication failure
■Create, modify, delete, or view Authentication Policy data
Information related to the user being authenticated may include the following:
■IP address
■Browser type
■User Login ID
■Time of Access
Information about users requesting authentication or brute force attacks can be stored
in the file system or in a back-end database.
8.4 Mobile and Social Events You Can Audit
This section provides the following topics:
■REST Run-Time Audit Events
■Mobile and Social Audit Events
8.4.1 REST Run-Time Audit Events
You can audit the run-time events in the following table.
Server Shut Down The server shuts down. ■Date and time
■Instance Name
■Application Name
■User Name
Note: Oracle recommends that you avoid auditing, logging, or
tracing sensitive user attributes, such as user passwords.
Table 8–3 (Cont.) Access Manager Run-time Audit Events
Run-time Event Issued When Event Details Include
Mobile and Social Events You Can Audit
8-12 Administrator's Guide for Oracle Access Management
8.4.2 Mobile and Social Audit Events
You can audit the runtime events in the following table.
Table 8–4 REST Run-Time Audit Events
Run-time Event Issued When Event Details Include
Partner Security Validation
Event
Partner credentials are
validated using the
appropriate security
mechanism. The event is
logged for both success and
failure scenarios.
■Partner ID (or any unique
partner var)
■Remote IP
■Security Mechanism
■Service Instance
(Endpoint or name)
■Event Status
(success/fail)
Create Token A token is created. ■Event Status
■Caller Attribute
■Subject Attribute
■Filter Subject Attribute
■Token Attribute
■Opcode Attribute
■Message Text
Terminate Token A token is terminated. ■Event Status
■Caller Attribute
■Subject Attribute
■Filter Subject Attribute
■Token Attribute
■Opcode Attribute
■Message Text
Get Token A token is obtained/read. ■Event Status
■Caller Attribute
■Subject Attribute
■Filter Subject Attribute
■Token Attribute
■Opcode Attribute
■Message Text
Table 8–5 Mobile and Social Run-Time Audit Events
Run-Time Event Issued When Event Details Include
IDP Login A user attempts to log in
using an identity provider
■Event status
■Application ID
■Identity provider name
■Event message
Mobile and Social Events You Can Audit
Auditing Administrative and Run-time Events 8-13
IDP Rest Access The REST service for identity
providers is accessed
■Event status
■Application ID
■Protocol
■Event message
IDP User Profile The user profile related to a
user authenticated by an
identity provider is obtained
■Event status
■Application ID
■User attributes
■Identity provider name
■Event message (optional
attributes)
Local Registration A user registers locally by
providing registration info
■Event status
■User ID
■First name
■Last name
■E-mail
■Location
■Time zone
■Event message
Security Validation The security mechanism on
the Identity Provider REST
Services for Relying Party
(RP) is validated
■Security mechanism
■Client principal
■Remote IP address
■Event message
OpenID Authentication
Request
An OpenID authentication
request is initiated
■Event status
■Request ID
■IDP login URL
■Request attributes
■Message text
OAuth Authentication
Request
An OAuth authentication
request is initiated
■Event status
■Request ID
■Return URL
■IDP attributes
■Message text
OAuth Access Token Request An OAuth access token
request is initiated
■Event status
■Request ID
■Token
■Message text
Local Login User logs in locally ■Event status
■Application ID
■User ID
■Token
■Message text
Table 8–5 (Cont.) Mobile and Social Run-Time Audit Events
Run-Time Event Issued When Event Details Include
Identity Federation Events You Can Audit
8-14 Administrator's Guide for Oracle Access Management
8.5 Identity Federation Events You Can Audit
The Identity Federation service also uses the Fusion Middleware Audit Framework for
auditing. The following data is part of each audit record, regardless of the event or
event type that is audited:
■timestamp - Date and time the audit event occurred
■initiator - the initiator of the audit event (for some events this attribute may be
empty)
■ECID - the execution context ID
The Fusion Middleware Audit Framework supports the following audit levels:
■None
■Low
■Medium
■Custom
Events can be audited in different categories and audit levels. Table 8–6 lists the event
categories and where they are described in this chapter.
The following section contain more information.
■Session Management Events for Identity Federation
■Protocol Flow Events for Identity Federation
■Server Configuration Events for Identity Federation
■Security Events for Identity Federation
8.5.1 Session Management Events for Identity Federation
Session Management events for this Identity Federation release, include a subset of
auditable events for the previous release. For attributes of each event, see "Session
Management Events" in Oracle Fusion Middleware Administrator's Guide for Oracle
Identity Federation.
Table 8–6 Categories of Audit Events for Identity Federation
Category Described in ...
Session Management Session Management Events for Identity Federation
Protocol Flow Protocol Flow Events for Identity Federation
Server Configuration Server Configuration Events for Identity Federation
Security Security Events for Identity Federation
See Also: Oracle Fusion Middleware Administrator's Guide for
Oracle Identity Federation chapter on "Diagnostics and Auditing" for
greater detail
Table 8–7 Identity Federation Session Management Events
Auditable Events Auditing Not Supported in This Release for ...
CreateUserSession –
Creation of a session after a successful login
CreateUserFederation –
Creation of a user federation between two remote servers
Identity Federation Events You Can Audit
Auditing Administrative and Run-time Events 8-15
8.5.2 Protocol Flow Events for Identity Federation
Protocol flow events for this Identity Federation release, include a subset of auditable
events for the previous Identity Federation release. For attributes of each event, see
"Protocol Flow Events" in Oracle Fusion Middleware Administrator's Guide for Oracle
Identity Federation.
8.5.3 Server Configuration Events for Identity Federation
Auditable Server configuration events for this Identity Federation release, include a
subset of auditable events for the previous Identity Federation release. For attributes of
each event, see "Server Configuration Events" in Oracle Fusion Middleware
Administrator's Guide for Oracle Identity Federation.
DeleteUserSession –
Deletion of a session after logout
UpdateUserFederation -
Updating the user federation between two remote servers
CreateActiveUserFederation –
Creation of an active federation after
successful login
DeleteUserFederation –
Deletion of a user federation between two remote servers
CreateActiveUserFederation –
Creation of an active federation after
successful login
DeleteActiveUserFederation -
Deletion of an active federation after logout
LocalAuthentication –
Authentication of a user at OIF
LocalLogout - Logout of a user at Identity
Federation
Table 8–8 Protocol Flow Events for Identity Federation
Auditable Events Auditing Not Supported in This Release for ...
IncomingMessage
Message being received by Identity Federation
AssertionCreation
Creation of an assertion by Identity Federation
(Success only
OutgoingMessage
Message being sent by Identity Federation (Success
only)
AssertionConsumption
Consumption of an assertion by Identity Federation
(Success only)
Table 8–9 Server Configuration Identity Federation
Auditable Events Auditing Not Supported in This Release for ...
CreateConfigProperty
Adding a new configuration property (Success only)
SetDataStoreType
Changing the type of a data store (Success only)
ChangeConfigProperty
Changing the value of an existing configuration
property (Success only)
ChangeDataStore
Setting of the federation data store (Success only)
DeleteConfigProperty
Deleting a configuration property (Success only)
Table 8–7 (Cont.) Identity Federation Session Management Events
Auditable Events Auditing Not Supported in This Release for ...
Security Token Service Events You Can Audit
8-16 Administrator's Guide for Oracle Access Management
8.5.4 Security Events for Identity Federation
Auditable security events for this Identity Federation release, include all auditable
events for the previous Identity Federation release. For attributes of each event, see
"Security Events" in Oracle Fusion Middleware Administrator's Guide for Oracle
Identity Federation.
8.6 Security Token Service Events You Can Audit
Security Token Service provides an independent audit configuration file, named
component_events.xml
, that defines specific event types and events to audit. The
following sections provide more details.
■About Audit Record Content Common to All Events
■Security Token Service Administrative Events You Can Audit
■Security Token Service Run-time Events You Can Audit
CreatePeerProvider
Adding a new provider to the list of trusted
providers (Success only)
UpdatePeerProvider
Updating the information on an existing provider in
the list of trusted providers (Success only)
PeerProviderID
DeletePeerProvider
Deleting a provider from the list of trusted
providers (Success only)
LoadMetadata
Loading of metadata (Success only)
ChangeFederation
Changing of the trusted providers (Success only)
ChangeServerProperty
Changing of a server configuration property
(Success only)
Table 8–10 Security Events for Identity Federation
Auditable Events Auditing Not Supported in This Release for ...
CreateSignature
Creation of a digital signature by Identity
Federation
n/a
Ve ri fy S ig na t ure
Verification of a digital signature by Identity
Federation
EncryptData
Encryption of data by Identity Federation
DecryptData
Decryption of data by Identity Federation
Table 8–9 (Cont.) Server Configuration Identity Federation
Auditable Events Auditing Not Supported in This Release for ...
Security Token Service Events You Can Audit
Auditing Administrative and Run-time Events 8-17
8.6.1 About Audit Record Content Common to All Events
The following data is part of each audit record, regardless of the event or event type
that is audited:
■Date and time of event
■IP address of the client initiating event
■Client identity
■Processing time for the event
8.6.2 Security Token Service Administrative Events You Can Audit
Security Token Service administrative events fall into several configuration
management operations defined in
component_events.xml
. See details in Table 8–11.
See Also: "Setting Up Auditing for Oracle Access Management" on
page 8-20
Table 8–11 Security Token Service Configuration Management Operations
Security Token Service
Configuration Operations Description
Common Attributes ■OldSettings: The string representing the previous settings before
the change was applied.
■NewSettings: The string representing the new settings.
■TemplateID: The ID of the Validation or Issuance Template being
created or updated or deleted.
■ProfileID: The ID of the Partner Profile being created or updated
or deleted.
■PartnerID: The ID of the Partner being created or updated or
deleted.
■SettingsID: The ID of the generic settings being created or
updated or deleted.
Create Validation Template Audit event recorded for the creation of a Validation Template
referenced by CreateValidationTemplate.
Attributes:
■TemplateID
■NewSettings
Update Validation Template Audit event recorded for the update of a Validation Template
referenced by UpdateValidationTemplate.
Attributes:
■TemplateID
■OldSettings
■NewSettings
Delete Validation Template Audit event recorded for the delete event of a Validation Template
referenced by DeleteValidationTemplate.
Attributes:
■TemplateID
■OldSettings
Create Issuance Template Audit event recorded for the creation of an Issuance Template
referenced by CreateIssuanceTemplate.
Attributes:
■TemplateID
■NewSettings
Security Token Service Events You Can Audit
8-18 Administrator's Guide for Oracle Access Management
Update Issuance Template Audit event recorded for the update of an Issuance Template
referenced by UpdateIssuanceTemplate.
Attributes:
■TemplateID
■OldSettings
■NewSettings
Delete Issuance Template Audit event recorded for the delete event of an Issuance Template
referenced by DeleteIssuanceTemplate.
Attributes:
■TemplateID
■OldSettings
Create Partner Profile Audit event recorded for the creation of Partner Profile referenced by
CreatePartnerProfile.
Attributes:
■ProfileID
■NewSettings
Update Partner Profile Audit event recorded for the update of a Partner Profile referenced by
UpdatePartnerProfile.
Attributes:
■ProfileID
■OldSettings
■NewSettings
Delete Partner Profile Audit event recorded for the delete event of Partner Profile referenced
by DeletePartnerProfile.
Attributes:
■ProfileID
■OldSettings
Create Partner Audit event recorded for the creation of Partner Profile referenced by
CreatePartner.
Attributes:
■PartnerID
■NewSettings
Update Partner Audit event recorded for the update of a Partner Profile referenced by
UpdatePartner.
Attributes:
■PartnerID
■OldSettings
■NewSettings
Delete Partner Audit event recorded for the delete event of Partner Profile referenced
by DeletePartner.
Attributes:
■PartnerID
■OldSettings
Generic Admin Creation Audit event recorded for the generic create administrative operation
referenced by GenericAdminCreation.
Attributes:
■SettingsID
■NewSettings
Table 8–11 (Cont.) Security Token Service Configuration Management Operations
Security Token Service
Configuration Operations Description
Security Token Service Events You Can Audit
Auditing Administrative and Run-time Events 8-19
8.6.3 Security Token Service Run-time Events You Can Audit
Security Token Service-specific run-time events for token operations are defined in
component_events.xml
. See details in Table 8–12.
Generic Admin Update Audit event recorded for the update of a generic update
administrative operation referenced by GenericAdminUpdate.
Attributes:
■SettingsID
■OldSettings
■NewSettings
Generic Admin Removal Audit event recorded for generic delete administrative operation
referenced by GenericAdminDeletion.
Attributes:
■SettingsID
■OldSettings
Table 8–12 Security Token Service-specific Run-time Events
Token Operations Description
Common Attributes ■Requester: Who made the request by sending the RST
■RelyingParty: The one for whom the token is created
■UserID: End user identity
■TokenType: Either SAML11, SAML20, Username, X.509,
Kerberos, OAM or Custom
■Token: The XML value of the token
■TokenContext: The Context data passed for token
operations
■Message: The XML representation of the incoming or
outgoing message
Incoming Message Incoming RSTR message received by Security Token Service
referenced by OutgoingMessage.
Attributes populated for this event, if available:
■Requester
■RelyingParty
■Message
Outgoing Message Outgoing RSTR message received by Security Token Service
referenced by IncomingMessage.
Attributes populated for this event, if available:
■Requester
■RelyingParty
■Message
Table 8–11 (Cont.) Security Token Service Configuration Management Operations
Security Token Service
Configuration Operations Description
Setting Up Auditing for Oracle Access Management
8-20 Administrator's Guide for Oracle Access Management
8.7 Setting Up Auditing for Oracle Access Management
The following overview provides a list of the tasks that must be performed before you
can perform auditing for Oracle Access Management.
1. Set up the audit data store, as described in "Setting Up the Audit Database Store"
on page 8-21.
2. Set up publishing for audit reports, as described in "Preparing Oracle Business
Intelligence Publisher EE" on page 8-21.
3. Edit the Audit Configuration in the Oracle Access Management Console, as
described in:
■Using the Oracle Access Management Console for Audit Configuration
■Adding, Viewing, or Editing Audit Settings
See Section 8.8, "Validating Auditing and Reports" for details testing and validating
the audit configuration.
Token Validation Audit event for token validation in Security Token Service
referenced by TokenValidation. The status attribute indicates
whether or not the validation operation was successful.
Attributes populated for this event, if available:
■Requester
■RelyingParty
■Token
■TokenType
■TokenContext
■Status
Token Generation Audit event for token generation in Security Token Service
referenced by TokenGeneration.
Attributes populated for this event, if available:
■Requester
■RelyingParty
■Token
■TokenType
■TokenContext
■UserID
LDAP User Authentication Audit event for local user authentication with the LDAP
Directory referenced by LDAPUserAuthentication.
Attributes populated for this event, if available:
■UserID
■Status
Generic Runtime Operation Audit event for a generic operation performed by Security
Token Service referenced by GenericRuntimeOperation
Attributes populated for this event, if available:
■OperationType: type of operation
■OperationData: string representing context of the
operation
Table 8–12 (Cont.) Security Token Service-specific Run-time Events
Token Operations Description
Setting Up Auditing for Oracle Access Management
Auditing Administrative and Run-time Events 8-21
8.7.1 Setting Up the Audit Database Store
This topic provides an overview of the tasks required to create the audit database and
extend the schema using the Repository Creation Utility (RCU). This task is required
before you can audit events for Oracle Access Management if you choose a database
store for audit data.
1. Create an audit database, version 11.1.0.7 or later, as described in the Oracle Fusion
Middleware Application Security Guide.
2. Run the RCU against the database, as described in "Create the Audit Schema using
RCU" in the Oracle Fusion Middleware Repository Creation Utility User's Guide.
3. Set up audit data sources for the audit loader and configure it for the OAM Server
as described in "Set Up Audit Data Sources" in the Oracle Fusion Middleware
Application Security Guide:
■Use the Java EE audit loader configuration for WebLogic Server.
■Use the JNDI name of the data source jdbc/AuditDB that points to the
database that was set up in step 2 above.
4. In the service instance specified in the domain file
($DOMAIN_
HOME/config/fmwconfig/jps-config.xml
), enable database auditing by changing
the value of the property
audit.loader.repositoryType
to
DB
. For example:
<serviceInstance name="audit.db" provider="audit.provider">
<property name="audit.loader.repositoryType" value="DB"/>
<property name="auditstore.type" value="db"/>
<property name="audit.loader.jndi" value="jdbc/AuditDB"/>
<property name="audit.maxDirSize" value="0"/>
<property name="audit.filterPreset" value="None"/>
<property name="audit.maxFileSize" value="104857600"/>
<property name="audit.loader.interval" value="15"/>
<propertySetRef ref="props.db.1"/>
</serviceInstance>
5. Restart the WebLogic Server.
6. Ensure that the audit loader is configured for the OAM Server and that it points to
the proper database, as described in "Configure a Database Audit Store for Java
Components" in the Oracle Fusion Middleware Application Security Guide.
7. Maintain the bus-stop files, as described in "Tuning the Bus-stop Files" in the
Oracle Fusion Middleware Application Security Guide.
8.7.2 Preparing Oracle Business Intelligence Publisher EE
You must prepare Oracle Business Intelligence Publisher Enterprise Edition (EE) for
use with Oracle Access Management audit reports as outlined in the following
procedure.
See Also:
■Oracle Fusion Middleware Application Security Guide for details on
managing the audit store
■Oracle Fusion Middleware Repository Creation Utility User's
Guide
Setting Up Auditing for Oracle Access Management
8-22 Administrator's Guide for Oracle Access Management
1. Install Oracle BI Publisher, as described in the Oracle Business Intelligence Enterprise
Edition Installation and Upgrade Guide.
2. Perform tasks as described in "Set Up Oracle Reports in Oracle Business
Intelligence Publisher" in the Oracle Fusion Middleware Application Security
Guide:
■Unzip the
oam_audit_reports_11_1_2_0_0.zip
into your Reports folder.
This zip file is located in the $ORACLE_HOME/oam/server/reports/
directory.
■Unjar the
AuditReportTemplates.jar
into your Reports folder.
AuditReportTemplates.jar
is located in the $MW_ORA_HOME/oracle_
common/modules/oracle.iau_11.1.1/reports/ directory.
■Set up the JNDI connection for the audit data source or the JDBC connection
the audit database.
The datasource name must be "Audit".
3. Set up audit report templates, as described in the section "Set Up Audit Report
Templates" of the Oracle Fusion Middleware Application Security Guide.
4. Set up audit report filters, as described in the section "Set Up Audit Report Filters"
of the Oracle Fusion Middleware Application Security Guide.
5. View reports from the following path: Reports/Oracle_Fusion_Middleware_Audit
reports.
8.7.3 Using the Oracle Access Management Console for Audit Configuration
Within Oracle Access Management, certain Audit Configuration settings are accessible
as Common Settings under the System Configuration. These settings are not required
when you audit to a database. Figure 8–2 shows the Audit Configuration section of the
Common Settings page.
See Also:
■Oracle Fusion Middleware Metadata Repository Builder's Guide for
Oracle Business Intelligence Enterprise Edition
■Oracle Fusion Middleware Developer's Guide for Oracle Business
Intelligence Enterprise Edition
■Oracle Fusion Middleware User's Guide for Oracle Business
Intelligence Enterprise Edition
See Also: "Validating Auditing and Reports" on page 8-25
Setting Up Auditing for Oracle Access Management
Auditing Administrative and Run-time Events 8-23
Figure 8–2 Common Settings: Auditing Configuration
The Auditing section provides settings for the Log Directory, Filter Settings, and Audit
Configuration Users.
Table 8–13 describes the elements in the Audit Configuration page.
Note: The actual log directory cannot be configured using the Oracle
Access Management Console. It is the default directory for the
Common Audit Framework audit loader. Changing the directory
impacts the audit loader and is not supported.
Table 8–13 Audit Configuration Elements
Elements Description
Maximum Directory Size The maximum size, in MBs, of the directory that contains audit output files.
For example, assuming that the maximum file size is 10, a value of 100 for
this parameter implies that the directory allows a maximum of 10 files.
Once the maximum directory size is reached, the audit logging stops.
For example, a value of 100 specifies a maximum of 10 files if the file size is
10 MB. If the size exceeds this, the creation of audit logs stops.
This is configured using the
max.DirSize
property described in the
configuration file
jps-config.xml
. This property controls the maximum size
of a bus-stop directory for Java components as described in the Oracle Fusion
Middleware Application Security Guide.
Maximum File Size The maximum size, in MBs, of an audit log file. Once the size of a file
reaches the maxi mum size, a new log file is created. For example,
specifying 10 directs file rotation when the file size reaches 10 MB.
This is configured using the
max.fileSize
property described in the
configuration file
jps-config.xml
. This property controls the maximum size
of a bus-stop file for Java components as described in the Oracle Fusion
Middleware Application Security Guide.
Filter Enabled Check this box to enable event filtering.
Setting Up Auditing for Oracle Access Management
8-24 Administrator's Guide for Oracle Access Management
8.7.4 Adding, Viewing, or Editing Audit Settings
The Administrator controls the amount and type of information that is logged by
choosing a filter preset from the Audit Configuration tab on the OAM Server Common
Properties page.
The following procedure describes how to add, view, or edit OAM Server Common
Audit Configuration settings. Individual audit policies cannot be configured using
Fusion Middleware Control. Oracle Access Management does not use JPS
infrastructure to configure the audit configuration. There are no WebLogic Scripting
Tool (WLST) commands for auditing.
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Settings section, select Common Settings from the View menu.
3. In the Audit Configuration section, enter appropriate details for your environment
(Table 8–13):
■Maximum Log directory size
■Maximum Log file size
■Filter Enabled
■Filter Preset (to define verbosity of audit data)
■Users to include specific users from the audit by clicking the Add (+) button
above the Users table and entering a value in the field.
4. Click Apply to submit the Audit Configuration (or close the page without
applying changes).
5. Restart AdminServer and OAM Servers after changes are applied.
Filter Preset Defines the amount and type of information that is logged when the filter is
enabled. The default value is Low.
■All: captures and records all auditable OAM events
■Low: captures and records a specific set of auditable OAM events
■Medium: captures and records events covered by the Low setting plus
a number of other auditable OAM events
■None: no OAM events are captured and recorded
Events for each filter preset are fixed in the read-only component_
events.xml file. Editing or customizing this file is not supported for Oracle
Access Management. Only items that are configured for auditing at the
specified filter preset can be audited.
Users Specifies the list of users whose actions are included only when the filter is
enabled. All actions of the special users are audited regardless of the filter
preset. Administrators can add, remove or edit special users from this table.
Note: Auditable events for each filter preset are fixed in the
read-only
component_events.xml
file. Editing or customizing this file
is not supported.
Table 8–13 (Cont.) Audit Configuration Elements
Elements Description
Validating Auditing and Reports
Auditing Administrative and Run-time Events 8-25
8.8 Validating Auditing and Reports
Use the following procedure to test your run-time event auditing configuration. Before
you begin:
■Configure auditing parameters as described in "Setting Up Auditing for Oracle
Access Management" on page 8-20.
■Ensure the Agents and Servers are running.
■Prepare BI EE Publisher as described in "Preparing Oracle Business Intelligence
Publisher EE" on page 8-21.
1. To validate an Authentication Event: Audit Console login success/failure as
described here or any administrative event described in Table 8–2, " Access
Manager Administrative Audit Events".
a. Sign out of Oracle Access Management Console.
b. Sign in to Oracle Access Management Console with invalid user (not
Administrator) credentials.
c. Sign in to Oracle Access Management Console using the proper Administrator
credentials.
d. Review Log File: Open the audit.log file and search for the last Administrative
event entries:
$DOMAIN_HOME/servers/$ADMINSERVER_NAME/logs/auditlogs/OAM/audit.log
e. Review Database Log:
a. Perform tasks in "Setting Up the Audit Database Store" on page 8-21.
b. Generate an Authentication event as described in Step 1.
c. Connect to the database and connecting to the database and reviews audit
events under IAU_BASE table.
2. To validate a Runtime Event: Audit Authorization success/failure as described
here or any runtime event described in Table 8–3, " Access Manager Run-time
Audit Events".
a. In a browser window, enter the URL of a protected resource for which you are
not authorized.
b. Review Log File: Open the audit.log file and search for the last Administrative
event entries:
$DOMAIN_HOME/servers/$ADMINSERVER_NAME/logs/auditlogs/OAM/audit.log
c. Review Database Log:
a. Perform tasks in "Setting Up the Audit Database Store" on page 8-21.
b. Generate and Authentication event as described in Step 1.
c. Connect to the database and connecting to the database and reviews audit
events under IAU_BASE table.
3. To validate Audit Configuration Changes: See Also "Adding, Viewing, or Editing
Audit Settings" on page 8-24.
a. From the Oracle Access Management Console, System Configuration tab,
Common Configuration, modify Maximum Directory Size (MB) and
Maximum File Size (MB) parameters.
Validating Auditing and Reports
8-26 Administrator's Guide for Oracle Access Management
b. Repeat Steps here to confirm auditing is working.
4. To View Reports:
a. Sign in to Oracle BI EE. For example:
http://host:port/xmlpserver
Here, host is the computer hosting Oracle BI Publisher; port is the listening port
for BI Publisher; xmlpserver is the login page for BI Publisher.
b. In Oracle BI Publisher Enterprise, locate the desired reports. For example:
Click Shared Folders, the component that contains the report you would like
to view and then select the desired report.
c. Perform any analysis as desired, or edit your auditing configuration as
needed.
$MW_HOME/user_projects/domains/base_domain/servers/oam_server1/logs/
auditlogs/OAM/
5. Archive and manage audit logs according to your company policies.
9
Logging WebGate Event Messages 9-1
9
Logging WebGate Event Messages
[10]
Each 10g and 11g WebGate instance can write information about its processes and
states to a log file. The logs can be configured to provide information at various levels
of granularity. For example, you can record errors, errors plus state information, or
errors, states, and other information to the level of a debug trace. You can also
eliminate sensitive information from the logs.
This chapter provides the following sections.
■About Logging, Log Levels, and Log Output
■About Log Configuration File Paths and Contents
■About Directing Log Output to a File or the System File
■Structure and Parameters of the Log Configuration File
■About Activating and Suppressing Logging Levels
■Understanding the Mandatory Log-Handler Configuration Parameters
■Configuring Different Threshold Levels for Different Types of Data
■Filtering Sensitive Attributes
9.1 About Logging, Log Levels, and Log Output
The logging feature enables you to analyze system performance and to troubleshoot
issues. You can configure logging for individual WebGate instances of the following
components:
■10g WebGates
■11g WebGates
■Custom Access Clients (Access Manager SDK)
You can configure different logging levels for different functional areas of a component
instance. For example, you can capture debug data for LDAP activity while recording
only error-level data for all other component activity. You can also record the time
taken for each request that a component processes, and you can send different levels of
Note: Unless explicitly stated, all information in this section applies
equally to 10g and 11g WebGates. For instance, the location of the log
configuration, oblog_config_wg.xml, has changed for 11g but the
content of the file and most other specifics have not.
About Logging, Log Levels, and Log Output
9-2 Administrator's Guide for Oracle Access Management
log data to different destinations. For example, you can send error information to a file
and all other log data to the system log.
Securing Sensitive Information: Access Manager handles sensitive information about
users. On some sites, this includes user password, date of birth, a social security
number, security questions and answers for lost password requests. Sensitive data on
your site might include a security number or other information you want to secure. At
certain logging levels, sensitive information might be captured. Today, you can filter
sensitive information out of log files, as described in "Filtering Sensitive Attributes" on
page 9-26.
Configuring Logging: You configure logging by editing a configuration file that is
stored with the Webgate. See "About Log Configuration File Paths and Contents" on
page 9-4.
Logging Levels: You can request logging at various levels. The highest level is Fatal
and the lowest level is Trace. See "About Log Levels" on page 9-2 for details.
Logging Destinations: In the log configuration file, a parameter known as a log writer
determines the destination for log output. See "About Directing Log Output to a File or
the System File" on page 9-9 for details. You create a complete definition for your log
output by identifying a log writer and a log level. This complete definition is known as
a log-handler. See "About The Second Compound List and Log Handlers" on page 9-13
for details.
The rest of this section discusses the following topics:
■About Log Levels
■About Log Output
9.1.1 About Log Levels
A logging level determines the amount of data that is written to the log data file. Each
logging level is cumulative, that is, each level contains all the data generated by the
higher levels. For example, Error logs contain all the data generated by the Fatal logs,
plus the events that are specific to the Error category.
Table 9–5 describes the levels. The default log level is Warning: LOGLEVEL_
WARNING.
Table 9–1 Logging Levels
Level
Number of
Events
Reported Description
LOGLEVEL_
FATAL
> 60 Records critical errors. Generally, these events can
cause the component to exit.
In the event of a system failure, Fatal-level messages are
always flushed to the log file.
LOGLEVEL_
ERROR
> 960 Records events that may require corrective action, for
example, a component is unavailable. Error logs can
also be generated for transient or self-correcting
problems, for example, failure to connect to another
component.
LOGLEVEL_
WARNING
> 1200 Records issues that may lead to an error or require
corrective action in the future.
LOGLEVEL_ INFO
> 400 Records completed actions or the current state of a
component, for example, the component is initializing.
About Logging, Log Levels, and Log Output
Logging WebGate Event Messages 9-3
Compound Lists: You can collect log data from non-adjacent levels and send different
levels of log data to different destinations. For example, you can send the Fatal logs to
the system log, and write Error logs to a file. See "About The Second Compound List
and Log Handlers" on page 9-13 for details.
Threshold: You configure a global cutoff, or threshold, for logging on the
LOG_
THRESHOLD_LEVEL
parameter in the log configuration file. By default, if a configured
level for a log-handler exceeds the cutoff, the log data is not collected. Note that logs
can fail to be written despite the configured level because the
LOG_THRESHOLD_LEVEL
parameter takes precedence over the level configured in the log-handler. Only the
MODULE_CONFIG
section of the log configuration file overrides the global threshold. See
"About The Simple List and Logging Threshold" on page 9-11 for details.
Overrides: You specify function- or module-specific overrides for the global logging
threshold on the
MODULE_CONFIG
parameter. See "Configuring Different Threshold
Levels for Different Types of Data" on page 9-22 for details.
9.1.2 About Log Output
Each line of the log output file follows a particular structure. A line starts with a date
and time stamp, followed by the thread that is processing the request, the name of the
function or module being logged, and the log level.
The following is a snapshot of the left-most columns of the log output file:
LOGLEVEL_
DEBUG1
> 400 Records debugging information. Typically, the
information at this level is only meaningful to a
developer.
LOGLEVEL_
DEBUG2
> 100 Records advanced debugging information. This level
augments the Debug1 log level. Typically, the
information at this level is only meaningful to a
developer.
LOGLEVEL_
DEBUG3
> 900 Records a large amount of debugging information or
data pertaining to an expensive section of the code.
This level is useful for debugging a tight loop or a
performance-sensitive function. Typically, the
information at this log level is only meaningful to a
developer.
These logs can contain sensitive information.
LOGLEVEL_
TRACE
> 900 Access
Manager API
> 150
third-party API
This log level is used to trace code path execution or to
capture performance metrics. This information is
captured at the entry and exit points for each
component function. Typically, the information at this
log level is only meaningful to a developer.
These logs can contain sensitive information.
LOGLEVEL_ ALL
> 5000 This level includes all the events and states from all
other levels.
Note: The Trace and Debug3 level logs can contain sensitive
information. For more information about sensitive information, see
"Filtering Sensitive Attributes" on page 9-26.
Table 9–1 (Cont.) Logging Levels
Level
Number of
Events
Reported Description
About Log Configuration File Paths and Contents
9-4 Administrator's Guide for Oracle Access Management
2007/06/01@00:50:56.859000 5932 2672 DB_RUNTIME DEBUG3
2007/06/01@00:50:56.859000 5932 2672 DB_RUNTIME TRACE
2007/06/01@00:50:56.859000 5932 2672 LDAP DEBUG1
2007/06/01@00:50:56.859000 5932 2672 LDAP TRACE
2007/06/01@00:50:56.859000 5932 2672 LDAP TRACE
The two columns to the right of the log level are internal code references, and can be
ignored. The following is an example of these columns:
0x00000205 ldap_connection_mngr.cpp:212
To the right of the internal code reference columns, you see the log message that is
associated with this log level, for example, "
Function called
" or "
Function
returned
," followed by the name of the function, as illustrated in the following
example:
"Function called" _CallName^ldap_init
The log message and function name can be followed by additional information, for
example, the duration of the process, the address space where the function is running,
or state information, as illustrated in the following examples:
"Connection health check result" Server^dlsun4072 Port^389 Server Priority^1
Connection available^true
"Function entered" _TraceName^ConnectionWatcherThread::CheckPrimaries
"Function exited" _TraceName^ConnectionWatcherThread::CheckPrimaries
TraceDuration^0.000028
"Connection Pool Status in ValidateConnections() "NumLivePrimaryConnections^1
Maximum Connections^1 UpConnections^1 Failover Threshold^1 Max Session
Time^0 SleepFor^60
To secure sensitive information and ensure that it is not included in the output of the
logging operation, see "Filtering Sensitive Attributes" on page 9-26.
9.2 About Log Configuration File Paths and Contents
The log configuration file, oblog_config_wg.xml, is used to specify configuration
details for WebGate logging (oblogs). You configure parameters that control WebGate
log output in XML-based log files that can be edited with a plain text editor. Changes
made to these files are effective immediately. Details are in the following sections:
■Log Configuration File Paths and Names
■Log Configuration File Contents
9.2.1 Log Configuration File Paths and Names
By default, WebGate logging is enabled and oblogs are generated in the Oracle HTTP
Server (OHS) instance diagnostics directory: instance1/diagnostics/logs/OHS/ohs1/.
Each WebGate instance includes a log configuration file (oblog_config_wg.xml) where
you can define what type of data is recorded in the log output. A log configuration file
is distinct from the log output file. For details on log output files, see "About Log
Output" on page 9-3.
See Also: "Log Configuration File Contents" on page 9-5
About Log Configuration File Paths and Contents
Logging WebGate Event Messages 9-5
The oblog_config_wg.xml file is updated when you edit to configure WebGate
logging. For example, by setting a new log threshold level, changing a log file name, or
filtering logs related to some modules and so on.
Log configuration, oblog_config_wg.xml, files reside in the following locations
depending upon your WebGate version:
10g WebGates: Webgate_install_dir\oblix\config
11g WebGates: $WEBGATE_HOME or $ORACLE_HOME/webgate/ohs/config. The
same oblog_config_wg.xml file is copied to the WebGate instance directory
($INSTANCE_HOME/webgate/config) when the WebGate instance is created The
later is to be used when configuring logging.
After installation, oblog_config_wg.xml and oblog_config_wg_original.xml both
contain comments to help guide your editing.
Table 9–2 lists the names of the log configuration files. Do not change the names.
The oblog_config_wg.xml file can be edited using any text editor as long as you ensure
that after the update the file is still valid XML. After updates to the file, changes will
take affect in about 60 seconds.
9.2.2 Log Configuration File Contents
The log configuration file controls items such as the following:
■What is logged for that component
■Where the data is sent
■In certain cases, the size of the write buffer used for the log
■Log file rotation intervals
The configuration file contains XML statements that you can edit in a text editor.
9.2.2.1 When Changes to the File Take Effect
A watcher thread picks up changes to the log configuration file every 60 seconds and
ensures that changes take effect. It is unnecessary to restart the server
Note: Do not change the path to this file. If you install more than one
instance, a log configuration file is installed for each instance. When
configuring logging, oblog_config_wg.xml under $INSTANCE_HOME
should be updated.
Table 9–2 Log Configuration File Names for Components
Component Log Configuration FIle Name
Webgate oblog_config_wg.xml
Access Manager SDK (custom Access
Client)
oblog_config.xml
Important: Do not change the default path or name for any logging
configuration file.
About Log Configuration File Paths and Contents
9-6 Administrator's Guide for Oracle Access Management
9.2.2.2 About Comments in the Log File
Each default log configuration file contains comments that are intended to assist with
editing the file.
The commented default configuration file is shown here:
Comments can span one or multiple lines. Comments look similar to the following:
<!--NetPoint Logging Configuration File -->
<!-- -->
<!--Changes to this file will be automatically taken into effect -->
<!--in one minute. This does not require any server restart. -->
Example 9–1 shows a typical log configuration file with comments. Example 9–8
shows an example of a log file without comments.
Example 9–1 The Default Log Configuration File with Comments
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--============================================================ -->
<!--============================================================ -->
<!--NetPoint Logging Configuration File -->
<!-- -->
<!--Changes to this file will be automatically taken into effect -->
<!--in one minute. This does not require any server restart. -->
<!-- -->
<!--============================================================ -->
<!--============================================================ -->
<!--Set the Log Threshold -->
<!---->
<!--The log Threshold determines the amount of information to log. -->
<!--Selecting a lower level of logging includes the information -->
<!--logged at the higher levels. For example, LOGLEVEL_ERROR -->
<!--includes the information collected at LOGLEVEL_FATAL. -->
<!---->
<!--Choices are: -->
<!--LOGLEVEL_FATAL - serious error, possibly a program halt. -->
<!--LOGLEVEL_ERROR - a transient or self-correcting problem. -->
<!--LOGLEVEL_WARNING - a problem that does not cause an error. -->
<!--LOGLEVEL_INFO - reports the current state of the component. -->
<!--LOGLEVEL_DEBUG1 - basic debugging information. -->
<!--LOGLEVEL_DEBUG2 - advanced debugging information. -->
<!--LOGLEVEL_DEBUG3 - logs performance-sensitive code. -->
<!--LOGLEVEL_TRACE - used when you need to trace the code path -->
<!--execution or capture metrics. Includes all previous levels. -->
<!-- -->
<!--If you do not specify a threshold, the default is WARNING. -->
<!-- -->
<!--In addition to specifying a threshold, you need to specify -->
<!--if changes that you make to the logging configuration in -->
<!--the NetPoint GUI overwrite the settings in this file. The -->
<!--AutoSync parameter accomplishes this. This parameter takes a -->
<!--value of True or False. If set to True, changes made in the -->
<!--GUI overwrite changes in this config file. If False, changes -->
<!--made in the GUI are only in effect until the server is -->
<!--stopped or restarted, after which the settings in this file -->
<!--overwrite the GUI settings. The default is True. -->
<!-- -->
See Also: The log configuration file on your system.
About Log Configuration File Paths and Contents
Logging WebGate Event Messages 9-7
<!-- -->
<CompoundList xmlns="http://www.oblix.com" ListName="logframework.xml.staging">
<SimpleList>
<NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" />
<NameValPair ParamName="AUTOSYNC" Value="True" />
<!-- SECURE_LOGGING flag can be used to turn on/off Secure Logging -->
<!-- feature. By defalut this feature is tunred on. -->
<NameValPair ParamName="SECURE_LOGGING" Value="On" />
<!-- In addition to specifying a log threshold, you need to -->
<!-- configure log level for which Secure Logging should be -->
<!-- applicable.Choices for this can be used same as that of -->
<!-- LOG_THRESHOLD_LEVEL. Secure log threshold can be set using -->
<!-- LOG_SECURITY_THRESHOLD_LEVEL flag. Default value for Secure -->
<!-- log threshold is TRACE. -->
<NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL"
Value="LOGLEVEL_TRACE" />
<!-- LOG_SECURITY_ESCAPE_CHARS is used to configure escape sequence -->
<!-- characters. This can be used to avoid additional information -->
<!-- getting overwritten due to Secure Logging mechanism. Currently -->
<!-- following characters have been identified as escape sequence. -->
<!-- Configuring inappropriate characters may lead to sensitive -->
<!-- information being unmasked. -->
<NameValPair ParamName="LOG_SECURITY_ESCAPE_CHARS" Value="),]" />
<!-- LOG_SECURITY_MASK_LENGTH is used to specify default masking -->
<!-- length if none is specified in FILTER_LIST. -->
<!-- Default value for LOG_SECURITY_MASK_LENGTH is 300. -->
<NameValPair ParamName="LOG_SECURITY_MASK_LENGTH" Value="300" / >
</SimpleList>
<!-- -->
<!-- -->
<!--============================================================ -->
<!--============================================================ -->
<!--Configure the Log Level -->
<!-- -->
<!-- -->
<!--To configure a log level, you specify a name for the -->
<!--configuration (for instance, MyErrorLog1) and -->
<!--the log level that you are configuring. You can create -->
<!--more than one configuration per log level if you want -->
<!--to output to more than one destination. You can output to -->
<!--the system log or to a file, as specified on -->
<!--the LOG_WRITER parameter. The value for the LOG_WRITER -->
<!--parameter may only be SysLogWriter, FileLogWriter or -->
<!--MPFileLogWriter. The MPFileLogWriter is a multi-process safe -->
<!--FileLogWriter. It should be used to log in webcomponents i.e -->
<!--Webgate loaded on multiprocess -->
<!--webservers like Apache and IPlanet(UNIX) -->
<!-- -->
<!--If you do not specify an output destination, the default is -->
<!--SysLogWriter. -->
<!-- -->
<!--If outputting to a file, you also specify a file name and -->
<!--other parameters. Default parameter values are: -->
<!--FILE_NAME: <installdir>/oblix/log/oblog.log -->
<!--BUFFER_SIZE: 32767 (number of bytes) -->
<!--MAX_ROTATION_SIZE: 5242880 (bytes, equivalent to 5MB) -->
<!--MAX_ROTATION_TIME: 86400 (seconds, equivalent to one day) -->
<!-- -->
<!--Configuring the log level does not ensure that the data is -->
<!--actually collected. Data collection for a log is -->
About Log Configuration File Paths and Contents
9-8 Administrator's Guide for Oracle Access Management
<!--determined by the LOG_THRESHOLD_LEVEL parameter, above, -->
<!--and the LOG_STATUS parameter in the log configuration. -->
<!-- -->
<!--If you do not provide a LOG_STATUS, the default for -->
<!--LOGLEVEL_FATAL, LOGLEVEL_ERROR, and LOGLEVEL_WARNING, -->
<!--is On. -->
<!---->
<!--This file contains several sample configurations that are -->
<!--enclosed in comments. To use them, remove the comments. -->
<!-- -->
<CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG">
<!--Write all FATAL logs to the system logger. -->
<ValNameList xmlns="http://www.oblix.com" ListName="LogFatal2Sys">
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL" />
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />
<NameValPair ParamName="LOG_STATUS" Value="On" />
</ValNameList>
<!--Write all logs to the Oracle log file. -->
<ValNameList xmlns="http://www.oblix.com" ListName="LogAll2File">
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ALL" />
<NameValPair ParamName="LOG_WRITER" Value="FileLogWriter" />
<NameValPair ParamName="FILE_NAME" Value="oblog.log" />
<!-- Buffer up to 64 KB (expressed in bytes) of log entries before
flushing to the file. -->
<NameValPair ParamName="BUFFER_SIZE" Value="65535" />
<!--Rotate the log file once it exceeds 50 MB (expressed in bytes). -->
<NameValPair ParamName="MAX_ROTATION_SIZE" Value="52428800" />
<!--Rotate the log file after 24 hours (expressed in seconds). -->
<NameValPair ParamName="MAX_ROTATION_TIME" Value="86400" />
<NameValPair ParamName="LOG_STATUS" Value="On" />
</ValNameList>
</CompoundList>
<!-- List of values that can be specified in the module config -->
<!-- -->
<!-- On - Uses loglevel set in the loglevel threshold -->
<!-- Off - No information is logged -->
<!-- LOGLEVEL_FATAL - serious error, possibly a program halt. -->
<!-- LOGLEVEL_ERROR - a transient or self-correcting problem. -->
<!-- LOGLEVEL_WARNING - a problem that does not cause an error. -->
<!-- LOGLEVEL_INFO - reports the current state of the component. -->
<!-- LOGLEVEL_DEBUG1 - basic debugging information. -->
<!-- LOGLEVEL_DEBUG2 - advanced debugging information. -->
<!-- LOGLEVEL_DEBUG3 - logs performance-sensitive code. -->
<!-- LOGLEVEL_TRACE - used when you need to trace the code path -->
<!-- execution or capture metrics. Includes all previous levels. -->
<!-- -->
<!-- List of modules that can be specified in the module config -->
<!-- -->
<!-- ALL_MODULES - Applies to all log modules -->
<!-- Specific module name - Applies to specific module -->
<!-- -->
<!-- -->
<!-- <ValNameList -->
<!-- xmlns="http://www.oblix.com" -->
<!-- ListName="MODULE_CONFIG"> -->
<!-- <NameValPair -->
<!-- ParamName="CONNECTIVITY" -->
<!-- Value="LOGLEVEL_TRACE"></NameValPair> -->
<!-- </ValNameList> --><!--
<!--FILTER_LIST is used to maintain list of attributes which need -->
About Directing Log Output to a File or the System File
Logging WebGate Event Messages 9-9
<!-- to be treated as sensitive and hence will be filtered out from -->
<!-- from logs. FILTER_LIST consist of all attribute names along -->
<!-- with corresponding masking lengths.There should be separate -->
<!-- entry in the list for the display name of the attribute -->
<!-- identified as sensitive. All attributes configured are case -->
<!-- sensitive i.e. if we configured sensitive attribute homePhone -->
<!-- as HomePhone then it will not get filtered out from logs. -->
<!-- By default four attributes (password, Password, response and -->
<!-- Response) are configured as sensitive -->
<!-- A sample configuration is shown below -->
<!-- <ValNameList -->
<!-- xmlns="http://www.oblix.com" -->
<!-- ListName="FILTER_LIST"> -->
<!-- <NameValPair -->
<!-- ParamName="password" -->
<!-- Value="40"></NameValPair> -->
<!-- <NameValPair -->
<!-- ParamName="Password" -->
<!-- Value="40"></NameValPair> -->
<!-- <NameValPair -->
<!-- ParamName="response" -->
<!-- Value="40"></NameValPair> -->
<!-- <NameValPair -->
<!-- ParamName="Response" -->
<!-- Value="40"></NameValPair> -->
<!-- <NameValPair -->
<!-- ParamName="homePhone" -->
<!-- Value="40"></NameValPair> -->
<!-- </ValNameList> -->
<ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
<NameValPair ParamName="password" Value="40" />
<NameValPair ParamName="Password" Value="40" />
<NameValPair ParamName="passwd" Value="40" />
<NameValPair ParamName="Passwd" Value="40" />
<NameValPair ParamName="response" Value="40" />
<NameValPair ParamName="Response" Value="40" />
</ValNameList>
</CompoundList>
9.3 About Directing Log Output to a File or the System File
To send log output to a destination, you configure a log writer. A log writer can send
log output to one, none, or both of the following:
■A log file.
This file resides under the root installation directory of the component.
■The system file of the host for the component.
If more than one component resides on the same host, all components send data to
the system log file on that host.
You can send logs of a particular level, or logs of different levels, to more than one type
of log writer. For instance, you can send Fatal data to the system log, and send Trace
data to a file. Or, you can send Fatal data to both the system log and a file.
You define log writers in the log configuration file using the
LOG_WRITER
parameter in
a log-handler definition. See "About The Second Compound List and Log Handlers"
Structure and Parameters of the Log Configuration File
9-10 Administrator's Guide for Oracle Access Management
on page 9-13 for details.
The log writers are described in Table 9–3.
9.4 Structure and Parameters of the Log Configuration File
The log configuration file conforms to a standard format. You can edit parameters and
add or subtract sections known as log-handler definitions, but do not change the
underlying format of the log configuration file.
See Example 9–1 or Example 9–8 for a listing of the default log configuration file.
The rest of this section discusses the following topics:
■About The Log Configuration File Header
■About The Initial Compound List
■About The Simple List and Logging Threshold
■About The Second Compound List and Log Handlers
■About The List for Per-Module Logging
■About The Filter List
■About XML Element Order
Table 9–3 Log Writers
Writer Description
SysLogWriter
Sends data to the system log file for the computer that hosts the
component being logged. Typically, the system log file contains event
information from multiple applications and the host operating system.
For Windows, this is the application log file located at My Computer,
Manage, Event Viewer, Application.
For UNIX platforms, the name and location of the system log file can
vary according to the computer and the preferences of the system
Administrator. Consult the Administrator of the computer for the file
location.
The default log configuration file sends Fatal, Error, and Warning
messages to the system log file.
FileLogWriter
This writer is recommended when you want to save log data for an
OAM Server or other single-process application on a disk file.
The FileLogWriter opens the log file and holds it open for disk writes
until the approximate file size limit or file rotation interval has been
reached. Oracle does not recommend this log writer for situations
where more than one process needs to write to the same log file. For
these situations, use the MPFileLogWriter.
MPFileLogWriter
This writer resembles the FileLogWriter, except that it opens and
closes the log file each time it writes data to the file. This enables
multiple processes to write to the file in turn. However, this practice
can slow performance substantially.
Oracle recommends using MPFileLogWriter only when FileLogWriter
fails to record logging data from some of the processes associated with
a multi-process application, for example, an Access Client installed on
a multi-process Web server (such as Apache) or the Solaris version of
the iPlanet Web server.
Structure and Parameters of the Log Configuration File
Logging WebGate Event Messages 9-11
9.4.1 About The Log Configuration File Header
At the beginning of the log configuration file there is an XML file header:
<?xml version="1.0" encoding="ISO-8859-1" ?>
The header serves the following purposes:
■The header declares the relevant XML version, which is always 1.0.
■It also declares the encoding format, which is always ISO-8559-1.
9.4.2 About The Initial Compound List
The header is followed by an initial compound list that is delimited as follows:
<CompoundList xmlns="http://www.oblix.com" ListName="logframework.xml.staging">
. . .
</CompoundList>
The first compound list is structured as follows:
■The compound list start-tag shows the relevant XML name space for the log
configuration file in the
xmlns
parameter.
■The compound list start-tag also provides a name for the compound list in the
ListName
parameter.
■The compound list end-tag occurs near the end of the file.
This compound list delimits all log configuration information.
9.4.3 About The Simple List and Logging Threshold
After the start-tag for the first compound list, a simple list sets the global defaults for
logging, as follows:
<SimpleList>
. . .
</SimpleList>
Between the start and end tags of the simple list, you configure the following:
Table 9–4 Global Parameters in the First Compound List
Parameter Description
LOG_LEVEL_THRESHOLD
Sets the default logging threshold.
Default value:
LOGLEVEL_WARNING
Possible Values: Refer to log levels in "About Log Levels" on
page 9-2
The global threshold allows logs of a particular level and more
general levels to be collected, and prevents lower-level logs from
being collected. This threshold can be overridden by a
per-module threshold. See "Configuring Different Threshold
Levels for Different Types of Data" on page 9-22 for details.
SECURE_LOGGING
Dynamically enables or disables the secure logging mechanism.
This does not require a server or component restart.
Default value: On
Possible Values: On or Off
Structure and Parameters of the Log Configuration File
9-12 Administrator's Guide for Oracle Access Management
Example 9–2 shows the simple lists containing global settings, which appear in the
first compound list in the oblog_config_wg.xml file.
Example 9–2 Simple Lists with Global Settings (First Compound List in oblog_config_
wg.xml)
<SimpleList>
<NameValPair
ParamName="LOG_THRESHOLD_LEVEL"
Value="LOGLEVEL_WARNING">
</NameValPair>
<NameValPair
ParamName="AUTOSYNC"
Value="True">
</NameValPair>
<NameValPair
ParamName="SECURE_LOGGING"
Value="On">
</NameValPair>
<NameValPair
ParamName="LOG_SECURITY_THRESHOLD_LEVEL"
Value="LOGLEVEL_TRACE">
</NameValPair>
<NameValPair
ParamName="LOG_SECURITY_ESCAPE_CHARS"
Value="),]">
</NameValPair>
LOG_SECURITY_THRESHOLD_
LEVEL
Indicates the log threshold for which secure logging is effective.
Default value:
LOGLEVEL_TRACE
Possible Values: Refer to log levels in "About Log Levels" on
page 9-2
Note: Ensure that
LOG_THRESHOLD_LEVEL
and
LOG_SECURITY_
THRESHOLD_LEVEL
are the same or are consistent with one
another. For example, if
LOG_THRESHOLD_LEVEL
is set to
LOGLEVEL_TRACE
while
LOG_SECURITY_THRESHOLD_LEVEL
is set at
LOGLEVEL_WARNING
, then secure logging applies to
LOGLEVEL_
WARNING
and above but does not apply to
LOGLEVEL_TRACE
.
LOG_SECURITY_ESCAPE_
CHARS
Configure escape sequence characters used to avoid additional
information being overwritten due to the secure logging
mechanism. Use a comma separated list as shown here.
Default value: ),]
Possible Values: Characters only
Note: Default values are recommended. Configuring
inappropriate characters may lead to sensitive information being
unmasked.
LOG_SECURITY_MASK_LENGTH
Specifies the default masking length if none is specified in
FILTER_LIST.
Default value: 300
Possible Values: Positive integer
Note: FILTER_LIST appears after the second compound list (log
handlers). For more information, see "Filtering Sensitive
Attributes" on page 9-26.
Table 9–4 (Cont.) Global Parameters in the First Compound List
Parameter Description
Structure and Parameters of the Log Configuration File
Logging WebGate Event Messages 9-13
<NameValPair
ParamName="LOG_SECURITY_MASK_LENGTH"
Value="300">
</NameValPair>
</SimpleList>
9.4.4 About The Second Compound List and Log Handlers
After the simple list containing global settings, and within the start and end tags for
the initial compound list, you specify an additional compound list. This compound list
contains log-handler definitions. The start and end tags for this list are as follows:
<CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG">
. . .
</CompoundList>
This compound list tag is configured as follows:
■In the start tag for the compound list, the
xmlns
parameter indicates the relevant
XML name space.
■Also in the start tag, you specify the name of the list on the
ListName
parameter.
Typically, the name of this list is
LOG_CONFIG
.
Between the start and end tags for the compound list for the log-handler, you specify
one or more
ValNameList
elements. Each
ValNameList
element contains the definition
for a log-handler. Each instance of this element begins and ends as follows:
<ValNameList xmlns="http://www.oblix.com" ListName="Unique_Name">
. . .
</ValNameList>
The
ValNameList
elements are configured as follows:
■The opening tag sets the relevant XML name space on the
xmlns
parameter.
■The opening tag also sets a name for the log-handler on the
ListName
parameter.
Within the opening and closing
ValNameList
tags, you configure the log-handler. A
log-handler definition contains three mandatory
NameValPair
elements:
■The first mandatory
NameValPair
element defines the logging level for the
log-handler.
This element contains the statement
ParamName="LOG_LEVEL"
, whose value is a
reserved name in Table 9–1, as follows:
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL" />
■The second mandatory
NameValPair
element defines the destination for log
output.
This element contains a statement
ParamName="LOG_WRITER"
, whose value is a
reserved name in Table 9–3, as follows:
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />
■The third mandatory
NameValPair
element toggles this log-handler on and off.
This element contains a statement
ParamName="LOG_STATUS"
, with a value of
On
or
Off
, as follows:
<NameValPair ParamName="LOG_STATUS" Value="On" />
Structure and Parameters of the Log Configuration File
9-14 Administrator's Guide for Oracle Access Management
Finally, within the opening and closing
ValNameList
tags, if you specify
FileLogWriter
or
MPFileLogWriter
as the log writer, you can add none, some, or all of
the following. See Table 9–7 for details:
■A destination file name, as follows:
<NameValPair ParamName="FILE_NAME" Value="oblog.log" />
■A buffer size, as follows:
<NameValPair ParamName="BUFFER_SIZE" Value="65535" />
■A a file size that determines when a new log file is generated, as follows:
<NameValPair ParamName="MAX_ROTATION_SIZE" Value="52428800" />
■A time in minutes that determines the interval at which a new log file is generated,
as follows:
<NameValPair ParamName="MAX_ROTATION_TIME" Value="86400" />
9.4.5 About The List for Per-Module Logging
After the end tag for the compound list that delimits the log-handlers, and before the
end tag for the initial compound list, you can add per-module logging parameters. See
"Configuring Different Threshold Levels for Different Types of Data" on page 9-22 for
details.
9.4.6 About The Filter List
After the per-module logging parameters a filter list identifies sensitive information
that you might want to filter out of the log file. For example, passwords and responses
for lost password management are sensitive information that you might want to filter
out of the log file.
Each name value pair associated with the FILTER_LIST parameter provides the name
of a word or phrase to be checked before the log is written and the corresponding
masking length for that word or phrase. During logging, the value of the word or
phrase is masked and omitted from the log file.
Simply put, during logging Access Manager does not recognize whether a value to be
masked is an attribute or its display name or something different (plain text). Secure
Logging works by searching for words or phrases added in the FILTER_LIST and then
masking out any data that is followed by the occurrence of those words or phrases. For
example, in the following statement:
\csabuild\coreid1014\np_common\db\ldap\util\ldap_util3.cpp:3107 "ldap_parse_result
of Simple Bind" ld handle^0x0779FA00 result^0x09FB0088
bind^cn=orcladmin LDAP bind operation status code^0 Additional
error message^ freeit^0 parse_rc^0
After turning Secure Logging ON and adding "
bind
" in the FILTER_LIST (which is
neither an attribute nor a display name), whatever follows the word in the FILTER_
LIST (in this case, "
bind
") is masked. In this case, you would see the following in logs:
\csabuild\coreid1014\np_common\db\ldap\util\ldap_util3.cpp:3107 "ldap_parse_result
of Simple Bind" ld handle^0x0779FA00 result^0x09FB0088
bind^cn=orcladmin LDAP bind********** status code^0 Additional
error message^ freeit^0 parse_rc^0
Structure and Parameters of the Log Configuration File
Logging WebGate Event Messages 9-15
All attributes are case sensitive. For example, if you enter "
password
" instead of
"
Password
" as a display name for an attribute, then "
Password
" is not filtered. By
default, four attributes are always configured in the filter list: password, Password,
response, and Response.
The default masking length,
40
, is specified for each of the four default attributes. The
default mask length can be altered for the default attributes if needed. If you add other
attributes to the filter list, you might need a larger mask length (
300
, for example).
The default filter list is shown in Example 9–3.
Example 9–3 FILTER_LIST Masks Sensitive Attributes in Log Files
<ValNameList>
xmlns="http://www.oblix.com"
ListName="FILTER_LIST">
<NameValPair
ParamName="password"
Value="40"></NameValPair>
<NameValPair
ParamName="Password"
Value="40"></NameValPair>
<NameValPair
ParamName="passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="Passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="response"
Value="40"></NameValPair>
<NameValPair
ParamName="Response"
Value="40"></NameValPair>
</SimpleList>
When you add another attribute to the filter list, you must include the display name as
well as the attribute name in the directory server.
9.4.7 About XML Element Order
When using XML, you can specify parallel elements in a list in any order as long as the
elements remain intact and within the tags that originally bracketed them. For
example, the lists in Example 9–4 and Example 9–5 are equivalent:
Example 9–4 Valid Name/Value List
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ERROR" />
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />
<NameValPair ParamName="LOG_STATUS" Value="On" />
</ValNameList>
Example 9–5 Another Valid Name/Value List
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ERROR" />
<NameValPair ParamName="LOG_STATUS" Value="On" />
</ValNameList>
About Activating and Suppressing Logging Levels
9-16 Administrator's Guide for Oracle Access Management
Similarly, within a given tag, the attributes (except for the tag name, which must
always be the first element within the tag brackets) can be reordered, as long as they
remain intact and within the tag elements that originally bracketed them. The opening
tags for a name-value list in Example 9–6 and Example 9–7 are equivalent:
Example 9–6 Opening tag for a Name/Value List
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">
Example 9–7 Opening tag for a Name/Value List
<ValNameList ListName="LogError2Sys" xmlns="http://www.example.com">
9.5 About Activating and Suppressing Logging Levels
Several factors determine if logging is active for a particular log-handler. Table 9–5 lists
these factors.
9.5.1 About Log Handler Precedence
You can configure up to three log-handler definitions for a single log level in a log
configuration file. Three different log handlers are required to send output for a
particular log level to each of the three log writers described in Table 9–3.
If you specify different
LOG_STATUS
settings in these log handlers, the setting in the
log-handler definition closest to the physical end of the log configuration file sets the
status for the other log-handler definitions of the same log level. For example, you can
set
LOG_STATUS
to
Off
for the first two log handlers for the Error log level, but if
LOG_
STATUS
is
On
for the third and final log handler in the configuration file, logging still
occurs for all three handlers.
The
LOG_STATUS
settings are moot if that level is more fine-grained than the current
LOG_THRESHOLD_LEVEL
. In this case, logging cannot be activated at this level unless the
threshold is overridden by a module-specific threshold. See "Configuring Different
Threshold Levels for Different Types of Data" on page 9-22 for details.
Table 9–5 Factors that Determine Whether Logging Is Active
Factor Importance Description
LOG_ THRESHOLD_
LEVEL
Primary This parameter sets a cutoff for logging. Any log level
that is more detailed than the threshold is
suppressed. See Table 9–1 for valid log levels.
You override this parameter for a subset of items that
can be logged using the
MODULE_CONFIG
parameter.
See "Configuring Different Threshold Levels for
Different Types of Data" on page 9-22 for details.
MODULE_CONFIG
Primary This sets a per-module override for the global logging
threshold.
See "Configuring Different Threshold Levels for
Different Types of Data" on page 9-22 for details.
LOG_STATUS
Secondary This parameter toggles logging on or off, as long as it
is not overridden by the logging threshold or a
module-specific override.
The physical
position of a log
handler
Secondary See "About Log Handler Precedence" on page 9-16.
Understanding the Mandatory Log-Handler Configuration Parameters
Logging WebGate Event Messages 9-17
9.6 Understanding the Mandatory Log-Handler Configuration Parameters
At minimum, each log-handler definition contains five parameters listed in Table 9–6.
If you specify
FileLogWriter
or
MPFileLogWriter
as the value for the
LOG_WRITER
parameter, the four parameters in Table 9–7 are relevant.
Table 9–6 Mandatory Log Configuration File Parameters
Parameter Comment
xmlns
This parameter is specified in the opening
ValNameList
tag.
It specifies the relevant XML namespace for the current list and
is identical for all log-handler definitions in a given logging
configuration file. Example:
http://www.example.com
ListName
This parameter is specified in the opening
ValNameList
tag.
Where possible, use the default names.
When creating a new log-handler definition, select a memorable
name that you cannot confuse with other log handlers.
Examples:
WarningsAndAboveToSyslog
sends Fatal, Error, and Warning
messages to the system log file.
WarningsOnlyToFileLog128KBuffer
sends messages from just
the Warning level to a 128KB buffer, and hence to a disk file.
TraceOnlyToMPRotateDaily
sends messages from just the Trace
level to the multi-process file writer, which opens and closes the
file each time it writes to disk. This file is replaced with a fresh
(empty) file every day, regardless of the size of the file at the
time of replacement.
LOG_LEVEL
This specifies a log level. See Table 9–1 for details.
The default logging configuration file activates logging for three
levels: Fatal, Error, and Warning.
LOG_WRITER
This specifies the destination for log output for this log-handler.
See Table 9–3 for details.
The default log configuration file sends output to both the
system log and the log data file for the component doing the
logging.
LOG_STATUS
This parameter turns the log handler
on
or
off
.
Understanding the Mandatory Log-Handler Configuration Parameters
9-18 Administrator's Guide for Oracle Access Management
The following sections contain more information.
■Settings in the Default Log Configuration File
■Description of the Settings in the Default Log Configuration File
9.6.1 Settings in the Default Log Configuration File
As installed with each component, the log configuration file activates only the highest
three levels (Fatal, Error, and Warning) and directs all log output to the system log.
On Windows, you can view the system log for the computer that hosts the component
you are logging by navigating to My Computer, Manage, Event Viewer, Application.
System event entries for the components being logged are interspersed among the
system events for the operating system and applications other than Access Manager.
Table 9–7 Log Data File Configuration Parameters
Parameter Description Default
FILE_ NAME
Mandatory. Used only for the FileLogWriter or
MPFileLogWriter. It is the name and location of the
file where log data is written.
You can prepend an absolute path to the file name
to store it somewhere other than the default
location, which is:
component_install_dir\oblix\logs
Where component_install_dir is the root installation
directory for the component whose system events
you are logging.
When you create more than one log-handler
definition that sends output to FileLogWriter or
MPFileLogWriter, provide unique file names so
that multiple handlers do not write to the same file.
This caution does not apply to log handlers
accessing the SysLogWriter.
oblog.log
BUFFER_SIZE
Optional. This is the size of the buffer, in bytes, for
logged data as it is being written to the log file.
If you set the buffer value to 0 or a negative
number, the default value is used. To write to the
log file immediately, without buffering, set the
value to a small number, for example, 5. Oracle
recommends that you set a small buffer size in
situations where there are system failures.
65535
(64KB)
MAX_ ROTATION_
SIZE
Optional. When the log file reaches this size (in
bytes), a time stamp is appended to the file name,
for example
oblog.log
becomes
oblog.log1081303126
. New data is written to the
file with the original name.
52428800
(512KB)
MAX_ ROTATION_
TIME
Optional. A time interval, in seconds, when the log
file is renamed, whether or not it has reached the
maximum rotation size.
If the rotation time determines when the file is
rotated, the numbers appended to the log files
differ by the number of seconds in the rotation
interval. For example,
oblog.log.1081389526
and
oblog.log.1081303126
differ by 84,600, which is
the number of seconds in 24 hours. This is the
rotation interval set in the log configuration file.
86400
(1 day, in
seconds)
Understanding the Mandatory Log-Handler Configuration Parameters
Logging WebGate Event Messages 9-19
For Solaris and Linux environments, the location of the system log is recorded in a
system configuration file whose particulars can vary from computer to computer. For
the name and location of this system file or the system log, consult the owner of the
computer that hosts the component whose system log you want to examine.
Example 9–8 shows the default log configuration file with comments removed to
expose the file structure.
Example 9–8 A Default Log Configuration File Without Embedded Comments
<?xml version="1.0" encoding="utf-8"?>
<CompoundList
xmlns="http://www.oblix.com
ListName="oblog_config_wg.xml.staging">
<SimpleList>
<NameValPair
ParamName="LOG_THRESHOLD_LEVEL"
Value="LOGLEVEL_WARNING"></NameValPair>
</SimpleList>
<SimpleList>
<NameValPair
ParamName="AUTOSYNC"
Value="True"></NameValPair>
</SimpleList>
<SimpleList>
<NameValPair
ParamName="SECURE_LOGGING"
Value="On"></NameValPair>
</SimpleList>
<SimpleList>
<NameValPair
ParamName="LOG_SECURITY_THRESHOLD_LEVEL"
Value="LOGLEVEL_TRACE"></NameValPair>
</SimpleList>
<SimpleList>
<NameValPair
ParamName="LOG_SECURITY_ESCAPE_CHARS"
Value="),]"></NameValPair>
</SimpleList>
<SimpleList>
<NameValPair
ParamName="LOG_SECURITY_MASK_LENGTH"
Value="300"></NameValPair>
</SimpleList>
<CompoundList
xmlns="http://www.oblix.com"
ListName="LOG_CONFIG">
<ValNameList
xmlns="http://www.oblix.com"
ListName="LogFatal2Sys">
<NameValPair
ParamName="LOG_LEVEL"
Value="LOGLEVEL_FATAL"></NameValPair>
<NameValPair
ParamName="LOG_WRITER"
Value="SysLogWriter"></NameValPair>
<NameValPair
ParamName="LOG_STATUS"
Value="On"></NameValPair>
</ValNameList>
Understanding the Mandatory Log-Handler Configuration Parameters
9-20 Administrator's Guide for Oracle Access Management
<ValNameList
xmlns="http://www.oblix.com"
ListName="LogAll2File">
<NameValPair
ParamName="LOG_LEVEL"
Value="LOGLEVEL_ALL"></NameValPair>
<NameValPair
ParamName="LOG_WRITER"
Value="FileLogWriter"></NameValPair>
<NameValPair
ParamName="FILE_NAME"
Value="oblog.log"></NameValPair>
<NameValPair
ParamName="BUFFER_SIZE"
Value="65535"></NameValPair>
<NameValPair
ParamName="MAX_ROTATION_SIZE"
Value="52428800"></NameValPair>
<NameValPair
ParamName="MAX_ROTATION_TIME"
Value="86400"></NameValPair>
<NameValPair
ParamName="LOG_STATUS"
Value="On"></NameValPair>
</ValNameList>
</CompoundList>
<ValNameList
xmlns="http://www.oblix.com"
ListName="FILTER_LIST">
<NameValPair
ParamName="password"
Value="40"></NameValPair>
<NameValPair
ParamName="Password"
Value="40"></NameValPair>
<NameValPair
ParamName="passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="Passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="response"
Value="40"></NameValPair>
<NameValPair
ParamName="Response"
Value="40"></NameValPair>
</ValNameList>
</CompoundList>
9.6.2 Description of the Settings in the Default Log Configuration File
The default configuration file sends Fatal, Error, and Warning messages to both the
system log and to a log data file named oblog.log.
The simple list near the top of the file sets the following parameters:
■It sets the
LOG_THRESHOLD_LEVEL
to
Warning
.
The threshold suppresses logging for levels that are more fine-grained than
Warning. You can override this threshold. See "Configuring Different Threshold
Understanding the Mandatory Log-Handler Configuration Parameters
Logging WebGate Event Messages 9-21
Levels for Different Types of Data" on page 9-22 for details.
The nested compound list contains four log-handler definitions:
■The first, named
LogFatal2Sys
, sets the logging level to
Fatal
and sets
LOG_
STATUS
to On.
The threshold level is Warning, which is more fine-grained than Fatal, so this
definition is in effect. The log output is written to the system log, as specified by
the
LOG_WRITER
parameter.
■The
LogError2Sys
log-handler definition sends Error level messages to the system
log.
Error is located before the current threshold level (Warning), so this definition is in
effect.
■The
LogWarning2Sys
definition sends Warning level output to the system log.
Like the two previous log-handler definitions, it is not overridden by the current
LOG_THRESHOLD_LEVEL
parameter.
■
LogAll2File
, the final log-handler definition, appears to send output from all log
levels to a disk file named oblog.log.
The
LOG_THRESHOLD_LEVEL
parameter is set to Warning, so only the output from
the Fatal, Error, and Warning levels are recorded in this log data file. Since output
from
LogAll2File
goes to the
FileLogWriter
, the parameters governing file name,
buffer size, rotation size, and rotation interval all take effect.
Figure 9–1 illustrates log-level activation in the default log confirmation file.
Figure 9–1 Log-Level Activation in the Default Log Configuration File
Configuring Different Threshold Levels for Different Types of Data
9-22 Administrator's Guide for Oracle Access Management
9.7 Configuring Different Threshold Levels for Different Types of Data
When diagnosing a problem, you may not want detailed logs for every operation that
a component performs. For example, to diagnose slow response times for requests that
an Identity Server submits to its directory, you would want detailed information on
LDAP operations and fewer details about other types of operations.
As of release 10.1.4.2, you can configure per-module or per-function threshold levels in
the log configuration file, so that Access Manager generates detailed logs for some
components while generating concise logs, or no logs, for others.
You configure per-module logging thresholds in a
MODULE_CONFIG
section in the oblog_
config_wg.xml file. The
MODULE_CONFIG
section overrides the global default that you
specify on the
LOG_THRESHOLD_LEVEL
in the simple list section of this file.
The rest of this section discusses the following topics:
■About the MODULE_CONFIG Section
■Configuring a Log Level Threshold for a Function or Module
9.7.1 About the MODULE_CONFIG Section
As described in "Structure and Parameters of the Log Configuration File" on page 9-10,
in the log configuration file you configure a global logging threshold. The following is
an example of the global
LOG_THRESHOLD_LEVEL
setting:
<SimpleList>
<NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" />
. . .
</SimpleList>
In addition to the global threshold, the configuration file can contain a
ValNameList
that defines function- or module-specific log thresholds. The name of this list is always
MODULE_CONFIG
. Only one instance of this list is permitted in the log configuration file,
and the information in the list applies to all log writers defined in the file. As of release
10.1.4.2, the default log configuration file contains a commented sample of the
MODULE_
CONFIG
list.
Each item in the
MODULE_CONFIG
list sets a logging level for a module, as shown in the
following example:
<ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
<NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>
<NameValPair ParamName="DB_RUNTIME" Value="LOGLEVEL_TRACE"></NameValPair>
</ValNameList>
The elements in this section are as follows:
■The
ValNameList
tag delimits the list of per-module logging thresholds.
■One
NameValPair
tag delimits each specific per-module logging threshold.
■The
ParamName
parameter sets the name of a module or function.
See Table 9–8 for a list of valid values.
■The
Value
parameter sets the logging threshold for the module that you specify as
a value for the
ParamName
parameter.
Table 9–1 lists the permissible values for the
Value
parameter. In addition to these
values, you can specify the value
ON
to enable logging for the module and a value
of
OFF
to disable logging for the specific module.
Configuring Different Threshold Levels for Different Types of Data
Logging WebGate Event Messages 9-23
The following sections contain more information.
■Location of the Per-Module Logging Section in the Log Configuration File
■List of Modules That Can Be Logged
9.7.1.1 Location of the Per-Module Logging Section in the Log Configuration File
You add the per-module logging threshold section near the end of the log
configuration file, after the closing tag for the compound list for the log-handlers and
before the closing tag for the first compound list in the file.
This section contains an example of the per-module logging section. See "Configuring
a Log Level Threshold for a Function or Module" for details.
9.7.1.2 List of Modules That Can Be Logged
Table 9–8 describes the a partial list of the values that you can specify for the
ParamName
parameter in the
MODULE_CONFIG
list.
Table 9–8 ParamName Values You Can Configure for Per-Module Logging Threshold
ParamName Value Logging Threshold That This Parameter Sets
AAA_ACTIONS
Sets a logging threshold for triggered actions that are configured as
part of a policy in the OAM Server.
<ValNameList xmlns="http://www.oblix.com"
ListName="MODULE_CONFIG">
<NameValPair Paramname="AAA_ACTIONS" Value="OFF">
</NameValPair>
AAA_AMENGINE
Sets a logging threshold for activity performed by the Access
Manager engine.
AAA_ISRESRCOPPROT
Sets a logging threshold for all OAM Server activities related to
determining if a resource operation is protected.
ACCESS_CLIENT
Sets a logging threshold for operations performed by an access
client, that is, an Access Client or Webgate.
ACCESS_GATE
Sets a logging threshold for operations performed by an Access
Client.
ACCESS_SDK
Sets a logging threshold for operations performed by the Access
Manager SDK interface.
See the Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details.
ACCESS_SERVER
Sets a logging threshold for operations performed in the OAM
Server.
AM_SDK
Sets a logging threshold for the Access Manager SDK.
See the Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details.
AUDIT
Sets a logging threshold for auditing.
See Chapter 8 for details.
AUTHENTICATION
Sets a logging threshold for user authentication operations.
AUTHN_MGMT
Sets a logging threshold for authentication scheme management.
AUTHN_PLUGIN
Sets a logging threshold for operations performed by an
authentication plug-in.
AUTHORIZATION
Sets a logging threshold for user authorization operations.
Configuring Different Threshold Levels for Different Types of Data
9-24 Administrator's Guide for Oracle Access Management
AUTHZ_MGMT
Sets a logging threshold for authorization scheme management.
AUTHZ_PLUGIN
Sets a logging threshold for authorization plug-in operations.
CACHE
Sets a logging threshold for cache management and operations on
the caches.
CONN_MGMT
Sets a logging threshold for connection management.
CONN_RUNTIME
Sets a logging threshold for connection run time.
CONNECTIVITY
Sets a logging threshold for client-sever connectivity and
messaging.
DB_CONFIGURATION
Sets a logging threshold for the data store interface layer
configuration.
DB_RUNTIME
Sets a logging threshold for the data store interface layer run time.
DIAGNOSTIC_FRAMEWORK
Sets a logging threshold for the diagnostic framework.
GROUPDB
Sets the threshold for logging accesses of Group Manager data in
the directory.
GROUP_MGR
Sets the threshold for logging Group Manager operations.
HTTP_REQ
Sets the threshold for logging HTTP request processing.
IDXML
Sets the threshold for logging IDXML operations.
See the Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details.
LDAP
Sets a logging threshold for LDAP SDK, for example:
<ValNameList xmlns="http://www.oblix.com"
ListName="MODULE_CONFIG">
<NameValPair Paramname="LDAP" Value="LOGLEVEL_TRACE">
</NameValPair>
NET
Sets a logging threshold for network APIs.
OBMYGROUPS
Sets a logging threshold for
ObMyGroups
processing. This refers to
searches of groups where the person who initiated the search is a
member.
OIS_CLIENT
Sets a logging threshold for the Identity client.
POLICY_MGMT
Sets a logging threshold for policy and policy domain management.
PPP
Sets a logging threshold for Identity Event Plug-in API operations.
See the Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details.
QUERY_BUILDER
Sets a logging threshold for Query Builder operations.
SECURITY
Sets a logging threshold for the security and encryption library.
SELECTOR
Sets a logging threshold for Selector operations.
SERVER
Sets a logging threshold for server infrastructure.
SSOTOKEN
Single sign-on token management.
UTILS
Sets a logging threshold for utility classes.
WEB
Sets a logging threshold for the Web server plug-in interface.
XML
Sets a logging threshold for the XML Infrastructure.
Table 9–8 (Cont.) ParamName Values You Can Configure for Per-Module Logging
ParamName Value Logging Threshold That This Parameter Sets
Configuring Different Threshold Levels for Different Types of Data
Logging WebGate Event Messages 9-25
9.7.2 Configuring a Log Level Threshold for a Function or Module
The following procedure describes how to configure a function- or module-specific log
level threshold.
1. Open the log configuration file in the following location:
Webgate_install_dir\identity|access\oblix\config
2. If a
ValNameList
section with a
ListName
of
MODULE_CONFIG
does not already exist
in this file, create one that is similar to the following:
<ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
</ValNameList>
Place this list after the end tag for the compound list that contains the log handler
definitions. If there are comments immediately after this end tag, place the list
after the comments.
3. Between the opening and closing tags of the new
ValNameList
element, configure
one or more
NameValPair
elements.
This element contains a
ParamName
parameter and a
Value
parameter. See
Table 9–8 for the modules that you can supply on the
ParamName
parameter. See
Table 9–1 for values, or you can specify a value of
On
or
Off
. The following is an
example:
<NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>
You can specify multiple
ValNamePair
elements within the
ValNameList
.
A complete per-module logging threshold section is illustrated in bold in the
following example:
<!-- ============================================================ -->
<!-- Configure the Log Level -->
. . .
<CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG">
<!-- Write all FATAL logs to the system logger. -->
<ValNameList xmlns="http://www.oblix.com" ListName="LogFatal2Sys">
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL">
</NameValPair>
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter">
</NameValPair>
<NameValPair ParamName="LOG_STATUS" Value="On">
</NameValPair>
</ValNameList>
. . .
</CompoundList>
<!-- List of values that can be specified in the module config -->
<!-- -->
<!-- On - Uses loglevel set in the loglevel threshold -->
<!-- Off - No information is logged -->
<!-- LOGLEVEL_FATAL - serious error, possibly a program halt. -->
<!-- LOGLEVEL_ERROR - a transient or self-correcting problem. -->
<!-- LOGLEVEL_WARNING - a problem that does not cause an error. -->
<!-- LOGLEVEL_INFO - reports the current state of the component. -->
<!-- LOGLEVEL_DEBUG1 - basic debugging information. -->
<!-- LOGLEVEL_DEBUG2 - advanced debugging information. -->
<!-- LOGLEVEL_DEBUG3 - logs performance-sensitive code. -->
<!-- LOGLEVEL_TRACE - used when you need to trace the code path -->
<!-- execution or capture metrics. Includes all previous levels. -->
Filtering Sensitive Attributes
9-26 Administrator's Guide for Oracle Access Management
<!-- -->
<!-- List of modules that can be specified in the module config -->
<!-- -->
<!-- ALL_MODULES - Applies to all log modules -->
<!-- Specific module name - Applies to specific module -->
<!-- -->
<!-- -->
<!-- <ValNameList -->
<!-- xmlns="http://www.oblix.com" -->
<!-- ListName="MODULE_CONFIG"> -->
<!-- <NameValPair -->
<!-- ParamName="CONNECTIVITY" -->
<!-- Value="LOGLEVEL_TRACE"></NameValPair> -->
<!-- </ValNameList> -->
<ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
<NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>
<NameValPair ParamName="DB_RUNTIME" Value="LOGLEVEL_TRACE">
</NameValPair>
</ValNameList>
</CompoundList>
9.8 Filtering Sensitive Attributes
As described earlier, you can activate secure logging and expand the default filter list
to mask sensitive information from the log file.
When you add an attribute to the filter list, you must include the display name as well
as the attribute name in the directory server. The following procedure describes how to
perform this task. In this example, you are instructed to filter the user's home phone
number: display name Home Phone; attribute name
homePhone
. However, you can
filter the attribute of your choice.
Oracle recommends that you optimize the use of FILTER_LIST to reduce the runtime
cost. For example, rather than adding two ParamName variations (
User Password
and
userPassword
), you could use only one. Using
Password
as the ParamName masks
values for
User Password
,
userPassword
, and other words that end with
Password
.
Also, instead of including both
Home Phone
and
homePhone
in FILTER_LIST, you could
simply use
Phone
.
1. Open the log configuration file in a text editor:
Webgate_install_dir\identity|access\oblix\config\oblog_config_wg.xml
2. In oblog_config_wg.xml:
Note: Each value added to FILTER_LIST increases the runtime cost
of using Secure Logging.
See Also:
■"About Logging, Log Levels, and Log Output" on page 9-1
■"About The Simple List and Logging Threshold" on page 9-11
■"About The Filter List" on page 9-14
■"Settings in the Default Log Configuration File" on page 9-18
Filtering Sensitive Attributes
Logging WebGate Event Messages 9-27
a. Confirm that secure logging is active. For example:
<SimpleList>
<NameValPair
ParamName="SECURE_LOGGING"
Value="On"></NameValPair>
</SimpleList>
b. Locate the
FILTER_LIST
parameter at the end of the file. For example:
<ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
<NameValPair ParamName="password" Value="40" />
<NameValPair ParamName="Password" Value="40" />
<NameValPair ParamName="response" Value="40" />
<NameValPair ParamName="Response" Value="40" />
</ValNameList>
c. Add the display name to mask and the value for the mask length, then add the
attribute and the value for the mask length. For example:
<NameValPair ParamName="Home Phone" Value="300" />
<NameValPair ParamName="homePhone" Value="300" />
d. Confirm that
LOG_THRESHOLD_LEVEL
and
LOG_SECURITY_THRESHOLD_LEVEL
are
at the same level or are consistent with each other, as described in Table 9–4 on
page 9-11. For example:
<SimpleList>
<NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" />
</SimpleList>
...
<SimpleList>
<NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" Value="LOGLEVEL_
WARNING" />
</SimpleList>
e. Save the oblog_config_wg.xml file.
3. Filtering User Password: Perform the following steps and see "About The Filter
List" on page 9-14:
In the filter list in oblog_config_wg.xml, add the User Password display name and
the corresponding attribute, and set the mask length for each. For example:
<ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
...
<NameValPair ParamName="User Password" Value="40" />
<NameValPair ParamName="userPassword" Value="40" />
</ValNameList>
4. Test secure logging and filtering of sensitive information as follows:
a. In the oblog_config_wg.xml file, set the
LOG_THRESHOLD_LEVEL
and
LOG_
SECURITY_THRESHOLD_LEVEL
to
TRACE
:
<NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_TRACE" />
...
<NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" Value="LOGLEVEL_
Note: For testing, set the
LOG_THRESHOLD_LEVEL
and
LOG_SECURITY_
THRESHOLD_LEVEL
to
TRACE
. See Step 6a.
Filtering Sensitive Attributes
9-28 Administrator's Guide for Oracle Access Management
TRACE" />
b. Perform a task that involves the component for which you have configured
secure logging. For example:
Access a resource
View or modify the value of the attribute in the user's profile:
Home Phone
(if
the filtered attribute is
homePhone
).
c. Check the oblog and confirm that the filtered attribute value is masked by a
string like ***********.
Webgate_install_dir/access/oblix/log/oblog.log
d. In the oblog_config_wg.xml file, reset the
LOG_THRESHOLD_LEVEL
and
LOG_
SECURITY_THRESHOLD_LEVEL
to the desired level for your enterprise.
e. Adjust the mask length of filtered attributes if needed in the oblog_config_
wg.xml file. For example:
<NameValPair ParamName="Home Phone" Value="340" />
<NameValPair ParamName="homePhone" Value="340"/>
5. Repeat Steps 1 through 6 for each component in your deployment with one or
more masked attributes.
10
Reporting 10-1
10
Reporting
[11]
Oracle Access Manager enables you to use Oracle BI Publisher as the reporting
solution for Oracle Access Management services. Access Manager provides a
restricted-use license for Oracle BI Publisher and easy-to-use reporting packages.
This chapter contains the following sections.
■About the Reports
■Accessing Oracle Access Management Reports
■Supported Output Formats
■Reports for Access Manager
■Creating Reports Using Third-Party Software
10.1 About the Reports
Oracle Access Management integrates with Oracle Business Intelligence Publisher,
which provides a pre-defined set of compliance reports. The data in the database audit
store is exposed through pre-defined reports in Oracle Business Intelligence Publisher.
These reports allow you to drill down the audit data based on various criteria, such as
user name, time range, application type, and execution context identifier (ECID).
Out-of-the-box, there are several sample audit reports available with Oracle Access
Management and accessible with Oracle Business Intelligence Publisher. You can also
use Oracle Business Intelligence Publisher to create your own custom reports.
Oracle BI Enterprise Edition (Oracle BI EE) is a comprehensive set of enterprise
business intelligence tools and infrastructure, including a scalable and efficient query
and analysis server, an ad-hoc query and analysis tool, interactive dashboards,
proactive intelligence and alerts, real-time predictive intelligence, and an enterprise
reporting engine. Oracle BI EE is designed to bring greater business visibility and
insight to a wide variety of users.
The components of Oracle Business Intelligence Enterprise Edition share a common
service-oriented architecture, data access services, analytic and calculation
infrastructure, metadata management services, semantic business model, security
model and user preferences, and administration tools. Oracle Business Intelligence
Note: For large-scale deployments, it is recommended that you
deploy a dedicated enterprise-class reporting solution. A solution
based on tools such as Oracle Business Intelligence Enterprise Edition
can provide the flexibility, automation, and performance required for
a large-scale organizations.
Accessing Oracle Access Management Reports
10-2 Administrator's Guide for Oracle Access Management
Enterprise Edition provides scalability and performance with data-source specific
optimized analysis generation, optimized data access, advanced calculation, intelligent
caching services, and clustering. The following are Oracle Access Management
reporting features:
■Select and view reports from a predefined list in the BI Publisher.
■Filter report information.
■View reports on-screen in the desired format.
■Provide interactive reports.
10.2 Accessing Oracle Access Management Reports
To access Access Manager Reports, you must start BI Publisher and run them. BI
Publisher cannot be accessed through the Access Manager Console. You must open BI
publisher explicitly to access Access Manager reports.
Follow this procedure to start BI Publisher.
1. Navigate to Start, Oracle BI Publisher Desktop, Oracle - BIPHome10134 and
click Start BI Publisher.
The Oracle BI Publisher Home page appears.
2. Enter the user name and password.
3. Click Sign In.
Follow this procedure to run a report.
1. Start Access Manager Reports.
See "Accessing Oracle Access Management Reports" on page 10-2 for more
information.
2. Click the more... link under Shared Folders.
3. Click Access Manager Reports to access the reports.
Alternately, click the more... link under Access Manager Reports. The resulting
page displays the Access Manager Reports classified according to functional area.
4. Select the report to view by clicking its name.
5. Click View.
The Report Input Parameters page displays the input parameters that must be
provided to run a report. The parameters act as filter criteria. In some cases, at
least one or more fields are mandatory while some reports do not require any
input parameters. If you leave the input parameter field blank and click View, all
the information associated with the report is displayed.
6. Enter the required parameters, if any.
7. Click View to run the report.
The report is displayed.
10.3 Supported Output Formats
All BI Publisher reports are generated in a native XML format. This XML can be
transformed into other output formats. The following formats are supported:
■HTML
Reports for Access Manager
Reporting 10-3
■PDF
■RTF
■MHTML
10.4 Reports for Access Manager
Access Manager Reports are classified based on functional area. For example, Access
Policy Reports, Attestation, Request and Approval Reports and Password Policy
Reports are available. (It is no longer named Operational and Historical.) Oracle
Access Manager Reports are classified into the following categories based on their
functional areas:
■Account Management Reports
■Authentication Reports
■Errors and Exceptions
10.4.1 Account Management Reports
The Accounts_Locked_Out Report is the account management report that allows
administrators to view details about accounts that have been locked out.
10.4.2 Authentication Reports
Authentication reports allow administrators to view details regarding user
authentications. They include:
■Authentication Statistics Report
■AuthenticationFromIPByUser
■AuthenticationPerIP
■AuthenticationStatisticsPerServer Report
10.4.2.1 Authentication Statistics Report
This report contains details regarding failed and successful authentications.
Table 10–1 Accounts_Locked_Out Report Fields
Field Description
User ID Identifier of the locked out user
Timestamp Time stamp of the lockout
Component/Application Name Component from which the user has been locked out
Event Details Additional information
Table 10–2 Authentication_statistics Report Fields
Field Description
Failure Failed (yes) or successful (no) authentication
Userid Identifier of the user
Number of Events Number of authentication events
Reports for Access Manager
10-4 Administrator's Guide for Oracle Access Management
10.4.2.2 AuthenticationFromIPByUser
This report contains details regarding failed and successful authentications from a
particular IP address.
10.4.2.3 AuthenticationPerIP
This report contains details regarding failed and successful authentications from this
IP address.
10.4.2.4 AuthenticationStatisticsPerServer Report
This report contains details regarding failed and successful authentications from a
particular server instance.
10.4.3 Errors and Exceptions
Error and exception reports allow administrators to view errors and exceptions logged
during the authentication process. They include:
■All Errors and Exceptions
■Authentication Failures
■User Activities
■Authentication History
■Authorization History
■Multiple Logins From Same IP
10.4.3.1 All Errors and Exceptions
This report contains details regarding errors and exceptions encountered during
runtime.
Table 10–3 AuthenticationFromIPByUser Report Fields
Field Description
IP Address IP address of the client
Distinct User Count Number of distinct users
Total Attempts Number of authentication attempts from this IP address
Users List of users attempting authentication from this IP address
Table 10–4 AuthenticationPerIP Report Fields
Field Description
IP Address IP address of the server
Distinct Users Number of users authenticated
Total Number of Attempts Number of authentication attempts (successful and failed)
Table 10–5 AuthenticationStatisticsPerServer Report Fields
Field Description
Server Instance Name Identifier of the server instance
Success Count Number of successful authentications
Failure Count Number of failed authentications
Reports for Access Manager
Reporting 10-5
10.4.3.2 Authentication Failures
This report contains details regarding failed and successful authentications.
10.4.3.3 User Activities
There are no fields to define in this report.
10.4.3.4 Authentication History
This report contains details regarding failed and successful authentications.
10.4.3.5 Authorization History
This report contains details regarding failed and successful authorizations.
Table 10–6 All Errors and Exceptions Report Fields
Field Description
User ID Identifier of the locked out user
Timestamp Time stamp of the lockout
Component/Application Name Component from which the user has been locked out
Client IP Address IP address of the client
Message Event The error or exception
Event Details Information regarding the error or exception
Table 10–7 Authentication Failures Report Fields
Field Description
User ID Identifier of the locked out user
Timestamp Time stamp of the lockout
Component/Application Name Component from which the user has been locked out
Client IP Address IP address of the client
Authentication Method Authentication method
Message Event Details Message regarding the failed authentication
Authorization_Failures Authorization failure
Table 10–8 Authentication History Report Fields
Field Description
User ID Identifier of the locked out user
Timestamp Time stamp of the lockout
Component/Application Name Component from which the user has been locked out
Client IP Address IP address of the client
Authentication Method Authentication method
Message Event Details Message regarding the failed authentication
Authorization_Failures Authorization failure
Creating Reports Using Third-Party Software
10-6 Administrator's Guide for Oracle Access Management
10.4.3.6 Multiple Logins From Same IP
This report contains details regarding multiple logins from the same IP address.
10.5 Creating Reports Using Third-Party Software
Access Manager supports the creation of reports by using third-party tools such as
Crystal Reports. To learn how to create reports by using third-party software, see the
third-party software documentation. Additional information on the audit schema and
creating custom reports can be found in the Oracle Fusion Middleware Application
Security Guide.
Table 10–9 Authorization History Report Fields
Field Description
User ID Identifier of the locked out user
Timestamp Time stamp of the lockout
Component/Application Name Component from which the user has been locked out
Client IP Address IP address of the client
Authentication Method Authentication method
Message Event Details Message regarding the failed authentication
Authorization_Failures Authorization failure
Table 10–10 Multiple Logins From Same IP Report Fields
Field Description
IP Address IP address
Usernames Used Identifiers of users
11
Monitoring Performance and Health 11-1
11
Monitoring Performance and Health
[12]
Monitoring performance refers to observing (viewing) performance metrics to make
yourself aware of the state of specific components of Oracle Access Management.
Monitoring health allows perimeter devices to check the health of an Access Manager
server instance by hitting the heartbeat URL of the Managed Server.
This chapter contains the following sections on monitoring Oracle Access
Management performance and Access Manager health.
■Introduction to Performance Monitoring
■Monitoring Server Metrics Using Oracle Access Management Console
■Monitoring SSO Agent Metrics Using Oracle Access Management Console
■Introduction to OAM Proxy Metrics and Tuning
■Monitoring Metrics Using the DMS Console
■Monitoring the Health of an Access Manager Server
11.1 Introduction to Performance Monitoring
Component performance metrics can be collected in memory during the completion of
particular events. These metrics are kept only in memory so there are several
mechanisms to extract and display them including (but not limited to) Oracle
Enterprise Manager Fusion Middleware Control (FMW), the Oracle Dynamic
Monitoring Service (DMS) and the Oracle Process Manager and Notification Server
(OPMN).
■FMW Control is a Web browser-based, graphical user interface that offers
monitoring options. See Chapter 12, "Monitoring Performance and Logs with
Fusion Middleware Control" for details.
■DMS uses the DMS Spy Servlet to provide access to DMS metric data from a web
browser. Information is categorized by Noun Types; for Oracle Access
Management the prefix is OAMS.OAM_. See Monitoring Metrics Using the DMS
Console.
■dmsdump is provided by DMS to take metrics from the servers based on
definitions in a dms configuration file. There are many OAM metrics exposed
when dms dumps are generated. See the Oracle Fusion Middleware Performance and
Tuning Guide for more details.
See Also:
■Chapter 12 if you are using Oracle Enterprise Manager Fusion
Middleware Control
Monitoring Server Metrics Using Oracle Access Management Console
11-2 Administrator's Guide for Oracle Access Management
■OPMN provides access to metrics using dmsdump. See the Oracle Fusion
Middleware Performance and Tuning Guide for more details.
11.2 Monitoring Server Metrics Using Oracle Access Management
Console
Users with valid Oracle Access Management Administrator credentials can log into
the Oracle Access Management Console and monitor various performance metrics.
This section provides the following topics:
■Monitoring Server Instance Performance
■Reviewing Server Metrics
11.2.1 Monitoring Server Instance Performance
Users with valid Oracle Access Management Administrator credentials can monitor
performance for Access Manager using the Monitoring command on the Actions menu
under the System Configuration tab using the Oracle Access Management Console.
See Section 2.4, "Understanding the Oracle Access Management Console" for details.
Before you begin, the OAM Server must be running.
1. From the Oracle Access Management Console, click Server Instances and the
desired server instance.
2. Server Instance:
a. From the Actions menu in the navigation tree, click Monitor Menu.
b. On the Monitor page, click the desired subtab to view results for the server
instance:
Server Processes Overview
Session Operations
Server Operations
WebGates
c. Proceed to "Reviewing Server Metrics."
3. See also, "Introduction to OAM Proxy Metrics and Tuning" on page 11-10.
11.2.2 Reviewing Server Metrics
This topic provides a look at the Server metrics available through the Monitor option
from the Server Instances tab in the Configuration section of the console. Figure 11–1
shows the Server Processes page.
Monitoring Server Metrics Using Oracle Access Management Console
Monitoring Performance and Health 11-3
Figure 11–1 Server Processes Overview Page
Server Processes Overview provides the following OAM Server events, organized in
individual columns on the tab.
Figure 11–2 shows the Session Operations tab.
Table 11–1 OAM Server Metrics: Server Processes Overview Tab
Server Metric Columns
Authorization Process
Authorization Requests
Authentication Process Failure
Authentication Process Success
Pre Authentication Process Failure
Pre Authentication Process Success
Monitoring Server Metrics Using Oracle Access Management Console
11-4 Administrator's Guide for Oracle Access Management
Figure 11–2 OAM Server Metrics: Session Operations Monitoring Page
OAM Server Session Operations metrics include:
Figure 11–3 shows the Server Operations tab.
Table 11–2 OAM Server Metrics: Session Operations
Session Operations
Check Session Valid
Check Session Valid Failure
Check Session Valid Success
Create Session
Create Session Failure
Create Session Success
Destroy Session
Destroy Session Failure
Destroy Session Success
Delete Client Session
Delete Client Session Failure
Monitoring Server Metrics Using Oracle Access Management Console
Monitoring Performance and Health 11-5
Figure 11–3 OAM Server Metrics: Server Operations Tab
OAM Server Operations metrics include those in Table 11–3.
Figure 11–4 shows the OAM Server Metrics: WebGates tab with all available metrics
showing.
Table 11–3 OAM Server Metrics: Server Operations Tab
OAM Server: Operations Metrics
Authentication Policy Response Failure
Authentication Policy Response Success
Authentication Scheme Response Failure
Authentication Scheme Response Success
Authentication Failure
Authentication Failure Responses
Authentication Policy Response
Authentication Requests
Authentication Scheme Response
Authorization Failure
Authorization Failure
Authorization Process Failure
Authorization Process Success
Monitoring SSO Agent Metrics Using Oracle Access Management Console
11-6 Administrator's Guide for Oracle Access Management
Figure 11–4 OAM Server Metrics: WebGates Tab
WebGate performance metrics include:
■Agent Name
■Agent Status
■Vers ion
11.3 Monitoring SSO Agent Metrics Using Oracle Access Management
Console
This section describes how to review metrics for various components and how to
determine whether tuning is needed. Users with valid Oracle Access Management
Administrator credentials can use the following procedure to display various SSO
Agent performance metrics using the Oracle Access Management Console.
Before you begin, the server and agent must be running.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Agents.
3. In the Search SSO Agents page, select the desired agent type tab:
■WebGates
■OSSO Agents
■OpenSSO Agents
This Agent can only be monitored using OpenSSO Proxy behavior with
respect to Agent Requests. See Monitoring OpenSSO Proxy Metrics.
4. Search for the agent you want to monitor.
5. In the Search Results table, highlight the desired agent SerialNumber and from the
Actions menu select Monitor.
6. Proceed as needed.
■Reviewing WebGate Metrics
■Reviewing OSSO Agent Metrics
11.3.1 Reviewing WebGate Metrics
WebGate metrics are organized across the following tabs:
■Connectivity
■Operations Overview
Monitoring SSO Agent Metrics Using Oracle Access Management Console
Monitoring Performance and Health 11-7
■Operations Detail
■Information
Following figures illustrate detached tables for one Webgate with all possible metrics
displayed for each:
■Figure 11–5, "Webgate Metrics: Connectivity Table"
■Figure 11–6, "Webgate Metrics: Operations Overview Table"
■Figure 11–7, "Webgate Metrics: Operations Detail Table"
■Figure 11–8, "Webgate Metrics: Detached Information Table"
Figure 11–5 Webgate Metrics: Connectivity Table
Figure 11–6 Webgate Metrics: Operations Overview Table
Figure 11–7 Webgate Metrics: Operations Detail Table
See Also: Oracle Fusion Middleware Performance and Tuning
Guide
Monitoring SSO Agent Metrics Using Oracle Access Management Console
11-8 Administrator's Guide for Oracle Access Management
Figure 11–8 Webgate Metrics: Detached Information Table
11.3.2 Reviewing OSSO Agent Metrics
When you have an OSSO Agent selected OSSO Agents Search Results table and
choose Monitor from the table's Actions menu, the following metrics pages are
available:
■Figure 11–10, "OSSO Agent Monitoring Process Overview Table"
■Figure 11–11, "OSSO Agent Operation Details Table"
Figure 11–9 OSSO Agent Monitoring Page with Operation Details
Figure 11–10 illustrates the OSSO Agent Monitoring Process Overview table.
Monitoring SSO Agent Metrics Using Oracle Access Management Console
Monitoring Performance and Health 11-9
Figure 11–10 OSSO Agent Monitoring Process Overview Table
Figure 11–11 illustrates the OSSO Agent Operation Details table.
Figure 11–11 OSSO Agent Operation Details Table
Introduction to OAM Proxy Metrics and Tuning
11-10 Administrator's Guide for Oracle Access Management
11.4 Introduction to OAM Proxy Metrics and Tuning
This section provides the following topics:
■About OAM Proxy Metrics
■OAM Proxy Server Tuning Parameters
11.4.1 About OAM Proxy Metrics
Throughput refers to the number of requests processed per second. Latency refers to
the time required to process a particular request. There is less than a 20% latency
increase with the introduction of a proxy between WebGate and OAM Server.
Table 11–4 lists the various OAM Proxy metrics available.
11.4.2 OAM Proxy Server Tuning Parameters
Performance of the OAM Proxy can be tuned by changing its configuration through
the Java EE container Administration Console.
Table 11–5 provides the tuning parameters for the OAM Proxy.
See Also:
■"OpenSSO Proxy Events and Metrics: Server" on page 11-13
■Oracle Fusion Middleware Performance and Tuning Guide
Table 11–4 OAM Proxy Metrics
Metric Description
handshakes.active Number of active threads doing handshake
handshakes.avg Average time spent performing initial handshake
handshakes.completed Number of times an initial handshake has been executed
handshakes.maxTime Maximum time spent performing initial handshake
handshakes.minTime Minimum time spent performing initial handshake
handshakes.time Total time spent performing initial handshake
failedHandshakes.count Count of failed handshakes
peerCompatibilityFailures.c
ount
Count of how many Peer Compatibility Check Failures have
happened
openSecurityMode.count Count of how many Open Security Mode handshakes have
happened
simpleSecurityMode.count Count of how many Simple Security mode handshakes have
happened
SSLSecurityMode.count Count of how many SSL Security Mode handshakes have
happened
negotiateSecurityMode.acti
ve
Number of active threads doing security mode negotiation
Note: Both the Java EE container Administrator and the Oracle
Access Management Administrator can tune performance using the
Java EE container Administration Console, which is outside the scope
of this book.
Monitoring Metrics Using the DMS Console
Monitoring Performance and Health 11-11
11.5 Monitoring Metrics Using the DMS Console
Oracle Access Management uses the Oracle Dynamic Monitoring Systems (DMS) to
measure application-specific performance information for OAM Servers and registered
Agents. The metrics can be used to monitor the time spent in a particular area, or track
particular occurrences or state changes. To access the DMS console, type the following
URL in a browser window and log in with your Oracle Access Management
Administrator credentials.
http:// <example_AdminServer:Port/dms/Spy
Once logged into the DMS console you can monitor metrics as discussed in the
following sections.
■Monitoring OAM Metrics
■Monitoring Coherence Caches
■Monitoring OpenSSO Proxy Metrics
11.5.1 Monitoring OAM Metrics
This section describes how to access metrics regarding OAM. In the DMS Metric
Tables panel, the OAM metrics can be reviewed as illustrated in Figure 11–12. Click the
desired metric from those listed to view the results on the right-side of the console.
Table 11–5 OAM Proxy Tuning Parameters
Purpose Parameter Type Value Description
Denial of
Service
Attacks
ConnectionValidationInterval Integer 120 The time interval in seconds for
validating the connections
periodically for denial of service
attacks
BacklogQueue Integer 50 Maximum length of backlog
queue
MaxNAPHandShakeTime Integer 100 The maximum time in
milliseconds within which the
client should complete the NAP
handshake with client. If NAP
handshake over a connection is
not completed within this time,
the connection will be marked as
malicious
Monitoring Metrics Using the DMS Console
11-12 Administrator's Guide for Oracle Access Management
Figure 11–12 OAM Metrics Table
11.5.2 Monitoring Coherence Caches
This section describes how to access information regarding the Coherence caches used
in OAM. OAM uses Coherence as a distributed cache to perform various functions.
Coherence provides management and monitoring support through management
mbeans. Beginning with this 11.1.2.2.3 release, OAM exposes Coherence metrics as
DMS metrics. Thus, monitoring information can be accessed using the DMS console.
In the DMS Metric Tables panel, the Coherence metrics for each of the caches is
available for review under the Weblogic Metrics section as illustrated in Figure 11–13.
The metric table links in the section provide details about the cache operations.
Figure 11–13 Weblogic Metrics
11.5.3 Monitoring OpenSSO Proxy Metrics
This section provides the following topics:
■Reviewing OpenSSO Metrics
■OpenSSO Proxy Events and Metrics: Server
■OpenSSO Proxy Metrics: Agent
Monitoring Metrics Using the DMS Console
Monitoring Performance and Health 11-13
11.5.3.1 Reviewing OpenSSO Metrics
User with valid Oracle Access Management Administrator credentials can use the
procedure here to view OpenSSO Proxy metrics in the DMS console.
Before you begin the procedure to access the DMS console, the OAM Server must be
running.
1. In a browser window, go to the DMS Console using the following URL:
http://<example_AdminServer:Port/dms/Spy
2. Log in with your Oracle Access Management Administrator credentials.
3. OpenSSO Agent Metrics: In the DMS Metric Tables, click OAMS.OAM_
Server.OPENSSO_Agents.
4. OpenSSO Proxy Metrics: In the DMS Metric Tables, click OAMS.OAM_
OpenSSOProxy and view the results on the right side of the console.
11.5.3.2 OpenSSO Proxy Events and Metrics: Server
Throughput refers to the number of requests processed per second. Latency refers to
the time required to process a particular request. The Events that can be monitored are
described in Table 11–6.
Table 11–7 lists the various OpenSSO Proxy metrics available for the named server.
Table 11–6 OpenSSO Proxy Server Events
Event Description
Naming Service Request This request is for naming lookups. One can monitor response time taken by the
OpenSSO Proxy in servicing this request
Agent Authentication Process Agent Authentication has been captured in two phases:
■AgentAuthentication_Login and AgentAuthentication_SubmitRequirements
phase. The second phase refers to the phase after the credentials are
submitted by the OpenSSO Agent for authentication
■The second phase refers to the phase after the credentials are submitted by
the OpenSSO Agent for authentication.
Agent Session Validation Agent Session Validation
User Authentication This event is captured for Client SDK's only. One can monitor response time taken
to authenticate client SDK's through this diagnostic event
User Session Validation Time taken to validate User Session
User Authorization Time taken for authorization as per the configured policy for the given resource
Table 11–7 OpenSSO Proxy Metrics: Server
Metric Description
AgentAuthentication_Login Response time details for Authentication requests during login phase sent by the
Agent to authenticate
AgentAuthentication_LoginFailures Count of how many Agent Authentication requests during login phase have
failed.
AgentAuthentication_SubmitRequirements Response time details for Authentication requests during Submit Requirements
phase send by the Agent to authenticate
AgentAuthentication_
SubmitRequirementsFailures
Count of how many Agent Authentication requests during Submit Requirements
phase have failed
NamingServiceRequest Response time details for Naming Service Request operations
NamingServiceRequestFailures Count of how many Naming Service Request operations have failed
UserAuthentication_SDK Response time details for User Authentication requests
Monitoring the Health of an Access Manager Server
11-14 Administrator's Guide for Oracle Access Management
11.5.3.3 OpenSSO Proxy Metrics: Agent
Table 11–8 lists the various OpenSSO Proxy metrics available for each OpenSSO Agent.
11.6 Monitoring the Health of an Access Manager Server
Access Manager Services are business critical and must always be available to control
user access to an organization’s protected web services and applications. Because
hardware, network connectivity issues and other failures can happen, HeartBeat
monitoring can be leveraged by Load Balancers to ensure user traffic is routed to
healthy OAM Servers. For example, when there is a firewall installed between a User
Agent or WebGate (10 or 11g) and the 10g or 11g Access Manager server, perimeter
devices can check availability of the Access Manager server (its health) by hitting its
HeartBeat URL. The following sections contain details.
■Understanding WebGate and Access Manager Communications
■Monitoring Access Manager Server Health
UserAuthentication_SDKFailures Count of how many User authentication Requests have failed
UserAuthorization Response time details for User Authorization operations
UserAuthorizationFailures Count of how many user authorization operations have failed
ValidateAgentSession Response time details for Agent Session Validation operation
ValidateAgentSessionFailures Count of how many agent session validation operations have failed
ValidateUserSession Response time details for User Session Validation operation
ValidateUserSessionFailures Count of how many User session validation operations have failed.
Table 11–8 OpenSSO Proxy Metrics: Agent
Metric Description
AgentAuthentication_
SubmitRequirements
Response time details for Authentication requests during Submit
Requirements phase collected per Agent
AgentCacheMode Specifies the cache mode for the client policy evaluator. Values can be:
subtree or self
AgentFilterMode Specifies how the agent filters requests to protected web applications.
The global value functions as a default, and applies for protected
applications that do not have their own filter settings
AgentHostName The host name of OpenSSO Agent
AgentIPAddress The IP Address of OpenSSO Agent
AgentMappingMode Specifies the mechanism used to determine the user ID
AgentState The state of OpenSSO Agent: enabled or disabled.
UserAttributeName Specifies the data store attribute that contains the user ID
UserAuthorization Response time details for User Authorization operations collected per
Agent
UserIdentity Specifies the session property name for the authenticated user's ID.
Default is 'UserToken'
ValidateAgentSession Response time details for Agent Session Validation operation collected
per Agent
agentType The type of OpenSSO agent: J2EE or Web Agent
Table 11–7 (Cont.) OpenSSO Proxy Metrics: Server
Metric Description
Monitoring the Health of an Access Manager Server
Monitoring Performance and Health 11-15
11.6.1 Understanding WebGate and Access Manager Communications
When deploying a network firewall between a WebGate and Access Manager server,
the WebGate communicates using the OAP protocol by creating a TCP socket
connection with Access Manager to establish a message channel. The WebGate uses
the message channel to send different OAP messages necessary to serve the resource
requests (isprotected, isauthorized, and the like). Now, consider a situation in which
the WebGate/Oracle HTTP Server is idle. In this case, the WebGate has received no
resource request and will not send any messages to Access Manager for authentication
or authorization; there will also not be any read/write activity on the socket
connection.
The firewall determines this connection is idle after 30-40 minutes of inactivity
(depending on its configuration) and terminates the socket connection but does not
inform/notify the WebGate or Access Manager server. In this case, when a request for
a resource arrives at the WebGate and it sends a OAP message to the Access Manager
server, it uses the existing connection and waits for a reply. Because the connection
was dropped by the firewall, the WebGate does not receive any reply; so it waits for
the TCP timeout. Following the TCP timeout, WebGate understands the message
channel is of no use and starts the process to get a new message channel. TCP timeout
is OS specific and may vary from several minutes to hours which makes the WebGate
unable to process user requests.
11.6.2 Monitoring Access Manager Server Health
The OAM monitoring model allows Web Tier components (load balancers) to ping an
OAM Managed Server's HeartBeat endpoint at a scheduled interval over HTTP(S).
This allows Web Tier components to route incoming HTTP traffic away from
unhealthy OAM Managed Server(s). Every OAM Managed Server exposes this
HeartBeat URL:
Scheme://ManagedServerHost:ManagedServerPort/oam/server/HeartBeat
In this URL, the following is true:
■scheme = https | http
■ManagedServerHost = Host name of the Access Manager WLS Managed Server
■ManagedServerPort = Port used by the Access Manager WLS Managed Server
The HeartBeat URL works as follows:
1. The Web Tier components will send an HTTP request to the HeartBeat endpoint of
the Access Manager Managed Server.
2. The Access Manager Managed Server will then do the following:
■Verify Id Store Connectivity
■Verify Policy Store Connectivity
■Verify the Credential Collector URLs are reachable
■Sanity check the working of the Coherence Layer
■Check for NAP connectivity
Note: The
setKeepAlive
WebGate parameter ensures that load
balancers do not drop the OAP connection. See User-Defined
WebGate Parameters for details.
Monitoring the Health of an Access Manager Server
11-16 Administrator's Guide for Oracle Access Management
If the above tests succeed, the Access Manager server is considered to be healthy
and a HTTP 200 response is sent to the Load Balancer. Any other HTTP Status
Code value signifies that the Access Manager Managed Server is not healthy.
3. When multiple Access Manager Managed Servers are present in the deployment,
the Web Tier component will repeat this for each OAM Managed Server.
Note: Neither the health status test results or check results can be
communicated in the body of the HTTP Response. A successful
heartbeat check will return the HTTP code 200.
12
Monitoring Performance and Logs with Fusion Middleware Control 12-1
12
Monitoring Performance and Logs with Fusion
Middleware Control
Live, dynamic performance metrics can be viewed in Fusion Middleware Control. This
chapter describes how to monitor performance and log messages for Access Manager
and Security Token Service using Oracle Fusion Middleware Control. This chapter
focuses on general tasks that Administrators can perform from Fusion Middleware
Control, which does not replace details in the Oracle Fusion Middleware
Administrator's Guide.
This chapter includes the following topics.
■Introduction to Fusion Middleware Control
■Logging In to and Out of Fusion Middleware Control
■Displaying Menus and Pages in Fusion Middleware Control
■Viewing Performance in Fusion Middleware Control
■Managing Log Level Changes in Fusion Middleware Control
■Managing Log File Configuration from Fusion Middleware Control
■Viewing Log Messages in Fusion Middleware Control
■Displaying MBeans in Fusion Middleware Control
12.1 Introduction to Fusion Middleware Control
Within Fusion Middleware Control, information is updated dynamically during live
sessions of Access Manager, Security Token Service, and other products.
Fusion Middleware Control organizes a wide variety of performance data and
administrative functions into distinct Web-based pages. This helps Administrators
easily locate the most important monitoring data and the most commonly used
administrative functions from a Web browser.
Note: Unless explicitly stated, information in this chapter is the same
for both services. There are no metrics in Oracle Fusion Middleware
Control for Identity Federation or Mobile and Social.
Logging In to and Out of Fusion Middleware Control
12-2 Administrator's Guide for Oracle Access Management
Oracle Access Management 11g is deployed as a Java EE application in a WebLogic
container. For high availability and failover, Oracle Access Management is typically
deployed in a WebLogic cluster environment.
A WebLogic Server domain can have multiple clusters. To provide monitoring and
performance statistics for all clustered components requires a composite target. This
target provides status and rolled-up load and response performance metrics for
member instances. In addition to the metrics exposed for Access Manager and Security
Token Service, generic performance metrics are also available for Java EE application
and composite Java EE applications.
Fusion Middleware Control must be deployed with Oracle Access Management on the
WebLogic Administration Server, as illustrated in Figure 12–1 (and described in the
Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management).
Figure 12–1 Fusion Middleware Control (AS-Control) Deployment Architecture
Using Fusion Middleware Control for targets is supported through the Oracle
Dynamic Monitoring Systems instrumentation within Oracle Access Management.
This instrumentation is used to provide:
■Performance overview and drill down
■Log message searches and dynamic log level changes
■Routing topology overview
■Mbean browser
■Component- and cluster-level metrics for Access Manager with Security Token
Service
12.2 Logging In to and Out of Fusion Middleware Control
The Fusion Middleware Control Login page provides the usual fields for the User
Name and Password. The bottom of the Fusion Middleware Control Login page
provides topics that you can click for additional information. This section provides the
following topics:
Note: Enterprise Manager Grid Control is an independently licensed
product that provides additional capabilities not found in Fusion
Middleware Control (primarily, the ability to collect and maintain data
for historical purposes and trending).
Displaying Menus and Pages in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-3
■Logging In To Fusion Middleware Control
■Logging Out of Fusion Middleware Control
12.2.1 Logging In To Fusion Middleware Control
Only Fusion Middleware Control Administrators can perform this task.
1. In a browser window, enter the URL to Fusion Middleware Control. For example:
http://host.example.com:8888/em/
2. Expand a topic at the bottom of the Login page to learn about the enhanced user
experience or new features.
3. Log in as a Fusion Middleware Control Administrator.
4. Choose the farm containing Oracle Access Management, if needed.
5. Help: From the Farm Resource Center on the OAM Farm page, choose topics of
interest (or click Help in the upper-right corner of the page) to get more
information.
6. Proceed to any topic in this chapter for viewing and configuration details.
12.2.2 Logging Out of Fusion Middleware Control
You can use the following procedure to log out of Fusion Middleware Control.
1. Click the Log Out link in the upper-right corner of Fusion Middleware Control.
2. Close the browser window.
12.3 Displaying Menus and Pages in Fusion Middleware Control
This section provides the following topics for Access Manager and Security Token
Service:
■About the Farm Page in Fusion Middleware Control
■About Context Menus and Pages in Fusion Middleware Control
■Displaying Context Menus and Target Details in Fusion Middleware Control
12.3.1 About the Farm Page in Fusion Middleware Control
Figure 12–2 illustrates the OAM Farm page in Fusion Middleware Control. Each Farm
page includes similar information. The Farm Resource Center provides immediate
access to online information.
See Also: Oracle Fusion Middleware Administrator's Guide for details
about getting started using Fusion Middleware Control
See Also: Oracle Fusion Middleware Administrator's Guide for details
about getting started using Fusion Middleware Control
Displaying Menus and Pages in Fusion Middleware Control
12-4 Administrator's Guide for Oracle Access Management
Figure 12–2 OAM Farm Page in Fusion Middleware Control
Sections on the Farm page are described in Table 12–1.
The navigation tree on the left side of the page, like the one in Figure 12–3, enables you
to choose a specific instance (target) on which to operate regardless of the page you are
currently viewing. Target names in your environment will be different.
Table 12–1 Farm Page Sections
Farm Page Sections Description
Deployments Within the farm, this section displays the Status and Target of each Internal Application
within the Application Deployment.
Clicking any link in the Deployments section (or in the navigation tree) displays a page
containing more information.
Fusion Middleware Within the farm, this section displays the status, host, and CPU usage for server instances
in the:
■WebLogic Server domain
■Identity and Access
Clicking any link on the page (or in the navigation tree) displays a page containing a more
detailed summary.
Farm Resource Center Provides a wealth of online information in the following categories:
■Information that is useful before you begin using Fusion Middleware Control
■Administrator tasks using Fusion Middleware Control
■Other resources
Clicking any link in the resource center displays information on the chosen subject. With a
wealth of information online, these details are not repeated in this book.
Displaying Menus and Pages in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-5
Figure 12–3 Farm Navigation Tree in Fusion Middleware Control
For more information, see "Logging In To Fusion Middleware Control".
12.3.2 About Context Menus and Pages in Fusion Middleware Control
For Oracle Access Management, Farm details in Fusion Middleware Control are
divided into the following nodes within the navigation tree:
■Application Deployments
■Internal Applications (includes logout page and other details for the OAM
AdminServer and OAM Server instances)
■WebLogic Server domains (WebLogic Server details, including the OAM Farm)
■Identity and Access (includes OAN Cluster or individual OAM Server instances)
Clicking a node in the navigation tree displays an information page with individual
links and a description of the Target, Type, and Full Name, as shown in Figure 12–4 for
Application Deployments.
Figure 12–4 Node Information Page in Fusion Middleware Control
Clicking an instance (target) name (from either the navigation tree or a page), displays
a context menu and a more detailed summary page. The Internal Application target is
highlighted in the navigation tree and a page of the same name is displayed on the
right. The context menu is available beneath the target name at the top of the page, as
shown in Figure 12–5.
See Also: "Displaying Menus and Pages in Fusion Middleware
Control" on page 12-3
Displaying Menus and Pages in Fusion Middleware Control
12-6 Administrator's Guide for Oracle Access Management
Figure 12–5 Application Deployment Summary for the Selected Internal Application
The Application Deployment menu is shown in Figure 12–6.
Figure 12–6 Application Deployment Menu
WebLogic Server domain: The WebLogic Server domain page is shown in Figure 12–7
with the corresponding menu displayed. The Oracle WebLogic Server domain
Displaying Menus and Pages in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-7
Resource Center, with links to online documentation, is visible in the bottom-left
corner. This page more closely resembles the Farm landing page.
Figure 12–7 WebLogic Server Domain Summary with Context Menu Exposed
Selecting a target name within the WebLogic Server domain node displays a target
summary page that more closely resembles the Application Deployment page in
Figure 12–5.
For more information, see "Displaying Context Menus and Target Details in Fusion
Middleware Control".
12.3.3 Displaying Context Menus and Target Details in Fusion Middleware Control
Fusion Middleware Control Administrators can use the following procedure to view
context menus and target pages.
See Also: "Viewing Performance in Fusion Middleware Control" on
page 12-8 for information about the Identity and Access node and
related pages.
Note: From the Farm Resource Center on the OAM Farm page,
choose topics of interest (or click Help in the upper-right corner of the
page) to get more information.
See Also: "About Context Menus and Pages in Fusion Middleware
Control" on page 12-5
Viewing Performance in Fusion Middleware Control
12-8 Administrator's Guide for Oracle Access Management
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the Farm containing Oracle Access Management, if needed.
3. Information Pages: From the navigation tree, click one of the following to display
the related information page:
■Application Deployments
■WebLogic Server domain
■Identity and Access
4. Menus and Summary Pages: Click an instance name (in either the navigation tree
or the related page) to display a summary page and menu (Figure 12–5 and
Figure 12–6).
5. Cluster or Server Pages: See "Viewing Performance in Fusion Middleware
Control".
12.4 Viewing Performance in Fusion Middleware Control
Fusion Middleware Control provides Administrators with:
■A cluster-wide view of performance for Access Manager with Security Token
Service
■A per-server drill-down of key performance metrics
■The ability to quickly add or remove performance metrics
Using Fusion Middleware Control, you can view performance metrics for live sessions
in a variety of formats. Table 12–2 summarizes the pages for selected nodes and target
instances.
This section provides the following topics:
Table 12–2 Resulting Pages for Selected Nodes and Targets
Node Target
Information
Summary Page
Performance
Overview
Performance
Summary
w/Metrics
Application Deployment
Internal Applications ...AdminServer
oamsso_logout(11.1.1.3.0) AdminServer
oamsso_logout(11.1.1.3.0) oam_server
Yes
Yes
Yes
No
No
No
Yes
Yes
Yes
WebLogic Server domain
oam_bd (Cluster name)
AdminServer
oam_server
Yes
Yes
Yes
No
No
No
No
Yes
Yes
Identity and Access
OAM
(Cluster)
oam_server
(Server)
No
No
Yes
Yes
Yes
Yes
Note: Security Token Service performance is included with relevant
OAM Cluster and Server pages.
Viewing Performance in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-9
■About Performance Overview Pages in Fusion Middleware Control
■About the Metrics Palette and the Performance Summary Page
■Displaying Performance Metrics in Fusion Middleware Control
■Displaying Component-Specific Performance Details
12.4.1 About Performance Overview Pages in Fusion Middleware Control
The Fusion Middleware Control Performance Overview can be used to reflect
WebLogic cluster information down to specific performance metrics for individual
Cluster and Server targets.
Cluster Page: The top node within Identity and Access leads to a page for the OAM
Cluster Deployment, which includes a Performance Overview. For Figure 12–8, the
Cluster is selected in the navigation tree, beneath the Identity and Access node.
Figure 12–8 illustrates the Cluster Deployments and Performance Overview sections.
This page includes a table for Token Issuance and Token Validations.
Figure 12–8 Cluster Page
OAM Server Pages: Selecting an OAM Server target name from the navigation tree (or
the open page), displays a Performance Overview for the target. At the top of the
OAM Server page, a summary of Key Metrics for the server instances appears instead
of the Cluster Deployment section. Figure 12–9 illustrates the OAM Server instance
Key Metrics, which include Token Issuance and Token Validations per second. The
Token Validation success rate is included.
Viewing Performance in Fusion Middleware Control
12-10 Administrator's Guide for Oracle Access Management
Figure 12–9 Key Metrics for Server Page
Table 12–3 describes the elements of the Performance Overview for Clusters and OAM
Server instances in Fusion Middleware Control. There are only a few differences.
Table 12–3 Summary of Performance Overviews in Fusion Middleware Control
Section or Column Name Description
Cluster Menu Dynamic context menus provide functions related to the selected target (also available
when you right-click a target in the navigation tree). This menu is available for the
selected Cluster.
The Component Performance command enables you to choose between displaying
Access Manager or Security Token Service metrics.
See Also: "Access Manager Component Pages" and "Security Token Service Component
Pages".
Deployments, OAM Cluster pages This section appears only on OAM Cluster pages. It describes the status of each instance
in the cluster. The following information is included:
■Instance Name
■Status
■Authentications
■Authorizations
Instance Name This column includes the name of each OAM Server instance in the cluster. For
example:
OAM_server_name
Status This column identifies the status of each OAM Server instance in the cluster with either
a:
■Green Up Arrow (running)
■Red Down Arrow (not running)
Authentications Authentications columns identify:
■Authentications/sec: The number of authentications per second for each OAM
Server instance in the cluster
■Success Rate (% of Authentications Successful): A numeric value representing the
percentage of successful authentications for each OAM Server instance in the
cluster
Viewing Performance in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-11
Authorizations This column identifies the number of authorizations per second for each OAM Server
instance in the cluster.
Authorizations columns identify:
■Authorizations/sec: The number of authorizations per second for each OAM
Server instance in the cluster
■Success Rate (% of Authorizations Successful): A numeric value representing the
percentage of successful authorizations for each OAM Server instance in the
cluster
Server Instance Menu Dynamic context menus provide functions related to the selected target (also available
when you right-click a target in the navigation tree). This menu is available for the
selected server instance.
The Component Performance command enables you to choose between displaying
specific Access Manager or Security Token Service metrics.
See Also: "Access Manager Component Pages" and "Security Token Service Component
Pages".
Key Metrics, OAM Server Page This table provides a summary of statistics for only the selected OAM Server instance.
Key metrics include details for both Access Manager and Security Token Service:
■Authentications/sec, Average Authentication Latency (ms), and Success ratio
■Authorizations/sec, Average Authorization Latency (ms), and Success ratio
■Token Issuances/sec, Average Issuance Latency (ms), and Success ratio
■Token Validations/sec, Average Validation Latency (ms), and Success ratio
Performance Overview, OAM Cluster
and OAM Server Pages
This section provides a graphic representations of Access Manager authentication and
authorization operations and Security Token Service Token Issuance and Token
Validation operations. Metrics in the Performance Overview are not configurable. The
Metrics Palette is available for only the Performance Summary.
Whether you have an OAM Cluster or OAM Server instance selected, the Performance
Overview includes:
■Authentications/sec and Authorizations/sec
■Token Issuances/sec and Token Validations/sec
Within each table:
■Coordinates along the horizontal axis (the x axis) identify the time period.
■Coordinates along the vertical axis (the y axis) identify the number of named
transactions that occured during the time period.
Table 12–3 (Cont.) Summary of Performance Overviews in Fusion Middleware Control
Section or Column Name Description
Viewing Performance in Fusion Middleware Control
12-12 Administrator's Guide for Oracle Access Management
12.4.1.1 Access Manager Component Pages
The Component Performance command on both the Cluster and Server instance
menus enables you to display Access Manager-specific metrics.
Cluster component-specific metrics are aggregated across the cluster, illustrated in
Figure 12–10. Details follow in Table 12–4.
Figure 12–10 Aggregated Access Manager Component Metrics for the Cluster
Figure 12–11 illustrates the Access Manager component metrics for a single OAM
Server instance.
Figure 12–11 Access Manager Component Metrics for a Single OAM Server Instance
Table View Click the Table View link on the bottom-right side of the Performance Overview to
display performance information in columns within a pop up window.
LDAP Servers, OAM Cluster and
OAM Server Pages
This section is available when either an OAM Cluster or a single OAM Server instance
is selected. It provides information for the default LDAP user identity store:
■LDAP operations/sec
■LDAP Latency (milliseconds)
■LDAP Success Rate
Application Domains, OAM Cluster
and OAM Server Pages
This section of the OAM Cluster and OAM Server pages provides information for all
Application Domains that were used during authentication and authorization
processing.
Columns in this section provide the:
■Application Domain Name: Each Application Domain that contains the
authentication and authorization policies used for a request.
■Authentications/sec, Authentications Latency (ms), Success Ratio (%) for each
Application Domain
■Authorizations/sec, Authorization Latency (ms), Success Ratio (%) for each
Application Domain
Table 12–3 (Cont.) Summary of Performance Overviews in Fusion Middleware Control
Section or Column Name Description
Viewing Performance in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-13
Table 12–4 describes the component-specific metrics for Access Manager.
12.4.1.2 Security Token Service Component Pages
The Component Performance command on both the Cluster and Server instance
menus enables you to display Security Token Service component-specific metrics.
Component-specific metrics are aggregated for the Cluster, as illustrated in
Figure 12–10.
Table 12–4 Access Manager Component Metrics
Access Manager Metrics Description
Access Manager Clients Based on your selection (Cluster or Server instance), this page provides
information for all active Access Clients in a cluster (or for the active Access
Clients of an individual OAM Server). Details include:
■Client ID
■Type
■Authentications
■Authorizations
Client ID Displays the name of the Agent, as defined in the Agent registration in the
Oracle Access Management Console. For example:
IAMSuiteAgent
Type Displays the Agent. type For example:
OAM Webgate
Authentications Authentications columns identify:
■Authentications/sec: The number of authentications per second for each
OAM Server instance in the cluster
■Latency (ms): The number of milliseconds the authentication was
delayed
■Success Rate (% ): A numeric value representing the percentage of
successful authentications for each OAM Server instance in the cluster
Authorizations Authorizations columns identify:
■Authorizations/sec: The number of authorizations per second for each
OAM Server instance in the cluster
■Latency (ms): The number of milliseconds the authorization was delayed
■Success Rate (%): A numeric value representing the percentage of
successful authorizations for each OAM Server instance in the cluster
Viewing Performance in Fusion Middleware Control
12-14 Administrator's Guide for Oracle Access Management
Figure 12–12 Aggregated STS Component Metrics for the Cluster
For each individual server instance, STS component-specific metrics are also available,
as illustrated in Figure 12–10.
Figure 12–13 STS Component Metrics for an Individual OAM Server Instance
Table 12–5 introduces the STS component specific metrics.
Table 12–5 STS Component-Specific Metrics
Security Token Service Metrics Description
Requestor Partners Statistics summary for either the selected OAM Server instance (or an
aggregated summary for the Cluster):
■Partner ID
■Token Issuances
■Token Validations
Selecting a Requestor Partner ID reveals Relying Party Details with
specific information for only the named partner.
Token Operations Metrics for STS Token Operations include:
■Token Type
■Token Issuances: Total Requests, Requests per second, Average
Issuance Latency (ms)
■Token Validations: Total Requests, Requests per second, Average
Issuance Latency (ms)
Viewing Performance in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-15
12.4.2 About the Metrics Palette and the Performance Summary Page
The Performance Summary command on the Cluster or Server menu displays metrics
charts for the selected target.
Figure 12–14 Performance Summary Command
On the Performance Summary page, a chart is displayed for each selected metric. An
OAM Server Performance Summary page. Figure 12–15 shows the Performance
Summary page with an open Metric Palette from which you can choose metrics to
chart. Stacked charts allow you to easily compare multiple metrics for the same time
frame, change the time frame to go back in time, or zoom in or out.
Figure 12–15 Performance Summary Page with Metric Palette
Table 12–6 describes the status and controls available on the Performance Summary
page.
Table 12–6 Status and Controls on Performance Summary Pages
Status or Control Description
Past n minutes Status is based on the specified time period, which can be adjusted using the slider.
All
n Minutes The specified time period, which can be adjusted using the slider.
Viewing Performance in Fusion Middleware Control
12-16 Administrator's Guide for Oracle Access Management
Slider The tool you use to adjust the time period.
Chart Set A list from which you can choose the set of saved charts to view.
Table 12–6 (Cont.) Status and Controls on Performance Summary Pages
Status or Control Description
Viewing Performance in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-17
12.4.3 Displaying Performance Metrics in Fusion Middleware Control
Fusion Middleware Control Administrators can use the following procedure to add or
change the metrics that are displayed in the Performance Summary.
View A menu that enables you to add a grid, save a chart, and order information on the page.
Overlay A menu that enables you to search for and view another instance of the same type and
compare this against the instance in the summary.
Metric Palette A listing from which you can select performance metrics to chart. Items unique to Access
Manager and Security Token Service are shown here.
Left: Metric Palette for the Cluster
Right: Metric Palette for a Single OAM Server
Table 12–6 (Cont.) Status and Controls on Performance Summary Pages
Status or Control Description
Viewing Performance in Fusion Middleware Control
12-18 Administrator's Guide for Oracle Access Management
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Performance Overview:
a. Expand the desired node and select a target. For example: Identity and Access.
Identity and Access
oam_server
b. Review the Performance Overview.
3. Performance Summary:
a. Select a target (Step 1).
b. From the context menu, select Performance Summary.
c. Review the Summary Page.
4. Changing Metrics:
a. From the Performance Summary page (Step 2), click the Show Metrics Palette
button.
b. From the Metrics Palette, expand nodes and check (or clear) boxes to add (or
remove) metrics from the summary.
c. Review the updated the Summary page.
d. Click Hide Metrics Palette when you finish.
5. Saving a Chart Set:
a. From the View menu on the Performance Summary page, click Save Chart
Set.
b. In the dialog box that appears, enter a unique name for this chart set and click
OK when the operation is confirmed.
c. Click Hide Metrics Palette when you finish.
d. Review the updated information on the Summary Page.
6. Adding an Overlay, Access Manager:
a. From the Overlay menu on the Performance Summary page, click Another
Oracle Access Manager.
b. In the Search and Select Targets dialog, enter the target name and host name,
then click Go.
c. In the target results table, click the name of the desired target and then Select.
d. When finished viewing the overlay, click Remove Overlay from the Overlay
menu.
7. Adding an Overlay, Today with Yesterday:
a. From the Overlay menu on the Performance Summary page, click Today with
Yesterday.
See Also:
■"About Performance Overview Pages in Fusion Middleware
Control"
■"About the Metrics Palette and the Performance Summary Page"
Managing Log Level Changes in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-19
b. When finished viewing the overlay, click Remove Overlay from the Overlay
menu.
8. Tes ti ng :
a. Using the Access Tester, perform several authentication and authorization
tests (see Chapter 26).
b. In Fusion Middleware Control, check performance metrics.
12.4.4 Displaying Component-Specific Performance Details
Fusion Middleware Control Administrators can use the following procedure to view
and compare component-specific performance data.
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the desired node and select a target. For example:
Identity and Access
oam_server
3. From the context menu, select Component Performance.
4. Choose Access Manager (or Security Token Service).
5. STS Partner ID: Choose a Partner ID in the Security Token Service results table for
more details, if needed.
6. Component Performance:
a. From the context menu, select Component Performance.
b. Choose either Access Manager (or Security Token Service).
c. Choose an item in the results table to get more details, if available.
7. Tes ti ng :
a. Using the Access Tester, perform several authentication and authorization
tests (see Chapter 26).
b. In Fusion Middleware Control, check performance metrics.
12.5 Managing Log Level Changes in Fusion Middleware Control
Oracle Fusion Middleware components generate log files containing messages that
record all types of events. Administrators can set log levels using Fusion Middleware
Control, as described in this chapter.
Topics in this section include:
See Also:
■"Access Manager Component Pages"
■"Security Token Service Component Pages"
Note: Alternatively, Administrators can set OAM logger levels using
custom WebLogic Scripting Tool (WLST) commands, as described in
Chapter 7.
Managing Log Level Changes in Fusion Middleware Control
12-20 Administrator's Guide for Oracle Access Management
■About Dynamic Log Level Changes
■Setting Log Levels Dynamically Using Fusion Middleware Control
12.5.1 About Dynamic Log Level Changes
Using Fusion Middleware Control, Administrators can change log levels dynamically
for Access Manager (or Security Token Service). Table 12–7 outlines log availability
and functions in Fusion Middleware Control.
Figure 12–16 shows the Log Levels configuration page in Fusion Middleware Control.
Notice that Runtime Loggers is the selected View and oracle.oam logger names are
currently displayed. With Security Token Service there is only one logger that affects
the log levels for Security Token Service:
oracle.security.fed
.
Table 12–7 OAM Log Availability and Functions in Fusion Middleware Control
Node Target
View Log
Messages
Log
Configuration
Application Deployment
Internal Applications ...AdminServer
oamsso_logout(11.1.1.3.0) AdminServer
oamsso_logout(11.1.1.3.0) oam_server
Yes
Yes
Yes
Yes
Yes
Yes
WebLogic Server domain
oam_bd (Cluster name)
AdminServer
oam_server
Yes
Yes
Yes
No
Yes
Yes
Identity and Access
OAM
(Cluster)
oam_server
(Server)
No
Yes
No
Yes
Managing Log Level Changes in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-21
Figure 12–16 Access Manager Log Levels on the Log Configuration Tab
Managing Log Level Changes in Fusion Middleware Control
12-22 Administrator's Guide for Oracle Access Management
Figure 12–17 Log Levels for Security Token Service
The Log Levels tab on the Log Configuration page allows you to configure the log
level for both persistent loggers and active runtime loggers:
■Persistent loggers are saved in a configuration file and become active when the
component is started.
The log levels for these loggers are persisted across component restarts.
■Runtime loggers are automatically created during runtime and become active
when a particular feature area is exercised.
For example, oracle.j2ee.ejb.deployment.Logger is a runtime logger that becomes
active when an EJB module is deployed. Log levels for runtime loggers are not
persisted across component restarts.
Table 12–8 explains the configuration status and options for log levels.
Table 12–8 Log Levels Tab on Log Configuration Page
Element Description
Apply Submits and applies log level configuration changes, which take affect
immediately.
Revert Restores the target's previous log level configuration, which take affect
immediately.
View Use this list to view runtime loggers or loggers with a persistent log
level state.
■Runtime Loggers
■Loggers with Persistent Log Level State
Managing Log Level Changes in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-23
Search Use this list to specify the categories you would like to search.
Table
Logger Name The name of the loggers found during the search. You can expand names
in the list to see any loggers beneath the top node.
Oracle Diagnostic Logging
Level (Java Level)
Choose the logging level for the corresponding logger; c.
Click Apply and review confirmation messages displayed in a pop-up
window:
Updating log levels
Updating the log levels of runtime loggers
The log levels of runtime loggers have been updated successfully
The log levels have been updated successfully
Log File Clicking a name in the Log File column displays the Log Files page,
which you can use to create and edit the file where log messages are
logged, the format of the log messages, rotation policies, and other
logging parameters.
See Also: "Managing Log File Configuration from Fusion Middleware
Control" on page 12-24.
Persistent Log Level State Identifies the persistent state for this specific logger, which is set when
you create or edit the value using the Log Files tab.
Table 12–8 (Cont.) Log Levels Tab on Log Configuration Page
Element Description
Managing Log File Configuration from Fusion Middleware Control
12-24 Administrator's Guide for Oracle Access Management
12.5.2 Setting Log Levels Dynamically Using Fusion Middleware Control
Fusion Middleware Control Administrators can use the following procedure to set the
log level dynamically.
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the desired node, and select a target. For example:
Identity and Access
oam_server
3. From the Access Manager context menu, select Logs and then choose Log
Configuration.
4. From the Log Levels tab, View list, choose the loggers to display. For example:
Runtime Loggers.
5. From the Search list, choose a category, enter your search criteria, and click the
search button. For example: All Categories sts.
6. In the results table, expand nodes to reveal information as needed.
7. In the results table, choose log levels for your environment, then click Apply (or
Revert).
8. Proceed to "Managing Log File Configuration from Fusion Middleware Control"
12.6 Managing Log File Configuration from Fusion Middleware Control
This section provides the following information:
■About Log File Configuration
■Managing Log Files with Fusion Middleware Control
12.6.1 About Log File Configuration
Figure 12–8 shows the Log Files Configuration. Use this page to create and edit where
the log messages will be logged to, the format of the log messages, the rotation policies
used, as well as other parameters depending on the log file configuration class.
See Also: "About Dynamic Log Level Changes" on page 12-20
Note: Administrators can also set logger levels using custom WLST
commands as described in Chapter 7.
Managing Log File Configuration from Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-25
Figure 12–18 Log Files Configuration Page
Table 12–9 describes the log files configuration parameters for Access Manager (or
Security Token Service).
Managing Log File Configuration from Fusion Middleware Control
12-26 Administrator's Guide for Oracle Access Management
Table 12–9 Log Files Elements
Element Description
Create Click this button to display the fresh form to create a new file for logged messages.
■Log File is the name of the log handler (odl-handler for OAM)
■Log Path points to the logging output file in your environment, which you can change.
■The output logging file in your environment can have a unique file name.
Create Like Click this button to display a partially filled-in form to create a new file for logged messages.
Edit Configuration Click this button to display and edit the selected log file configuration.
View Configuration Click this button to view a read-only description of the selected log file configuration.
Table The information in this table is based on log file configuration parameters in this table.
Handler Name The Log File name assigned during log file creation.
Log Path The file system directory path assigned during log file creation.
Log File Format The Log File format assigned during log file creation.
Rotation Policy The rotation policy selected during log file creation.
Managing Log File Configuration from Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-27
12.6.2 Managing Log Files with Fusion Middleware Control
Fusion Middleware Control Administrators can use the following procedure to create
a log file, edit the configuration, or view a read-only version of the log file
configuration.
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the desired node, and select a target. For example:
Identity and Access
oam_server
3. From the Access Manager menu, select Logs and then Log Configuration.
4. Create a Log File: From the Log Files tab (Table 12–9):
a. Click the Create button to display a fresh Create Log File form.
b. Enter a name and file system path for this log file. For example:
Log File
oam-odl-handler
Log Path domains
/oam_db/servers/oam-server1/log/oam.log
c. Click the desired Log File Format. For example: ... Text
d. Set the logging attributes. For example:
Use Default Attributes
Supplemental Attributes
e. Associate a Logger. For example: Root Logger
f. Specify the Rotation Policy. For example: Size Based
Maximum Log File Size (MB)
10.0
Maximum Size of All Log File Size (MB)
1000.0
g. Click OK to submit the configuration.
5. Create Like:
a. From the Log Files tab, click the name of an existing log file.
b. Click the Create Like button.
c. On the Create Log File form, enter your own information:
Log File name
Log Level
Attributes
d. Edit any other details as needed, then click OK to submit the configuration.
6. Edit Configuration:
a. From the Log Files tab, click the name of an existing log file.
b. Click the Edit Configuration button.
c. Change configuration details as needed.
d. Click OK to submit the changes.
See Also: "About Log File Configuration" on page 12-24
Viewing Log Messages in Fusion Middleware Control
12-28 Administrator's Guide for Oracle Access Management
7. View Configuration:
a. From the Log Files tab, click the name of an existing log file.
b. Click the View Configuration button.
c. Review the information, then click OK to dismiss the configuration page.
Contents are greyed out when opened for viewing configuration.
8. Proceed to "Viewing Log Messages in Fusion Middleware Control".
12.7 Viewing Log Messages in Fusion Middleware Control
This section includes the following topics:
■About Finding, Viewing, and Exporting Log Messages
■Viewing Logged Messages With Fusion Middleware Control
12.7.1 About Finding, Viewing, and Exporting Log Messages
By using the context menu for an OAM Server instance in Fusion Middleware Control,
Administrators can locate, view, and export key log information for:
■Application Deployment targets, including the WebLogic (and OAM)
AdminServer and the OAM SSO logout pages on both AdminServer and OAM
Servers
■WebLogic Server domain targets, including the OAM Farm, AdminServer, and
OAM Servers
■Identity and Access targets, including the OAM Farm, Clusters, and individual
OAM Servers
Using log files to troubleshoot common problems requires that you:
■Get familiar with the Oracle Diagnostic Logging (ODL) format used by Oracle
Fusion Middleware components, as described in the Oracle Fusion Middleware
Application Security Guide
■Configure log files to collect the appropriate level of information
■Search, view and export key log information in the farm
■Correlate messages in log files across components
Figure 12–19 shows the Log Messages page for Access Manager and Security Token
Service in Fusion Middleware Control.
Viewing Log Messages in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-29
Figure 12–19 Typical Log Messages Page in Fusion Middleware Control
Table 12–10 describes elements on the Log Messages page in Fusion Middleware
Control, which you can use to locate and view messages.
Table 12–10 OAM Log Message Search Controls in Fusion Middleware Control
Element Description
Broaden Target Scope Select items on this list to expand (or narrow) the targets that are used in this search:
■Oracle WebLogic Server domain
■OAM Cluster
■Oracle WebLogic Server
■Oracle Fusion Middleware Farm
Target Log Files... Displays a list of all log files for the target scope from which you can select a specific log file to view or
download.
Refresh Options Select an item from this list to specify the refresh method:
■Manual Refresh
■30 Second Refresh
■1 Minute Refresh
Search Options
Viewing Log Messages in Fusion Middleware Control
12-30 Administrator's Guide for Oracle Access Management
Date Range The period during which the desired set of messages was logged:
■Most Recent
Minutes
Hours
Days
■Time interval
Date Range
Start Date
End Date
Message Types Check all message types that apply for this search:
■Incident Error
■Error
■Warning
■Notification
■Trace
■Unknown
Message Choose an identifier from this list and add a value in the blank field beside it to refine your search
criteria:
Add Fields Click this button to display a list of additional search criteria you can include.
Search Click this button to initiate a search using the specified criteria.
Viewing Options
Table 12–10 (Cont.) OAM Log Message Search Controls in Fusion Middleware Control
Element Description
Viewing Log Messages in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-31
View Choose items from this menu to view or reorder columns in the search results table:
Show Select the entity to view:
View Related Messages This menu is available when at least one message is listed in the search results.
Table 12–10 (Cont.) OAM Log Message Search Controls in Fusion Middleware Control
Element Description
Viewing Log Messages in Fusion Middleware Control
12-32 Administrator's Guide for Oracle Access Management
12.7.2 Viewing Logged Messages With Fusion Middleware Control
Fusion Middleware Control Administrators can use the following procedure to view
and download log messages for the target. This procedure explains how to search for
messages, view messages (or view related messages), view all messages in a single log
file, and export or download messages.
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the desired node and select a target. For example:
Identity and Access
oam_server
3. From the OAM context menu, select Logs and then choose View Log Messages.
4. Search (Table 12–10):
a. Specify a Date Range.
b. Check all Message Types to be included in your search.
c. Define Message content options.
d. Add Fields: Enter details to further refine message content.
e. Click Search to display a list of messages that fit your search criteria.
Export Messages to a
File
A menu of viewing commands that are available when at least one message is listed in the search
results. You can choose from the following commands:
Results Table Columns These are based on selections in the View menu on the Log Messages page.
Message Area Displays details for the selected message in the search results table.
See Also: "About Finding, Viewing, and Exporting Log Messages"
on page 12-28
Table 12–10 (Cont.) OAM Log Message Search Controls in Fusion Middleware Control
Element Description
Displaying MBeans in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-33
5. View Messages: From the table of search results, click one or more messages to
view on the lower half of the page.
6. View Related: Use one of the following methods to organize the table of search
results.
a. By Time: From the View Related menu, select by Time.
b. By ECID: Click ECID in the message on the screen (or, from the View Related
menu, select by ECID Execution Context ID).
c. From the Scope menu, select a time period.
7. Log File: From the table of search results, click a name in the Log File column to
view all messages in the file.
8. Export Messages
a. Select one or more messages in the search results table.
b. From the Export Messages menu, choose the desired export format. For
example: As Oracle Diagnostic Log (.txt).
c. In the dialog box, click Open with and then choose the desired program.
d. From the open program, save the file to a new path.
9. Download
a. Select one or more messages in the search results table.
b. Click the Download button.
c. In the dialog box, click Open with and then choose the desired program.
d. From the open program, save the file to a new path.
10. Tes ti ng :
a. Using the Access Tester, enter an invalid user name and try to authenticate
(see Chapter 26).
b. In Fusion Middleware Control, go to the log viewer and review the error.
c. Using the Access Tester, enter an invalid password and try to authenticate.
d. In the Fusion Middleware Control log viewer, check the error and then view
all related log messages.
e. Repeat this test using different log levels, as described in "Managing Log Level
Changes in Fusion Middleware Control" on page 12-19.
12.8 Displaying MBeans in Fusion Middleware Control
A Java object is a unit of code that runs the computer. Each object is an instance of a
particular class or subclass that relies on the class's methods or procedures or data
variables. Within the Java programming language, a Java object that represents a
manageable resource (application, service, component, or device) is known as an
MBean (managed bean).
Fusion Middleware Control enables you to:
■View information on key MBean Attributes and Operations
■Invoke methods
This section provides the following topics:
Displaying MBeans in Fusion Middleware Control
12-34 Administrator's Guide for Oracle Access Management
■About the System MBean Browser
■Managing Mbeans
12.8.1 About the System MBean Browser
The Fusion Middleware Control System Mbean Browser can be used to view the items
outlined in Table 12–11.
Table 12–12 describes the MBeans that Access Manager and Security Token Service
deploy on the AdminServer on the domain runtime server (OAM Server).
Figure 12–20 Shows the System MBean Browser and the related Attributes tab
displaying information for the Security Token Service CertRevocationListConfig:
oracle.sts:Location=oam_server1,type=CertRevocationListConfig
.
Table 12–11 System MBean Browser
Node Target System Mbean Browser
Application Deployment
Internal Applications ...AdminServer
oamsso_logout(11.1.1.3.0)
AdminServer
oamsso_logout(11.1.1.3.0) oam_
server
Yes
Yes
Yes
WebLogic Server domain
oam_bd (Cluster name)
AdminServer
oam_server
Yes
Yes
Yes
Identity and Access
OAM
(Cluster)
oam_server
(Server)
No
Yes
Note: Security Token Service MBeans are also available as described
here.
Table 12–12 MBeans that Access Manager and Security Token Service Deploy
MBeans For Description
Configuration Service oracle.oam:type=Config
Partner and Trust Service oracle.oam:type=PATConfig
STS MBeans oracle.sts:type=Config
Certificate Validation Module These are used for CRL management.
oracle.sts:type=CertRevocationListConfig
Displaying MBeans in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-35
Figure 12–20 System MBean Browser and Attributes Tab
Table 12–13 describes the System MBean Browser and associated tab in greater details.
Displaying MBeans in Fusion Middleware Control
12-36 Administrator's Guide for Oracle Access Management
12.8.2 Managing Mbeans
Fusion Middleware Control Administrators can use the following procedure to view,
edit or invoke MBeans for Access Manager and Security Token Service. Additionally,
you can apply values (or revert the change) and invoke MBeans.
1. Log in as described in "Logging In To Fusion Middleware Control" on page 12-3.
2. Expand the desired node and select a target. For example:
Identity and Access
oam_server
Table 12–13 System MBean Browser
System MBean Browser
System MBean Browser Expand items in this section to display Mbeans for the selected target. Under Application Defined
Beans, find
oracle.oam
and
oracle.sts
.
MBean Information Details for Attributes and Operations related to the MBean for the selected target are displayed on
the right.
Attributes This tab describes MBean attributes for the selected target.
Operations This tab describes MBean operations for the selected target.
Notifications This tab lists any notifications resulting from the invocation of an MBean.
Controls The following controls are available from these pages:
■Name Link: Clicking a name on either tab displays a full description of related MBeans.
■Apply Button: Submits and applies the selected MBean attribute value.
■Revert Button: Restores previous MBean attribute values following a change (and before
clicking Apply.
■Return Button: Returns you to the MBean Information page.
■Invoke Button: Invokes the selected MBean and value
Displaying MBeans in Fusion Middleware Control
Monitoring Performance and Logs with Fusion Middleware Control 12-37
3. From the Access Manager context menu, select System MBean Browser.
4. System MBean Browser: Expand classes and select an MBean target to display
related attributes and operations. For example: oracle.sts or oracle.oam.
5. Manage MBean Attributes:
a. Click the Attributes tab.
b. Review the name and description of MBean attributes for the selected target.
c. Edit values for one or more attributes and click Apply to submit changes (or
click Revert to cancel changes).
Alternatively: Click a Name in the Attributes table to display a full description
and the value; change the value and click Apply (or click Revert to cancel the
change).
6. Manage MBean Operations:
a. Click the Operations tab.
b. Review the name, description, number of parameters, and return type for each
MBean operation for the selected target.
c. Click a name in the Operations table to display the parameters and related
name, description, type, and value.
d. Edit values for the operation and click Apply to submit changes (or click
Revert to cancel changes).
e. Click Invoke to invoke the MBean and review the message that appears.
Displaying MBeans in Fusion Middleware Control
12-38 Administrator's Guide for Oracle Access Management
Part IV
Par t IV
Managing Access Manager Settings and
Agents
Part IV provides information about managing low-level Access Manager settings,
agents and sessions. It contains the following chapters.
■Chapter 13, "Configuring Access Manager Settings"
■Chapter 14, "Introduction to Agents and Registration"
■Chapter 15, "Registering and Managing OAM 11g Agents"
■Chapter 16, "Maintaining Access Manager Sessions"
13
Configuring Access Manager Settings 13-1
13
Configuring Access Manager Settings
[13]
The Access Manager Settings provide configuration options for a number of specific
Access Manager service operations.
This chapter describes these Access Manager-specific settings.
■Oracle Access Management Overview
■Managing Load Balancing
■Managing Secure Error Modes
■Managing SSO Tokens and IP Validation
■Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security
■Managing Run Time Policy Evaluation Caches
13.1 Oracle Access Management Overview
Before you begin this chapter on configuration options and service operations, be sure
to review the following topics.
■Chapter 2, "Getting Started with Oracle Access Management"
■Chapter 6, "Managing Server Registration"
13.2 Managing Load Balancing
This section provides the following topics:
■About Common Load Balancing Settings
■Managing OAM Server Load Balancing Settings
13.2.1 About Common Load Balancing Settings
For production environments that require increased application performance,
throughput, or high availability, you can configure two or more Managed Servers to
operate as a cluster. A cluster is a collection of multiple WebLogic Server server
instances running simultaneously and working together to provide increased
scalability and reliability. In a cluster, most resources and services are deployed
identically to each Managed Server (as opposed to a single Managed Server), enabling
failover and load balancing. A single domain can contain multiple WebLogic Server
clusters and multiple Managed Servers that are not configured as clusters. The key
difference between clustered and non-clustered Managed Servers is support for
Managing Load Balancing
13-2 Administrator's Guide for Oracle Access Management
failover and load balancing. These features are available only in a cluster of Managed
Servers.
By default, Access Manager has a single OAM Server to which all login and logout
requests are sent. In a high-availability deployment, you must change this setup so
that login and logout requests are first sent to the load balancer.
Figure 13–1 shows the Load Balancing Settings section of the Access Manager Settings
page. In earlier releases this was part of the SSO Engine settings; the SSO Engine being
the controller for sessions.
Figure 13–1 Access Manager Settings: Load Balancer
Table 13–1 describes each element and how it is used. Settings are global and common
to all OAM Servers in the WebLogic administration domain.
13.2.2 Managing OAM Server Load Balancing Settings
Users with valid Administrator credentials can perform the following task to modify
Access Manager load balancing settings using Oracle Access Management Console.
1. From the Access Manager Settings, open Load Balancing:
2. Expand the Load Balancing area:
■View Only: Close the page when you finish.
■Modify: Edit Load Balancing settings for your deployment (Table 13–1).
3. Click Apply to submit the changes (or close the page without applying changes).
4. Dismiss the Confirmation window.
See Also: Oracle Fusion Middleware High Availability Guide,
"Access Manager High Availability Configuration Steps" for high-level
instructions to set up a high availability Access Manager deployment.
Table 13–1 Access Manager Settings: Load Balancer
Element Description
OAM Server Host The virtual host name that represents the OAM Server Cluster, which
might be exposed by a load balancer in front of an OAM Server
Cluster.
OAM Server Port The virtual host port associated with the OAM Server Cluster. Values
between 1 and 65535 are supported.
OAM Server Protocol The protocol, either HTTP or HTTPS, that is used to access the virtual
host that represents the OAM Server Cluster.
See Also: "About Security Modes and X509Scheme Authentication" on
page C-4
See Also: "About Common Load Balancing Settings" on page 13-1
Managing Secure Error Modes
Configuring Access Manager Settings 13-3
13.3 Managing Secure Error Modes
A custom error page is packaged as part of the custom login application. An
out-of-the-box custom Web application archive file is provided that you can use as a
starting point to develop customized login and password pages.
Server Error Mode settings are global and common to all OAM Servers in the
WebLogic administration domain. This section provides the following topics:
■About OAM Server Error Modes
■Managing OAM Server Secure Error Modes
13.3.1 About OAM Server Error Modes
Figure 13–1 shows the Server Error Mode function, which appears on the Load
Balancing Settings area of the Access Manager Settings page.
Figure 13–2 Access Manager Settings: Server Error Mode
Table 13–2 describes the options you can choose to configure Server Error Mode for
your deployment.
Table 13–3 shows the error triggering condition and message codes for each of the
three modes.
Table 13–2 Server Error Mode
Element Description
Server Error Mode The setting you choose determines the nature of error messages and error codes
returned by the OAM Server when an operation fails (because of an invalid
username or password, for example, or a server error (connection to the LDAP
Server is down)).
Choose one of the following settings to configure error messages with varying
degrees of security for your custom login pages:
■SECURE: Most secure. Provides generic error messages that barely give any
hint of the internal reason for the error.
■EXTERNAL: Recommended level.
■INTERNAL: Least secure level. Recommended for Password Policy
validation, as described in "Managing Global Password Policy".
■OSSO10g: Compatible with OSSO 10g. Might be required in upgraded
environments for consistency.
See Also: "Managing OAM Server Secure Error Modes" on page 13-5.
Managing Secure Error Modes
13-4 Administrator's Guide for Oracle Access Management
Table 13–4 identifies the error codes, trigger conditions, and recommended messages.
Table 13–3 Error Trigger Condition, Modes, and Message Codes
Error Triggering Condition Internal Mode External Mode Secure Mode
Invalid login attempt OAM-1 OAM-2 OAM-8
Processing submitted credentials fails. For example: In WNA mode, the
SPNEGO token is not received.
OAM-3 OAM-3 OAM-8
An authentication exception is raised. OAM-4 OAM-4 OAM-9
User account gets locked based on certain conditions (exceeded invalid
attempts, for instance).
OAM-5 OAM-5 OAM-8
OAM-9 with
OIM integration
User account disabled. OAM-5 OAM-5 OAM-9
User has exceeded the maximum number of allowed sessions (a
configurable attribute).
OAM-6 OAM-6 OAM-9
Default error message, which is displayed when no other specific messages
propagate up. This is not propagated to the user level. Cause could be
multiple conditions.
OAM-7 OAM-7 OAM-9
Password expired. OAM-10 OAM-10 OAM-9
See Also: Developing Custom Error Pages in the Oracle Fusion
Middleware Developer's Guide for Oracle Access Management
Table 13–4 External Error Codes, Trigger Conditions, and Recommended Messages
External
Error Code Trigger Condition Recommended Display Message
OAM-1 Invalid login attempts less than the allowed
count.
An incorrect Username or Password was
specified
OAM-2 Invalid login attempts less than the allowed
count.
An incorrect Username or Password was
specified
OAM-3 Processing submitted credentials fails for
some reason. For example: in WNA mode,
the SPENGO token is not received.
Internal Error.
OAM-4 An authentication exception is raised for
some reason.
System error. Please contact the System
Administrator.
OAM-5 The user account gets locked because of
certain conditions (exceeded invalid
attempts, for instance).
OIM Integration. The Error page appears
with contact details after the password is
validated.
The user account is locked or disabled.
Please contact the System Administrator.
OAM-5 The user account gets locked because of
certain conditions (exceeded invalid
attempts, for instance).
OID Without OIM Integration: The Error
page appears with contact details after the
password is validated.
The user account is locked or disabled.
Please contact the System Administrator.
OAM-5 The user account is disabled. The user account is locked or disabled.
Please contact the System Administrator.
OAM-6 The user has exceeded the maximum
number of allowed sessions, which is a
configurable attribute.
The user has already reached the maximum
allowed number of sessions. Please close
one of the existing sessions before trying to
login again.
Managing SSO Tokens and IP Validation
Configuring Access Manager Settings 13-5
13.3.2 Managing OAM Server Secure Error Modes
Users with valid Administrator credentials can perform the following task to view or
edit Access Manager secure error mode settings for OAM Servers using the Oracle
Access Management Console.
1. In the Configuration console, select Access Manager from the View menu in the
Settings section.
2. On the Access Manager Settings page, expand the Load Balancing section.
3. Server Error Mode:
■Modify: Choose the desired Server Error Mode for your deployment
(Table 13–2 and Table 13–4).
■View Only: Close the page when you finish.
4. Click Apply to submit the changes (or close the page without applying changes).
5. Dismiss the Confirmation window.
6. Proceed to "Managing SSO Tokens and IP Validation".
13.4 Managing SSO Tokens and IP Validation
This section provides the following topics:
■About Access Manager SSO Tokens and IP Validation Settings
■Managing SSO Tokens and IP Validation
13.4.1 About Access Manager SSO Tokens and IP Validation Settings
Figure 13–3 shows the SSO portion of the Access Manager Settings page. Table 13–5
describes each element and how it is used.
OAM-7 Failure could be due to multiple reasons; the
exact reason is not propagated to the user
level for security reasons. For instance:
■The request ID could have been lost
■The certificate is not retrieved correctly
The default error message is displayed
when no other specific messages are
propagated up.
System error. Please re-try your action. If
you continue to get this error, please contact
the Administrator.
OAM-8 See Table 13–3 Authentication failed.
OAM-9 System error. Please re-try your action. If
you continue to get this error, please contact
the Administrator.
System error. Please re-try your action. If
you continue to get this error, please contact
the Administrator.
OAM-10 Password expired. The password has expired.
See Also: "About Common Load Balancing Settings" on page 13-1
Table 13–4 (Cont.) External Error Codes, Trigger Conditions, and Recommended Messages
External
Error Code Trigger Condition Recommended Display Message
Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security
13-6 Administrator's Guide for Oracle Access Management
Figure 13–3 Access Manager Settings: SSO
13.4.2 Managing SSO Tokens and IP Validation
Users with valid Administrator credentials can perform the following task to view or
edit Access Manager SSO settings using the Oracle Access Management Console.
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Access Manager from the View menu in the
Settings section.
3. Expand the SSO section:
■View Only: Close the page when you finish.
■Modify: Perform remaining steps to edit the configuration.
4. Edit settings as needed for your deployment, based on details in Table 13–5.
5. Click Apply to submit the changes (or close the page without applying changes).
6. Dismiss the Confirmation window.
7. Proceed to "Managing the Access Protocol for OAM Proxy Simple and Cert Mode
Security".
13.5 Managing the Access Protocol for OAM Proxy Simple and Cert Mode
Security
This section provides the following details:
■About Simple and Cert Mode Transport Security
■About the Common OAM Proxy Page for Secure Server Communications
■Viewing or Editing Simple or Cert Settings for OAM Proxy
■Configuring 64-bit WebGate in Cert Mode
■Tuning the Simple Mode WebGate
Table 13–5 Access Manager Settings: SSO
Element Description
IP Validation Specific to WebGates and is used to determine whether a client's IP
address is the same as the IP address stored in the ObSSOCookie
generated for single sign-on.
Check the box to enable IP Validation.
Clear the box to disable IP Validation if and only if IP Validation is
disabled on all the configured WebGates. See Section 15.2.3, "About IP
Address Validation for WebGates."
SSO Token Version Select your SSO token version from the list.
See Also: "About Common Load Balancing Settings" on page 13-1
Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security
Configuring Access Manager Settings 13-7
13.5.1 About Simple and Cert Mode Transport Security
Table 13–6 outlines the similarities between Simple and Cert modes.
See Also: Appendix C, "Securing Communication"
Table 13–6 Summary: Simple and Cert Mode
Artifact or Process Simple Mode Cert Mode Open Mode
X.509 digital certificates only. X X N/A
Communication between OAM Agents and
OAM Servers is encrypted using Transport
Layer Security, RFC 2246 (TLS v1).
X X N/A
For each public key there is a corresponding
private key that Access Manager stores in a
file:
aaa_key.pem
generated by openSSL
aaa_key.pem
generated by your CA
N/A
Signed certificates in Privacy Enhanced
Mail (PEM) format
aaa_cert.pem generated by
openSSL
aaa_cert.pem generated by
your CA
N/A
During OAM Server configuration, secure
the private key with a Global passphrase or
PEM format details, depending on which
mode you are using. Before an OAM Server
or Webgate can use a private key, it must
have the correct passphrase.
Global passphrase stored in
a nominally encrypted file:
■password.xml
PEM format:
■Keystore Alias
■Key KEYSTOREStore
Alias Password
N/A
During OAM Agent or OAM Server
registration, the communication mode is
propagated to the Oracle Access
Management Console.
Same passphrase for each
Webgate and OAM Server
instance.
Different passphrase for
each Webgate and OAM
Server instance.
N/A
The certificate request for the Webgate
generates the certificate request file, which
you must send to a root CA that is trusted
by the OAM Sever.
The root CA returns the Webgate
certificates, which can then be installed
either during or after Webgate installation.
cacert.pem
The certificate request,
signed by the
Oracle-provided openSSL
Certificate Authority
aaa_req.pem
The certificate request,
signed by the your
Certificate Authority
N/A
Encrypt the private key using the DES
Algorithm. For example:
openssl rsa -in aaa_key.pem -passin
pass: -out aaa_key.pem -passout pass:
passphrase -des
N/A X N/A
Agent Key Password N/A Enter a password during
agent registration in Cert
Security mode (see
Table 15–1, " Elements on
Create Pages for 11g and 10g
OAM Agents").
N/A
Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security
13-8 Administrator's Guide for Oracle Access Management
13.5.2 About the Common OAM Proxy Page for Secure Server Communications
Table 13–7 describes the settings required for Simple or Cert mode configurations.
13.5.3 Viewing or Editing Simple or Cert Settings for OAM Proxy
Administrators can use this procedure to view or edit Simple or Cert mode settings for
the common OAM Proxy.
During Agent registration,
ObAccessClient.xml is generated in:
$DOMAIN_HOME/output/$Agent_Name/
ObAccessClient.xml
Copy to:
11g Webgate: $11gWebgate_
instance_
dir/config/OHS/ohs1/web
gate/config
If:
$11gWebgate_instance_
dir=$ORACLE_
HOME/instance/instance1
10g Webgate: $Webgate_
install_dir/oblix/lib
ObAccessClient.xml
Copy to:
11g Webgate: $11gWebgate_
instance_dir/...
10g Webgate: $Webgate_
install_dir/...
ObAccessClient.xml
Copy to:
11g Webgate:
$11gWebgate_
instance_dir/...
10g Webgate:
$Webgate_install_dir/
...
During Agent registration, password.xml is
generated in:
$DOMAIN_HOME/output/$Agent_Name/
See Also: Appendix C
password.xml
Copy to:
11g Webgate: $11gWebgate_
instance_dir/...
10g Webgate: $Webgate_
install_dir/...
password.xml
Copy to:
11g Webgate: $11gWebgate_
instance_dir/...
10g Webgate: $Webgate_
install_dir/...
N/A
During Agent registration, aaa_key.pem is
generated in:
$DOMAIN_HOME/output/$Agent_Name/
See Also: Appendix C
aaa_key.pem
Copy to:
11g Webgate: $11gWebgate_
instance_dir...
10g Webgate: $Webgate_
install_dir...
aaa_key.pem
Copy to:
11g Webgate: $11gWebgate_
instance_dir...
10g Webgate: $Webgate_
install_dir...
N/A
Table 13–7 Server Common OAM Proxy Secure Communication Settings
Mode Description
Simple Mode Configuration The global passphrase for communication using OAM-signed X.509
certificates. This is set during initial OAM Server installation.
Administrators can edit this passphrase and then reconfigure all existing
OAM Agents to use it, as described in"Viewing or Editing Simple or Cert
Settings for OAM Proxy".
Cert Mode Configuration Details required for the Key KEYSTOREStore where the Cert mode X.509
certificates signed by an outside Certificate Authority reside:
■PEM Keystore Alias
■PEM Keystore Alias Password
Note: These are set during initial OAM Server installation. The certificates
can be imported using the import certificate utility or the keytool shipped
with JDK.
Administrators can edit the alias and password and then reconfigure all
existing OAM Agents to use them, as described in"Viewing or Editing
Simple or Cert Settings for OAM Proxy".
Table 13–6 (Cont.) Summary: Simple and Cert Mode
Artifact or Process Simple Mode Cert Mode Open Mode
Managing Run Time Policy Evaluation Caches
Configuring Access Manager Settings 13-9
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Access Manager from the View menu in the
Settings section.
3. Expand the Access Protocol section.
4. Simple Mode Configuration: Add or alter a Global Passphrase if you are using
OAM-signed X.509 certificates.
5. Cert Mode Configuration: Specify the following details.
■PEM Keystore Alias
■PEM Keystore Alias Password
6. Click Apply to submit the changes and dismiss the Confirmation window (or
close the page without applying changes).
7. Update Agent registration pages as needed to regenerate artifacts, and then
replace the earlier artifacts as described in Chapter 14 or Chapter 15.
13.5.4 Configuring 64-bit WebGate in Cert Mode
64-bit WebGates now support SHA2 (256,384 & 512 bit) certificates. Run the following
command to configure a 64-bit WebGate in cert mode.
<Oracle Middleware Home>/oracle_common/bin/orapki wallet add
-wallet $DOMAIN_HOME/output/$Agent_Name/cwallet.sso -trusted_cert
-cert <Root CA path .i.e. aaa_chain.pem> -auto_login_only
13.5.5 Tuning the Simple Mode WebGate
If using a simple mode WebGate, you can improve the response time of the OAM login
page by changing the
aaaTimeoutThreshold
time parameter in the WebGate profile
from -1 to 10. For detailed information about the AAA Timeout Threshold
configuration element, see Table 15–3, " Elements on Expanded 11g and 10g
WebGate/Access Client Registration Pages" in Chapter 15.
13.6 Managing Run Time Policy Evaluation Caches
This section explains:
■About Run Time Policy Evaluation Caches
■Managing Run Time Policy Evaluation Caches
13.6.1 About Run Time Policy Evaluation Caches
Figure 13–4 illustrates the Policy section of the Access Manager Settings page. This
section provides settings for the Resource Matching Cache and the Authorization
Result Cache, which come into play during policy evaluation at run time.
See Also:
■"Registering an OAM Agent Using the Console" on page 15-13
■Appendix C, "Securing Communication"
See Also: "About Run Time Resource Evaluation" on page 25-26
Managing Run Time Policy Evaluation Caches
13-10 Administrator's Guide for Oracle Access Management
Figure 13–4 Common Policy Evaluation Caches
Table 13–8 outlines these global settings that apply to all servers and requests.
13.6.2 Managing Run Time Policy Evaluation Caches
Administrators can use this procedure to manage the Access Manager common run
time policy evaluation cache settings.
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Access Manager from the View menu in the
Settings section.
3. Expand the Policy section.
4. Resource Matching Cache: Specify details and click apply (Table 13–8).
5. Authorization Result Cache: Specify details and click apply (Table 13–8).
6. Click Apply to submit the changes and dismiss the Confirmation window (or
close the page without applying changes).
Table 13–8 Policy Evaluation Caches
Element Description
Resource Matching Cache Caches mappings between the requested URL and the policy holding
the resource pattern that applies to the URL.
Default Values:
■Maximum Size 100000 Zero disables the cache
■Time to Live (seconds) 3600 Zero disables Time to Live
Authorization Result Cache Caches policy decisions for the requested URL and user.
Default Values:
■Maximum Size 100000 Zero disables the cache
■Maximum Size per User 100 Zero disables the cache
■Time to Live (seconds) 3600 Zero disables Time to Live
See Also: Oracle Fusion Middleware Performance and Tuning Guide
See Also: Guide
■Oracle Fusion Middleware High Availability Guide
■Oracle Fusion Middleware Performance and Tuning Guide
14
Introduction to Agents and Registration 14-1
14
Introduction to Agents and Registration
An agent (also known as a single sign-on agent or policy-enforcement agent) is any
front-ending entity that acts as an access client to enable single sign-on across
enterprise applications. Individual agents must be registered with Access Manager 11g
to set up the required trust mechanism between the agent and OAM Server. Registered
agents delegate authentication tasks to the OAM Server.
This chapter includes the following topics to give you an overview of agents, their
registration and management, processing, and tools.
■Introduction to Policy Enforcement Agents
■Introduction to Agent Registration
■Introduction to Remote Registration
14.1 Introduction to Policy Enforcement Agents
An agent is a software plug-in that can be installed on a Web server (such as Oracle
HTTP Server) where the application resides. To secure access to protected resources, a
Web server, Application Server, or third-party application must be associated with an
agent that is registered with Access Manager. To spare users from re-authenticating
when accessing multiple resources, the application delegates the authentication
function to the single sign-on (SSO) provider: Access Manager.
During agent registration, the application can be automatically registered and basic
policies automatically generated. Alternatively, you can turn off automatic policy
generation during Agent registration and manually create policies.
After registration, the Agent acts as a filter for HTTP/HTTPS requests, communicating
between the OAM Server and its services. The Agent intercepts requests for resources
protected by Access Manager and works with Access Manager to fulfill access
requirements. The following sections introduce the types of agents.
■About Agent Types and Runtime Processing
■About 11g WebGate Configured as a Detached Credential Collector
■About 11g WebGate Functionality for Mobile and Social
■About the Pre-Registered 10g WebGate IAMSuiteAgent
14.1.1 About Agent Types and Runtime Processing
With Access Manager 11.1.2, each Agent acts as a filter for requests. Your deployment
can include the agent types described in Table 14–1, in any combination.
Introduction to Policy Enforcement Agents
14-2 Administrator's Guide for Oracle Access Management
Table 14–1 Agent Types
Agent Type Description
OAM Agents
Note: Unless explicitly
stated, the terms Webgate
and Access Client are used
interchangeably.
OAM Agents must be installed independently, following Oracle Access
Management installation. After registering the agent with Access Manager,
the agent communicates directly with registered OAM Servers and Access
Manager services. OAM Agents communicate with Access Manager using
the OAM Proxy to "sanitize" the request and respond identically for all
agents. The following OAM Agents types are available:
■Webgate: An out of an box Web server access client that intercepts
HTTP requests for Web resources and forwards these to the OAM
Server. WebGates for various Web servers are shipped with Access
Manager.
11g WebGates (Chapter 30) provide:
Oracle Universal Installer for platform
Host-based cookie
Individual WebGate OAMAuthnCookie_<host:port>
Resource to Authorization Policy
Authorization Result
Webgate Authorization Caching
Diagnostic page to tune parameters
Capability to act as a detached credential collector
See Also:
"About 11g WebGate Functionality for Mobile and Social"
"About 11g WebGate Configured as a Detached Credential Collector"
Oracle Fusion Middleware Performance and Tuning Guide
10g WebGates provide
InstallShield and One installer per platform
Domain-based cookie
ObSSOCookie (one for all 10g WebGates)
Web server configuration
See Also: 10g Pre-registered IAMSuiteAgent in this table and
Chapter 30
■Custom, Programmatic Access Clients: Access Manager provides a
pure Java software developer kit (SDK). Use this SDK to create custom
Access Clients and extensions for Access Manager authentication and
authorization functionality (and custom tokens). An Access Client
processes requests for Web and non-Web resources (non-HTTP) from
users or applications. See details in the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management.
IAMSuiteAgent
a Pre-registered OAM 10g
Agent
This pre-registered 10g agent provides single sign-on functionality for the
IAM suite of consoles. The IAM Suite Agent includes a companion
Application Domain (IAMSuite) and basic policies that should not be
modified.
See Also: About the Pre-Registered 10g WebGate IAMSuiteAgent on
page 14-5
Legacy OSSO Agents mod_osso is part of the OracleAS 10g single sign-on (OSSO) solution that
authenticates users at a central OSSO Server. The mod_osso module is an
Oracle HTTP Server module that provides authentication to OracleAS
applications.
After registration with Access Manager, OSSO 10g Agents communicate
directly with Access Manager 11g services through an OSSO proxy. The
OSSO proxy supports existing OSSO agents when upgrading to Access
Manager. The OSSO proxy handles requests from OSSO Agents and
translates the OSSO protocol into a protocol for Access Manager 11g
authentication services.
Access Manager gives mod_osso the redirect URL for the user based on the
authentication scheme associated with the OAM policy defined for the
resource
See Also: Chapter 29, "Registering and Managing Legacy OSSO Agents" as
well as the following topics:
Introduction to Policy Enforcement Agents
Introduction to Agents and Registration 14-3
Table 14–2 introduces Access Manager features that support agent registration,
configuration, management, and single-sign on. Links to topics providing more
information are included.
Table 14–3 provides run time processing information for OAM Agents.
Legacy OpenSSO Agents Java Agents are deployed J2EE containers to work with the OpenSSO
server. Web Agents can be deployed on any Web or Servlet container. Each
OpenSSO Agent is a filter that is plugged into the container (Oracle
WebLogic Server, JBoss, Apache, and so on) that hosts applications.
Access Manager provides an OpenSSO Proxy to handle requests for
resources protected by OpenSSO Agents:
Scope can be Host- or Domain-based
OpenSSO Agent key stored locally (Agent bootstrap file, Agent host)
See Also: Chapter 28, "Registering and Managing Legacy OpenSSO
Agents".
Table 14–2 Agent Registration and SSO Support
Oracle Provides Description
Oracle Access Management Console Agent Registration, Configuration, Management.
See Also: "Registering an OAM Agent Using the Console" on page 15-13
oamreg tool Remote Agent Registration and Management
See Also: "Acquiring and Setting Up the Remote Registration Tool". on
page 15-33
SSO Implementations Access Manager supports numerous SSO scenarios.
See Also: "Introducing Access Manager Single Sign-On" on page 21-1
Protocols that secure information
exchange on the Internet
This depends on the credential collector you choose.
See Also: Table 22–5, " Comparing the DCC and ECC"
Login and Logout Forms The location of the login and logout forms depends on the credential collector.
See Also: Table 22–5, " Comparing the DCC and ECC" and Chapter 27
Cryptographic keys One key is generated and used per registered mod_osso or 11g Webgate.
However, one single key is generated for all 10g Webgates.
See Also: Table 1–2, " Features in Access Manager 11.1.2"
Keys storage ■Agent side: A per agent key is stored locally in the Oracle Secret Store in a
wallet file.
■OAM Server side: A per agent key, and server key, are stored in the
credential store on the server side.
See Also: "Understanding Credential Collection and Login"
Table 14–1 (Cont.) Agent Types
Agent Type Description
Introduction to Policy Enforcement Agents
14-4 Administrator's Guide for Oracle Access Management
14.1.2 About 11g WebGate Configured as a Detached Credential Collector
With Oracle Access Manager 11.1.1, the Embedded Credential Collector (ECC) is the
default. The ECC was and is integrated with the OAM Server.
Access Manager 11.1.2 also supports the ECC by default. However, Access Manager
11.1.2 also enables you to configure an 11g WebGate to use a detached credential
Table 14–3 Run Time Processing Overview for Access Manager
Agent Type Description
11g WebGates
11g Access Clients
After installation and registration, 11g WebGates communicate with Access Manager
using the OAM Proxy to "sanitize" the request and respond identically for all agents.
Process overview, Authentication Request without OAMAuthnCookie: When a
request for a resource protected by Basic authentication scheme comes without an
authorization header (credentials)
1. WebGate redirects through the front channel to either Embedded or Detached
Credential Collector (depending on scheme configuration) to collect credentials.
2. Credential Collector collects user credentials based on the challenge method
defined for the authentication scheme.
3. User is authenticated; OAM Proxy (Embedded Collector) or Detached Collector
itself (DCC) communicates with the OAM Server through the back channel
protocol for the token and returns a response through the front channel with a
token issued by the OAM Server.
4. WebGate validates the response, extracts the authentication token issued by the
OAM Server, and sets a token in OAMAuthnCookie.
5. WebGate is redirected to the requested resource, with the newly set
OAMAuthnCookie attached.
6. WebGate validates the OAMAuthnCookie, performs authorization through the
back channel, and serves the page when authorization is successful.
Process overview, Basic Authentication: When a request for a resource protected by
Basic authentication scheme comes without an authorization header (credentials)
1. WebGate responds with
WWW-Authenticate
header containing the realm
mentioned in the authentication scheme with status code
401(authorization
required)
.
2. Browser client interprets the
WWW-Authenticate
header and collects credentials
from user.
3. Browser client performs request again with authorization header containing
credentials.
See Also:
"About 11g WebGate Configured as a Detached Credential Collector" on page 14-4
"About 11g WebGate Functionality for Mobile and Social" on page 14-5
10g Webgates
10g Access Clients
After installation and registration, 10g WebGates communicate directly with Access
Manager using the OAM proxy, which acts as a bridge.
See Also:
■IAMSuiteAgent for details about this agent and Application Domain.
■Chapter 30 for details about registering legacy 10g WebGates with Access
Manager.
■Appendix A for details about legacy 10g WebGates currently operating with Web
Applications coded for Oracle ADF Security and the OPSS SSO Framework.
■Oracle Fusion Middleware Application Security Guide for details about legacy 10g
Webgates configured as the Identity Assertion Provider (IAP) for SSO (for
applications using WebLogic container-based security with Access Manager 11g
(or Oracle Access Manager 10g).
OpenSSO Agents See Also: "Runtime Processing Between OpenSSO Agents and Access Manager" on
page 28-6.
OSSO Agent
(mod_osso 10g)
See: "Understanding OSSO Agents with Access Manager" on page 29-1.
Introduction to Agent Registration
Introduction to Agents and Registration 14-5
collector (DCC). The DCC is considered more secure when compared to the default
ECC.
An 11g WebGate configured to act as a DCC is known as an Authenticating WebGate.
WebGates that protect resources are known as Resource WebGates.
14.1.3 About 11g WebGate Functionality for Mobile and Social
WebGates interact with the client to perform authentication and authorization; this
involves redirection to collect credentials, set the cookie to hold the session, report
errors, and so on. WebGates work with browser clients, which usually have all the
support required for this interaction end to end. However, there are cases where a
non-browser client making REST calls directly needs to access resources and perform
authentication and authorization. This use case can be addressed with Mobile and
Social.
Mobile and Social support is enabled using two user-defined parameters within the
WebGate agent registration page. Mobile and Social services use a programmatic
non-browser client with Access Manager. For details, see the following
documentation.
■Part XI, "Managing Oracle Access Management Mobile and Social"
■Oracle Fusion Middleware Developer's Guide for Oracle Access Management
14.1.4 About the Pre-Registered 10g WebGate IAMSuiteAgent
This 10g WebGate and the companion Application Domain provides single sign-on
functionality for the IDM Administration Console. IAMSuiteAgent is installed and
pre-configured for this purpose as part of the initial OAM Server installation and
configuration.
Oracle strongly recommends that you do not alter IAMSuiteAgent and the companion
Application Domain. However, you can replace the IAMSuiteAgent with a fresh 10g
WebGate. For details, see the following sections.
■"Replacing the IAMSuiteAgent with an 11g WebGate" on page 15-42
■"Configuring Centralized Logout for IAMSuiteAgent" on page 30-10
■"Bundled 10g IAMSuiteAgent Artifacts" on page D-1
14.2 Introduction to Agent Registration
You can use either the Oracle Access Management Console or the remote registration
tool for Agent registration and updates. Unless explicitly stated, information in this
section applies to agent registration using either of these tools. This section provides
the following details.
■About Agent Registration, Keys, and Policies
■About File System Changes and Artifacts for Registered Agents
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"
Introduction to Agent Registration
14-6 Administrator's Guide for Oracle Access Management
14.2.1 About Agent Registration, Keys, and Policies
Administrators must register each Agent to operate with Access Manager. Only
registered agents can communicate with an OAM Server, and process information for
a user attempting to access a protected resource.
An agent key and partner key are created during registration. You can also create
policies to protect the application during agent registration. If you choose to
automatically create policies during agent registration, a host identifier and
Application Domain are created with basic policies and resource definitions. Later on,
you can view and manage the Application Domain and policies.
Following a successful registration (using either the console or remote registration
tool), the full agent registration appears in the Oracle Access Management Console
and is propagated to all Managed Servers in the cluster. Table 14–4 identifies the keys
and policies generated during agent registration.
Note: The agent is presumed to reside on the computer hosting the
application to be protected. However, it can reside on a proxy Web
server and the application on a different host.
Note: You can register multiple WebGates or Access Clients under a
single host identifier, with the same Application Domain and policies,
as follows:
1. When you register a WebGate, allow the process to create a host identifier
(a name of your choice), and enable "Auto Create Policies".
2. Register a second WebGate with the same host identifier as Step 1, and
clear the "Auto Create Policies" box to eliminate policy creation.
Table 14–4 Keys and Policies Generated During Agent Registration
Keys and Policies Accessible to Accessible through
One key per 11g WebGate Agent
One key for all 10g Agents
One key per OpenSSO Agent stored in
local Agent bootstrap file
One key per OSSO Agent
See Also: "About Key Use, Generation,
Provisioning, and Storage" on page 15-27
■OAM Server ■Client-side: Secure local storage
on the client host (a local wallet
file)
■Server side: The Java Keystore
Partner key for the application
(None for OpenSSO Agents)
■11g WebGate Client-side
Application Domain and default Policies
are generated during Agent registration on
demand:
■Named for the Agent
■Populated with default
authentication and authorization
policies (but not Token Issuance
Policies)
■Identified by the same host identifier
that was specified for the Agent
during registration
■Administrators can view, modify, or
remove a registered agent using either
the Oracle Access Management
Console or custom WLST commands
for Access Manager
■All agent types at run time monitor
attempts to access a Web site and use
OAM Servers to provide
authentication and authorization
services before completing the request
Oracle Access Management Console
Policy Configuration
Application Domains
DomainName
Introduction to Agent Registration
Introduction to Agents and Registration 14-7
14.2.2 About File System Changes and Artifacts for Registered Agents
When you register an agent using the Oracle Access Management Console, a new file
system directory is created for the Agent on the Oracle Access Management Console
host (AdminServer). This new directory includes generated files for the registered
agent, as described in Table 14–5.
Generated or updated artifacts must be copied from the console host (AdminServer)
into the agent's installation directory, as shown in Table 14–6.
Table 14–5 Artifacts Associated with Agent Registration
Registration Artifact Generated for ...
All WebGates or Access Client
ObAccessClient.xml
All WebGates/Access Clients on the console host (AdminServer).
During run time, periodic update checks are made. ObAccessClient is updated
automatically when a change is discovered.
Note: The pre-registered 10g IAMSuiteAgent does not use ObAccessClient.xml for
bootstrap or configuration.
See Also: Properties files generated on the client in this table.
cwallet.sso
11g WebGate only
11g WebGates, regardless of the transport security mode.
Certificate and password files for secure
communication
All WebGates/Access Clients. For example:
■password.xml (nominally encrypted file for Simple Mode Global passphrase)
■aaa_cert.pem (reserved name for WebGate certificate file, which cannot be
changed)
■aaa_key.pem (reserved name for WebGate key file, which cannot be changed)
Cert Mode:
■PEM keystore Alias
■PEM keystore Alias Password
Note: When editing an 11g WebGate registration, password.xml is updated only when
the mode is changed from Open to Cert or Simple to Cert. In Cert mode, once
generated, password.xml cannot be updated. Editing the agent Key Password does not
result in creation of a new password.xml.
See: Chapter 13 for details about Simple and Cert mode transport security)
OpenSSO Properties files See: Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
osso.conf file See: Chapter 29, "Registering and Managing Legacy OSSO Agents"
Table 14–6 Copying Generated Artifacts
Agent Type & Artifacts Copy Generated Artifacts to Agent Installation Directory ...
ObAccessClient.xml
(and 11g WebGate cwallet.sso)
11g WebGate or Access Client
Before agent startup, copy the ObAccessClient file (and cwallet.sso) from the
generated location (AdminServer (Console) host) to the agent installation directory.
See: Chapter 15, "Registering and Managing OAM 11g Agents"
ObAccessClient.xml
10g WebGate or Access Client
Before agent startup, copy ObAccessClient.xml from the generated location to the
agent installation directory. For example, from the AdminServer (Console) host:
Note: The pre-registered IAMSuiteAgent does not use ObAccessClient.xml and
should not be modified.
See: Chapter 30, "Registering and Managing 10g WebGates with Access Manager
11g"
OpenSSO Agent Properties Files See: Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
10g OSSO Agent osso.conf See: Chapter 29, "Registering and Managing Legacy OSSO Agents"
Introduction to Remote Registration
14-8 Administrator's Guide for Oracle Access Management
14.3 Introduction to Remote Registration
As an alternative to using the Console for agent registration, you can use the remote
registration utility, oamreg, with Oracle-provided templates. The user of the remote
registration script can be a part of any group that is mapped against the
Administrator's Role in the primary user-identity store for Access Manager
(Chapter 5).
Secure registration and creation of an Application Domain (as well as Symmetric key
generation) is supported using either remote registration mode described in
Table 14–7.
Symmetric key generation per Application: One key is generated and used per
registered mod_osso or 11g WebGate. However, one single key only is generated for all
10g WebGates.
Table 14–8 describes functionality that is not supported:
For more information on the registration modes, see the following sections:
■Performing In-Band Remote Registration
■Performing Out-of-Band Remote Registration
■Updating Agent Configuration Files
Chapter 15 has additional details.
14.3.1 Performing In-Band Remote Registration
Following is a brief overview of in-band Web server Administrator tasks for
provisioning an application using the remote registration tool. Unless explicitly stated,
tasks are the same regardless of the type of agent you have protecting resources.
In this overview, the term "Administrator" refers to any user within the network who
is part of the LDAP group that is designated for Administrators in the Default System
User Identity Store registered with Oracle Access Management.
Table 14–7 Remote Registration Methods
Method Description
In-band mode For Administrators within the network who manage the Web server that hosts
the agent can use this mode or the Oracle Access Management Console.
Out-of-band mode Administrators outside the network must submit registration requests to an
Administrator within the network. After processing the request, the in-band
Administrator returns the files required by the out-of-band Administrator who
uses the files to configure his environment.
Note: Registration of legacy Agents (10g WebGate, OpenSSO, and
OSSO 10g) is also supported.
Table 14–8 Remote Registration Does Not Support
Not Supported with Remote Registration
Persistence of the Key and Agent Information
Generation of Keys used by internal components
API support for reading Agent information
Introduction to Remote Registration
Introduction to Agents and Registration 14-9
1. Acquire the registration tool as described in "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. Update the input file with unique values for the agent and Application Domain as
described in "Creating Your Remote Registration Request" on page 15-34.
3. Run the registration tool to configure the Agent and create a default Application
Domain for the resources, as described in "Performing In-Band Remote
Registration" on page 15-34.
4. Validate the configuration as described in "Validating Remote Registration and
Resource Protection" on page 15-40.
5. Perform access checks to validate that the configuration is working, as described
in "Verifying Authentication and Access After Remote Registration" on page 15-40.
14.3.2 Performing Out-of-Band Remote Registration
The term out-of-band registration refers to manual registration that involves
coordination and actions by both the in-band Administrator and the out-of-band
Administrator. Following is a brief overview of out-of-band remote registration (when
the Agent is outside the network).
1. Out-of-band Administrator: Creates a starting request input file containing
specific application and agent details and submits it to the in-band Administrator.
■Acquire the registration tool as described in "Acquiring and Setting Up the
Remote Registration Tool" on page 15-33.
■Copy and edit a template to input unique values for the agent and Application
Domain as described in "Creating Your Remote Registration Request" on
page 15-34.
■Submit the starting request input file to the in-band Administrator using a
method you choose (email or file transfer).
2. In-band Administrator:
■Acquire the registration tool as described in "Acquiring and Setting Up the
Remote Registration Tool" on page 15-33.
■Use the out-of-band starting request with the registration tool to provision the
agent and create the following files to return to the out-of-band Administrator.
See "Performing Out-of-Band Remote Registration" on page 15-35 for details:
–agentName_Response.xml is generated for the out of band Administrator
to use in Step 3.
–OAM Agents: A modified ObAccessClient.xml file is created (and the 11g
WebGate cwallet.sso file), which the out-of-band Administrator can use to
bootstrap the WebGate.
11g WebGates: SSO wallet creation.
–OSSO Agents: A modified osso.conf file is created for the out-of-band
Administrator to bootstrap the OSSO module.
–OpenSSO Agents: A modified version of the OpenSSO properties files are
generated.
3. Out-of-band Administrator: Uses the registration tool with the agentName_
Response.xml file and copies the Agent configuration and any other generated
artifacts to the appropriate file system directory.
Introduction to Remote Registration
14-10 Administrator's Guide for Oracle Access Management
4. In-band Administrator: Validates the configuration as described in "Validating
Remote Registration and Resource Protection" on page 15-40.
5. Out-of-band Administrator: Performs several access checks to validate that the
configuration is working, as described in "Verifying Authentication and Access
After Remote Registration" on page 15-40.
14.3.3 Updating Agent Configuration Files
After a successful registration (or update), you must locate the Agent configuration
files on the AdminServer (console) host and copy these to the Agent host, as described
in Table 14–9.
Note: In
outofband
mode, the in-band Administrator uses the
starting request file submitted by the out-of-band Administrator, and
returns a generated agentName_Response.xml file to the out-of-band
Administrator for additional processing. The out-of-band
Administrator runs the remote registration tool with agentName_
Response.xml as input to generate agent configuration files.
See Also:
■"Updating Agent Configuration Files" on page 14-10
■"Understanding the Remote Registration Tool, Modes, and
Process" on page 15-24
Table 14–9 Agent Registration and Configuration Update Artifacts
Artifacts For ... Description
Simple or Cert mode If Simple or Cert mode is used, certificate artifacts must also be copied to
the Agent host following registration.
See Also: Appendix C, "Securing Communication"
11g OAM Agents
(WebGate/Access Client)
See Also: Chapter 15, "Registering and Managing OAM 11g Agents"
10g OAM Agents
(WebGate/Access Client)
See Also: Chapter 30, "Registering and Managing 10g WebGates with
Access Manager 11g"
OSSO Agent See Also: Chapter 29, "Registering and Managing Legacy OSSO Agents"
OpenSSO Agent See Also: Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
15
Registering and Managing OAM 11g Agents 15-1
15
Registering and Managing OAM 11g Agents
[14]
This chapter provides information on registration and management of 11g WebGates
(and the programmatic equivalent, Access Clients) using either the Oracle Access
Management Console or the remote registration command-line utility. During
registration, you can identify specific applications to be protected by Access Manager
policies.
This chapter includes the following topics:
■Before Registering and Managing Agents
■Understanding OAM Agent Registration Parameters in the Console
■Registering an OAM Agent Using the Console
■Configuring and Managing Registered OAM Agents Using the Console
■Understanding the Remote Registration Tool, Modes, and Process
■Understanding Remote Registration Templates: OAM Agents
■Performing Remote Registration for OAM Agents
■Introduction to Updating Agents Remotely
■Updating Agents Remotely
■Validating Remote Registration and Resource Protection
■Replacing the IAMSuiteAgent with an 11g WebGate
■Managing the Preferred Host in 10g WebGates
15.1 Before Registering and Managing Agents
Before you can perform tasks in this chapter, ensure that the Oracle Access
Management Console host (AdminServer) and a managed OAM Server are running.
See Also: The following, as needed for your environment.
■Chapter 14, "Introduction to Agents and Registration"
■"Managing Policies and Application Domains Remotely" on
page 25-82
■Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
■Chapter 29, "Registering and Managing Legacy OSSO Agents"
■Chapter 30, "Registering and Managing 10g WebGates with
Access Manager 11g"
Understanding OAM Agent Registration Parameters in the Console
15-2 Administrator's Guide for Oracle Access Management
15.2 Understanding OAM Agent Registration Parameters in the Console
This section describes OAM Agent registration parameters. Unless explicitly stated,
the information here applies equally to both 11g and 10g WebGates, including
programmatic Access Clients. Topics include:
■About Create OAM WebGate Page and Parameters
■About User-Defined WebGate Parameters
■About IP Address Validation for WebGates
15.2.1 About Create OAM WebGate Page and Parameters
The
Create OAM ... WebGate
page requests minimal information to streamline
registration. Required details are identified by the asterisk (*). Whether you register an
11g WebGate or 10g WebGate, the initial information requested is the same.
Figure 15–1 Create OAM 11g WebGate Page
Table 15–1 describes the Create page for 11g WebGates (or Access Clients). Unless
explicitly noted, all elements apply to both 11g and 10g Agents.
Understanding OAM Agent Registration Parameters in the Console
Registering and Managing OAM 11g Agents 15-3
Table 15–1 Elements on Create Pages for 11g and 10g OAM Agents
OAM WebGate Element Description
Version Specifies whether this will be a 10g or an 11g WebGate.
Name The unique identifying name for this Agent registration. This is often the name of the computer that
is hosting the Web server used by WebGate.
A unique identifying name for each Agent registration is preferred. However:
■If the Agent Name exists, no error occurs and the registration does not fail. Instead, Access
Manager creates the policies if they are not already in place.
■If the host identifier exists, the unique Agent Base URL is added to the existing host identifier
and registration proceeds.
Description A meaningful description of this Agent registration.
Base URL
Optional
The host and port of the computer on which the Web server for the WebGate is installed. For
example, http://example_host:port or https://example_host:port. The port number is optional.
Note: A particular Base URL can be registered once only. There is a one-to-one mapping from this
Base URL to the Web server domain on which the WebGate is installed (as specified with the Host
Identifier element). However, one domain can have multiple Base URLs.
Access Client Password
Optional
An optional, unique password for this WebGate, which can be assigned during this registration
process.
When a registered WebGate connects to an OAM Server, the password is used for authentication to
prevent unauthorized WebGates from connecting to OAM Servers and obtaining policy
information.
Security Level of communication transport security between the Agent and the OAM Server (this must
match the level specified for the OAM Server):
■Open--No transport security
■Simple--SSL v3/TLS v1.0 secure transport using dynamically generated session keys
■Cert--SSL v3/TLS v1.0 secure transport using server side x.509 certificates. Choosing this
option displays a field where you can enter the Agent Key Password.
Agent Key Password: The private key file (aaa_key.pem) is encrypted using DES algorithm.
The Agent Key Password is saved in obfuscated format in password.xml and is required by
the server to generate password.xml. However, this password is not retained by the server.
When editing an 11g WebGate registration, password.xml is updated only when the mode is
changed from Open to Cert or Simple to Cert. In Cert mode, once generated, password.xml
cannot be updated. Editing the Agent Key Password does not result in creation of a new
password.xml.
Note: For more information on Simple and Cert modes, and private key encryption, see
Appendix C.
Host Identifier This identifier represents the Web server host. This is automatically seeded with the value in the
agent Name field.
Note: You can register multiple OAM WebGates (or Access Clients) under a single host identifier
with the same Application Domain and policies, as follows:
1. When you register a WebGate, allow the process to create a host identifier (a name of your
choice), and enable "Auto Create Policies".
2. Register a second WebGate with the same host identifier as Step 1, and clear the "Auto Create
Policies" box to eliminate policy creation.
See Also: "About Virtual Web Hosting" on page 22-10.
User-defined Parameters Parameters you can enter to enable specific WebGate behaviors:
See Also: "About User-Defined WebGate Parameters" on page 15-5.
Virtual Host Check the box beside Virtual Host if you installed a WebGate on a Web server that contains
multiple Web site and domain names. The WebGate must reside in a location that enables it to
protect all of the Web sites on that server.
See Also: "About Virtual Web Hosting" on page 22-10.
Understanding OAM Agent Registration Parameters in the Console
15-4 Administrator's Guide for Oracle Access Management
Auto Create Policies During agent registration, you can have authentication and authorization policies created
automatically. This option is checked (enabled) by default.
Default: Enabled
Shared Registration and Policies: Multiple WebGates (or Access Clients) installed on different Web
servers can share a single registration and policies to protect the same resources. This is useful in a
high-availability failover environment. To do this:
1. WebGate1: Register the first WebGate and enable Auto Create Policies to generate a host
identifier (named as you like) and policies.
2. WebGate2: Register the second WebGate, specify the same host identifier as the first WebGate,
and disable Auto Create Policies.
After registering the second agent, both WebGates use the same host identifier and policies.
IP Validation Check the box beside IP Validation to ensure a client's IP address is the same as the IP address
stored in the ObSSOCookie generated for single sign-on. In the IP Validation Exceptions box, enter
any IP addresses to exclude from validation using standard notation for the addresses: for example,
10.20.30.123.
When enabled, the IP address stored in the ObSSOCookie must match the client's IP address.
Otherwise, the cookie is rejected and the user must re-authenticate.
Default: Disabled
See Also: "About IP Address Validation for WebGates" on page 15-10.
Agent Key Password Requested for only Cert mode communication, this passphrase is used to encrypt the private key
used for SSL communication between WebGate and the OAM Server in Simple and Cert modes.
Note: The Agent Key Password has no relationship to the Access Client Password described earlier
within this table.
Cert Mode: In this mode, the agent key can be different on the client and server; it is no longer
global. Administrators must enter the Agent Key Password to enable generation of a password.xml
file during agent registration, which must be copied to the agent side. For certificate generation,
you must encrypt the private key (used for SSL) using this password through
openssl
or other
third-party tools to be placed inside aaa_key.pem. At runtime, WebGate retrieves the key from
password.xml, and uses it to decrypt the key in aaa_key.pem.
■If the key is encrypted, WebGate internally invokes the call back function to obtain the
password.
■If the key is encrypted and password.xml does not exist, WebGate cannot establish
connections with the OAM Server.
■If the key is not encrypted, there is no attempt to read password.xml.
For more information, see Appendix C.
Resource Lists
Table 15–1 (Cont.) Elements on Create Pages for 11g and 10g OAM Agents
OAM WebGate Element Description
Understanding OAM Agent Registration Parameters in the Console
Registering and Managing OAM 11g Agents 15-5
To help streamline WebGate registration, some elements are concealed during the
create operation and default values are applied.
15.2.2 About User-Defined WebGate Parameters
Certain supported parameters can be defined by Administrators entering values
directly on the WebGate registration page or within the OAM Agent remote
registration request template. Table 15–2 describes supported user-defined parameters.
Each parameter can have only one value.
Protected Resource (URI)
List
URIs for the protected application: /
myapp/login
, for example. Each URI for the protected
application should be specified in a new row of the table for the Protected Resource List.
Default: /**
The default matches any sequence of characters within zero or more intermediate levels spanning
multiple directories.
Add Resources: Each URI should be specified in a new row of the table for the Protected Resource
List. Click the + button to add a resource to the Protected Resource List. For instance, if you add
/financial
(and repeat to add
/myfinancial
) the following URLS are seeded into the designated
policies of the Application Domain when Auto Create Policies is selected):
/financial yields Resource URL /financial/**
/myfinancial yields Resource URL /myfinancial/**
/**
See Also: "About the Resource URL, Prefixes, and Patterns" on page 25-18.
Public Resource (URI) List Each public application should be specified in a new row of the table for the Public Resource List.
Add Resources: Each URI should be specified in a new row of the table for the Public Resource
List. Click the + button to add a resource to the Public Resource List. For instance, if you add
/people
the following URLS are included here and in the Application Domain (when Auto Create
Policies is selected):
/people
See Also: "About the Resource URL, Prefixes, and Patterns" on page 25-18.
See Also: Table 15–3, " Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages"
Note: All changes made using the Oracle Access Management
Console are taken up without restarting the application server.
Changes are reflected automatically after the reconfiguration timeout
period.
Table 15–1 (Cont.) Elements on Create Pages for 11g and 10g OAM Agents
OAM WebGate Element Description
Understanding OAM Agent Registration Parameters in the Console
15-6 Administrator's Guide for Oracle Access Management
Table 15–2 User-Defined WebGate Parameters
User-Defined WebGate Parameter Description
ChallengeRedirectMethod Configure this user-defined authentication POST data preservation parameter for both
the embedded credential collector (ECC) and the detached credential collector (DCC).
Value: GET|POST|DYNAMIC
Note: Preference is given first to the Authentication Scheme containing this parameter;
second to the WebGate providing this user defined parameter. Otherwise, default
behavior is Dynamic.
See Also: Table 22–23, " User-Defined Challenge Parameters for Authentication
Schemes"
ChallengeRedirectMaxMessageBytes Configure this user-defined WebGate parameter to limit the size of the message data
received as obrareq.cgi and obrar.cgi. Message data is comprised of query string length,
if present (or POST data length, if POST data is present). If message size exceeds this
limit, the message is not processed and the existing message is shown in the browser.
The event is logged as usual.
Default: 8192 bytes
Notes:
obrareq.cgi is the authentication request in the form of a query string redirected from
WebGate to OAM Server.
obrar.cgi is the authentication response string redirected from the OAM Server to
WebGate.
See Also: "Configuring Authentication POST Data Handling" on page 22-90
Table 15–2, " User-Defined WebGate Parameters"
MaxPostDataBytes Authentication post-data preservation parameter for both the embedded credential
collector (ECC) and the detached credential collector (DCC).
This parameter requires a positive integer value that restricts the maximum number of
bytes of POST data that is submitted as user credentials and sent to the OAM Server.
Default: 8192 bytes
Assigning MaxPostDataBytes to a Resource WebGate gives preference to restricting the
size of the post data received from the application before forwarding the post data to be
preserved.
See Also: "Configuring the PasswordPolicyValidationScheme"
"Configuring Authentication POST Data Handling" on page 22-90
Table 22–23, " User-Defined Challenge Parameters for Authentication Schemes"
MaxPreservedPostDataBytes Configure this user-defined WebGate parameter (or user-defined Authentication Scheme
challenge parameter) for authentication POST-data preservation.
Default: 8192 bytes
Note: Preference is given first to the Authentication Scheme containing this parameter;
second to the WebGate providing this user-defined parameter. Otherwise, default
behavior is 8192 bytes.
This parameter defines the maximum length of POST data that WebGate can preserve. If
the size of inbound raw user POST data (or encrypted post data after processing),
crosses this limit, POST data is dropped and the existing authentication flow continues.
The event is logged as usual.
See Also: "Configuring Authentication POST Data Handling" on page 22-90
Table 22–23, " User-Defined Challenge Parameters for Authentication Schemes"
PostDataRestoration Authentication post-data preservation parameter for both the embedded credential
collector (ECC) and the detached credential collector (DCC). This parameter requires a
value of
true
or
false
.
Default:
false
When set to
true
, WebGate initiates POST data preservation.
See Also: "Configuring Authentication POST Data Handling" on page 22-90
Understanding OAM Agent Registration Parameters in the Console
Registering and Managing OAM 11g Agents 15-7
serverRequestCacheType
ECC Only
Authentication post-data preservation parameter by the embedded credential collector
(ECC).
This OAM Server parameter in oam-config.xml indicates mechanism to be used to
remember the request context. Possible values are FORM, COOKIE, or CACHE.
Default: COOKIE
FORM is the required value for POST data preservation.
See Also:
TempStateMode
in Table 22–23, " User-Defined Challenge Parameters for
Authentication Schemes".
"Configuring Authentication POST Data Handling" on page 22-90
UrlInUTF8Format=true In an environment that uses Oracle HTTP Server 2, this parameter must be set to true to
display latin-1 and other character sets.
ProxySSLHeaderVar=IS_SSL Uses when the WebGate is located behind a reverse proxy, SSL is configured between the
client and the reverse proxy, and non-SSL is configured between the reverse proxy and
the Web server. It ensures that URLs are stored as HTTPS rather than HTTP. The proxy
ensures that URLs are stored in HTTPS format by setting a custom header variable
indicating whether it is servicing an SSL or non-SSL client connection.
The value of the ProxySSLHeaderVar parameter defines the name of the header variable
the proxy must set. The value of the header variable must be "ssl" or "nonssl".
If the header variable is not set, the SSL state is decided by the SSL state of the current
Web server.
Default: IS_SSL
client_request_retry_attempts=1 WebGate-to-OAM Server timeout threshold specifies how long (in seconds) the WebGate
waits for the OAM Server before it considers it unreachable and attempts the request on
a new connection.
If the OAM Server takes longer to service a request than the value of the timeout
threshold, the WebGate abandons the request and retries the request on a new
connection.
Default: 1
Note: The new connection that is returned from the connection pool can be to the same
OAM Server, depending on your connection pool settings. Also, other OAM Servers
may also require more time to process the request than the time specified on the timeout
threshold. In some cases, the WebGate can retry the request until the OAM Servers are
shut down. You can configure a limit on the number of retries that the WebGate
performs for a non-responsive server using the client_request_retry_attempts parameter.
InactiveReconfigPeriod=10 The WebGate update thread reads the shared secret from the OAM Server every 1
minute when WebGate is active. The OAM Server server returns the shared secret in its
own cache (the OAM Server cache).
Default: 10 (minutes)
See Also: Oracle Fusion Middleware Performance and Tuning Guide
fallbackToContainerPolicy=true Used for the IAMSuiteAgent. When set to
false
, user access to the resource is denied
and an HTTP response code, 403 is returned.
When set to 'true' the request goes through to the container and uses whatever policy
(related to J2EE authentication/authorization) is configured on the container to grant or
deny the user access.
Default:
true
logoutRedirectUrl= Default = http://OAMServer_host:14200/oam/server/logout
protectWebXmlSecuredPagesOnly=tr
ue
Used for the IAMSuiteAgent. After the user is authenticated, this parameter is used for
all subsequent requests to determine if the Agent should validate the incoming request.
When set to:
false
: The Agent always validates the incoming request
true
: The default. The Agent determines whether to validate the incoming request based
on the following:
■If the application specifies 'CLIENT-CERT' as part of the construct:
"<auth-method>" in its web.xml, the Agent validates the incoming request.
■If the application does not specify 'CLIENT-CERT' as part of the construct:
"<auth-method>" in its web.xml, the Agent does not validate the incoming request.
Instead, the Agent lets the request go through to the application.
Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter Description
Understanding OAM Agent Registration Parameters in the Console
15-8 Administrator's Guide for Oracle Access Management
maxAuthorizationResultCacheElems Max Authorization Results Cache Elements—Number of elements maintained in the
Authorization Result Cache. This cache maintains information about authorization
results for associated sessions. For example:
maxAuthorizationResultCacheElems=10000
Default = 100000
See Also: Oracle Fusion Middleware Performance and Tuning Guide
authorizationResultCacheTimeout Authorization Results Cache Timeout—Number of elements maintained in the
Authorization Result Cache. This cache maintains information about authorization
results for associated sessions. For example:
authorizationResultCacheTimeout=60
Default, if no time is specified = 15 (seconds)
Note: Authorization Results Cache Timeout is not set by default.
With the cache enabled, the first request result persists for the cache duration. This
magnifies the effect causing a brief time delay. For example suppose you set an
authentication policy Response and set a custom session attribute exmpl:sample. The
corresponding authorization policy Response returns this as HEADER SESSION_ATTR_
EXMPL=sample. When a user access the URL protected by these policies, the header
comes after a few refreshes. Initially, however, the value might not be found.
A value of 0 disables the cache. With no cache, it takes two requests for the header
response to be filled. The first sets the session variable used, the second uses the session
variable. Oracle recommends that you do not set a Response value in the same
authorization request that triggers it.
See Also: Oracle Fusion Middleware Performance and Tuning Guide.
UniqueCookieNames Controls WebGate cookie name format:
■Legacy format (still the default and backward compatible): <prefix>_
<host>:<port>_<suffix>
■Enabled UniqueCookieNames format (rfc2109-compliant cookie name restriction):
<prefix>_<host>:<port>_<suffix>
■Disabled: Cookie name format is <prefix>_<suffix>. No <host>:<port> and No
<host>_<port> is added to the cookie name.
■Any other value is treated as the default legacy format: <prefix>_<host>:<port>_
<suffix>
11g WebGate only
SetKeepAlive By default, SetKeepAlive is ON. In this case, a first keep-alive message will be sent after
the default idle time of 2 minutes. To change this behavior, set a new value for the
parameter. If SetKeepAlive=Off, the feature is disabled and no keep-alive messages will
be sent. If SetKeepAlive=x (where x is some positive integer value), the keep-alive
message will be sent after the channel is idle for
x
minutes. Any firewall or load balancer
should be configured to forward the TCP/IP keep-alive messages to the actual end
parties (front-ending Access Manager server).
A programmatic way to change the idle time is implemented for Linux64, Linux32, and
Windows32 WebGates. This is not possible on SPARC Solaris platforms; in that case,
SetKeepAlive is enabled and the idle time out for Keep alive must be set manually by
the system administrator.
filterOAMAuthnCookie For 11g WebGate, a user-defined parameter (
filterOAMAuthnCookie
(default
true
)) can
be used to prevent the OAMAuthnCookie from being passed to downstream
applications for security consideration. If you do want to pass the cookie on, then set the
filterOAMAuthnCookie
parameter to
false
.
Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter Description
Understanding OAM Agent Registration Parameters in the Console
Registering and Managing OAM 11g Agents 15-9
ssoCookie Controls the OAMAuthnCookie cookie.
Default:
ssoCookie=httponly
ssoCookie=Secure
Disable either setting:
ssoCookie=disablehttponly
ssoCookie=disableSecure
Note: These parameters are configured differently depending on your credential
collector configuration.
■For detached credential collector-enabled 11g WebGates, set these parameters
directly in the agent registration page.
■For non-DCC agents (Resource WebGates), these parameters are configured
through user-defined challenge parameters in authentication schemes.
See Also:
Table 22–23, " User-Defined Challenge Parameters for Authentication Schemes"
"Configuring Challenge Parameters for Encrypted Cookies" on page 22-88
"Configuring 11g WebGates and Authentication Policy for DCC"
miscCookies Controls other miscellaneous Access Manager internal cookies. By default, httponly is
enabled for all other (miscellaneous) cookies.
Default:
miscCookies=httponly
miscCookies=Secure
Disable either setting:
miscCookies=disablehttponly
miscCookies=disableSecure
Note: These parameters are configured differently depending on your credential
collector configuration.
■For detached credential collector-enabled WebGates, set these parameters directly
in the agent registration page.
■For non-DCC agents (Resource WebGates), these parameters are configured
through challenge parameters of the same name.
See Also:
Table 22–23, " User-Defined Challenge Parameters for Authentication Schemes"
"Configuring Challenge Parameters for Encrypted Cookies" on page 22-88
"Configuring 11g WebGates and Authentication Policy for DCC"
obSSOCookieCoExConfig Controls the cookie properties set on ObSSOCookie during OAM 10g Co-Existence.
Default:
obSSOCookieCoExConfig=httponly
obSSOCookieCoExConfig=Secure
Disable either setting:
obSSOCookieCoExConfig=disablehttponly
obSSOCookieCoExConfig=disableSecure
Disable both settings:
obSSOCookieCoExConfig=disableSecure;disablehttponly
For detached credential collector-enabled 11g WebGates used for Co-Existence (as DCC
or with DCC Tunneling), set this parameter in the agent registration page. See the
Co-existence chapter in Oracle Fusion Middleware Migration Guide for Oracle Identity and
Access Management for more information.
Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter Description
Understanding OAM Agent Registration Parameters in the Console
15-10 Administrator's Guide for Oracle Access Management
15.2.3 About IP Address Validation for WebGates
IP address validation is a function that determines if a client's IP address is the same as
the IP address stored in the cookie generated for single sign-on. The
IPValidation
parameter turns IP address validation on and off; it is a WebGate specific parameter
found in the WebGate profile. If
IPValidation
is
true
, the IP address stored in the
cookie must match the client's IP address, otherwise, the SSO cookie (Table 1–2) is
rejected and the user must reauthenticate. By default,
IPValidation
is
false
. The
following is true in regards to enabling and disabling IP Validation.
■Enabling IP Validation on the WebGate automatically enables it on the OAM
server side; this can be verified in the Access Manager settings.
■Disabling IP Validation on the WebGate will not disable it on the OAM server.
OAMAuthAuthenticationServiceLoca
tion
11g WebGate non-browser client
functionality
Activates non-browser client functionality and defines the location of the authentication
service.
OAMAuthUserAgentPrefix
=prefix string that acts as the prefix for the "user-agent" HTTP
header value.
For example, to activate this functionality for Identity Connect:
OAMAuthAuthenticationServiceLocation=https://login.example.com/nbc
Non-browser client functionality is deactivated if the parameter is omitted (or is
provided with no value).
See Also: Section XI, "Managing Oracle Access Management Mobile and Social."
OAMAuthUserAgentPrefix
11g WebGate non-browser client
functionality
Activates non-browser client functionality and defines the string that acts as a prefix for
the "user-agent" http header value.
OAMAuthAuthenticationServiceLocation
=full URL location of the NBC authentication
service.
For example, to activate this functionality for Identity Connect:
OAMAuthUserAgentPrefix=NBC
Non-browser client functionality is deactivated if this parameter is omitted (or is
provided with no value).
See Also: Section XI, "Managing Oracle Access Management Mobile and Social."
RequestContextCookieExpTime Controls the time (in seconds) to expire OAMRequestContext cookie. Configuring the
cookie lifetime is an optional control for deployments with a critical need to handle
situations where the cookies could proliferate.
Default: not set
In the Resource WebGate registration, add this parameter to expire the
OAMRequestContext cookie in the configured number of seconds using the "Max-Age"
directive on all but IE browsers (default 5 minutes).
Note: For Internet Explorer only, this parameter requires a time sync between the
browser and Web server hosts because IE uses the "Expires" directive to expire the
cookie with an absolute time. However, on IE browsers, when this parameter is not set,
OAMRequestContext cookie is a transient session cookie.
On other (non-IE) browsers, the cookie is persistent and expires based on the time set
using the "Max-Age" directive.
See Also:
OAMRequestContext in Table 21–6, " SSO Cookies"
ProxyTrustedIPList Multi-valued parameter that holds the list of IP addresses of the trusted proxies or load
balancers. See Section 15.2.3.2.1, "Using ProxyTrustedIPList."
ProxyRemoteIPHeaderVar Specifies the name of the HTTP header that contains the list of IP addresses. See
Section 15.2.3.2.2, "Defining ProxyRemoteIPHeaderVar."
Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter Description
Understanding OAM Agent Registration Parameters in the Console
Registering and Managing OAM 11g Agents 15-11
■IP Validation on the OAM server side should be disabled manually, if and only if it
is disabled on all the WebGates.
■When IP Validation is enabled on the WebGate side, server side IP Validation
should never be turned off.
To configure single sign-on between WebGate and an Access Client that does not have
the client IP address at authentication, the IP validation option can be explicitly turned
off (set IP Validation to false). When the IP Validation parameter is set to false, the
browser or client IP address is not used as a part of the SSO cookie. However, Oracle
recommends that you keep IP validation on whenever possible. For WebGate profile
configuration information, see Section 15.4.3, "Viewing or Editing an OAM Agent
Registration Page in the Console." Additional details are in the following sections.
■Defining The IP Validation Exceptions List
■Enabling IP Validation in Load Balanced Environments
15.2.3.1 Defining The IP Validation Exceptions List
The IP Validation parameter can cause problems with certain Web application
deployments. For example, Web applications managed by a proxy server typically
change the user's IP address, substituting the IP address of the proxy. This prevents
single sign-on from using the cookie. The IP Validation Exceptions parameter lists IP
addresses that are exceptions to this process. When
IPValidation
is
true
, the IP
address is compared to the IP Validation Exceptions List. If the address is found on the
list, it does not need to match the IP address stored in the cookie.
You can add as many IP addresses as needed to the Exceptions list - the actual IP
addresses of the client and not the IP addresses stored in the ObSSOCookie SSO
cookie. If an SSO cookie is from one of the exception IP addresses, the Access System
ignores the address stored in the SSO cookie for validation. (The IP addresses in the IP
Validation Exceptions List can be used when the IP address in the cookie is for a
reverse proxy.)
15.2.3.2 Enabling IP Validation in Load Balanced Environments
In the case of (proxy servers or) a load balancer, Oracle Access Manager can not
enforce true IP validation because an attacker can use the IP address defined in the
exception list. Web applications managed thusly typically change the user's IP address
(substituting the IP address of the proxy or load balancer). This can prevent single
sign-on using the SSO cookie.
A load balancer adds an "X-forwarded-for" header variable to incoming HTTP
requests, containing a comma-space-separated list of the original IP number of the
requester. Consider the following example in which the request passed proxy1, proxy2
and proxy3 (proxy3 appears as the remote address of the request). The last IP address
is always the IP address that connects to the last proxy.
X-Forwarded-For: client1, proxy1, proxy2
The trust list will be referenced to look up each IP address from the header, starting
with the right-most value. The left-most IP address being the farthest downstream
client and each successive proxy that passed the request (adding the IP address from
which it received the request).
Note: Access Manager now supports Internet Protocol version 6
(IPv6) as well as IPv4.
Understanding OAM Agent Registration Parameters in the Console
15-12 Administrator's Guide for Oracle Access Management
Within the specified order, the first IP address that does not match any of those in the
trusted list is treated as an apparent client IP (defined as the IP address of the initiator
of the connection to the furthest node along the communication path that can be
trusted). Additionally:
■When all IP addresses from the header (starting from the right side) match with
entries in the trusted list, WebGate chooses the end client IP (the left most IP
address in the header).
■When the IP address is determined, WebGate obtains a session token that contains
the apparent client IP address and IP validation is evaluated by comparing the IP
address against the address in the session token.
■When the IP validation feature is enabled within a load balanced deployment,
authentication (session creation) and authorization is done by the WebGate with
this feature; otherwise the authenticated user must re-authenticate. When
WebGate searches for the particular HTTP header, the search is case-insensitive.
For example, "X-Forwarded-For" and "X-FORWARDED-FOR" are treated the same.
15.2.3.2.1 Using ProxyTrustedIPList
ProxyTrustedIPList
is a user defined, multi-valued
WebGate parameter that holds the list of IP addresses for the trusted proxies or load
balancers. The values are space separated. The IP addresses in the IP Validation
Exceptions List can be used when the IP address in the cookie is for a reverse proxy.
Figure 15–2 Load Balanced Deployment
In Figure 15–2, the end user's HTTP request passes through REVERSEPROXY1 and
REVERSEPROXY2 to reach the actual Web server. In this case, the IP addresses of
REVERSEPROXY1 and REVERSEPROXY2 should be added in the ProxyTrustedIPList
list as follows:
ProxyTrustedIPList=10.77.199.59 10.77.199.26
15.2.3.2.2 Defining ProxyRemoteIPHeaderVar The ProxyRemoteIPHeaderVar parameter
specifies the name of the HTTP header that contains the list of IP addresses. If this
parameter is not provided, the default header X-Forwarded-For is used. This
parameter can be configured like any other user-defined parameter in a WebGate
profile. For example, in the deployment described in Using ProxyTrustedIPList,
"X-FORWARDED-FOR" and other headers that come to the Web server take the
following form.
HTTP_X_FORWARDED_FOR="10.77.199.129, 10.77.199.59"
REMOTE_ADDR="10.77.199.26"
Note: In a centralized authentication deployment, if any Resource
WebGate (RWG) or Authentication WebGate (AWG) is behind a proxy,
the IP addresses of all intermediaries must be configured (in the
ProxyTrustedIPList
parameter) in the profile of the WebGate behind
the proxy. Otherwise, IP validation failures can occur.
Registering an OAM Agent Using the Console
Registering and Managing OAM 11g Agents 15-13
15.3 Registering an OAM Agent Using the Console
This procedure is for both a WebGate or programmatic Access Client. Registration
steps are the same. You can register an OAM-type agent before you deploy it. Users
with valid Administrator credentials can perform the following task to register a
WebGate using the Oracle Access Management Console.
After agent registration, you can change the communication mode of the OAM Server
if needed. Communication between the agent and server continues to work as long as
the WebGate mode is at least at the same level as the OAM Server mode or higher. See
Appendix C.
Before you begin, confirm that at least one OAM Server is running in the same mode
as the agent to be registered.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, select Create WebGate from the Agents
menu.
3. On the Create WebGate page, enter required details (those with an *) to register
this Agent.
4. Protected Resource List: In this table, enter individual resource URLs to be
protected by this Agent, as shown in Table 15–1.
5. Public Resource List: In this table, enter individual resource URLs to be public
(not protected), as shown in Table 15–1.
6. Auto Create Policies: Check to create a fresh Application Domain and policies (or
clear and use the same host identifier as another WebGate and share policies
(Table 15–1)).
7. Click Apply to submit the registration.
You may also close the page without applying changes, if applicable.
8. Click the Download button to download the generated artifacts.
Downloaded artifacts are located in the
$DOMAIN_HOME
/output/
$Agent_name
folder.
9. 10g WebGate: See Chapter 30 and:
a. Proceed as needed for your environment (Chapter 30):
Existing WebGate: Perform Step 8, then go to Chapter 27, "Configuring
Centralized Logout for Sessions Involving 11g WebGates".
See Also:
■Understanding OAM Agent Registration Parameters in the
Console
■Oracle Fusion Middleware Installation Guide for Oracle Identity
and Access Management chapter "Installing and Configuring
Oracle HTTP Server 11g WebGate for OAM"
Note: If you are creating an OAM 10g Agent, also see Chapter 30.
Configuring and Managing Registered OAM Agents Using the Console
15-14 Administrator's Guide for Oracle Access Management
New WebGate: Go to "Locating and Installing the Latest 10g WebGate for
Access Manager 11g" on page 30-14.
10. Copy the artifacts as follows (or install WebGate with the same specifications, then
copy artifacts), including any Simple or Cert mode files. For example, Open mode
files include:
11. Verify Registration: These are similar to steps in "Validating Agent Registration
using the Oracle Access Management Console".
a. Under Agents in Application Security, search and confirm the Agent name is
listed.
b. Confirm the Agent’s page contains the appropriate information.
c. Auto Create Policies: Confirm the Application Domain was generated, the
host identifier was created for the application, and that resources were created
in the Application Domain and associated with the host identifier.
d. Perform further tests, as described in "Verifying Authentication and Access
After Remote Registration".
12. Proceed as needed for your deployment:
■"Configuring and Managing Registered OAM Agents Using the Console"
■Part VI, "Managing Access Manager SSO, Policies, and Testing"
15.4 Configuring and Managing Registered OAM Agents Using the
Console
This section provides the following topics to help you manage registered WebGates:
■Understanding Registered OAM Agent Configuration Parameters in the Console
■Searching for an OAM Agent Registration
■Viewing or Editing an OAM Agent Registration Page in the Console
■Deleting OAM Agent Registration Using the Console
15.4.1 Understanding Registered OAM Agent Configuration Parameters in the Console
Whether you registered the agent using the Oracle Access Management Console or the
remote registration utility, you can view the full agent configuration page in the
console, as shown in Figure 15–3.
Agent & Artifacts Artifacts
11g WebGate/Access Client
ObAccessClient.xml and
cwallet.sso
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config
10g WebGate/Access Client
ObAccessClient.xml
Note: Go to Chapter 30 before
completing this task.
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host:
$10gWG_install_dir/oblix/lib/
Configuring and Managing Registered OAM Agents Using the Console
Registering and Managing OAM 11g Agents 15-15
Figure 15–3 Expanded 11g WebGate Page with Defaults
There are only a few differences between 11g and 10g WebGate registration pages.
Table 15–3 describes elements on an expanded registration. Additional settings
revealed here are used by the OAM Proxy.
Note: Most elements on the agent's page are the same as those you
define when using the remote registration tool with the expanded
OAM template.
ObAccessClient.xml
is populated with values after
agent registration or modification, regardless of the method you use.
Configuring and Managing Registered OAM Agents Using the Console
15-16 Administrator's Guide for Oracle Access Management
Table 15–3 Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element Description
Name
Vers i on
Description
Access Client Password
Security
User-defined Parameters
IP Validation
See: Table 15–1, " Elements on Create Pages for 11g and 10g OAM Agents".
See Also: "About User-Defined WebGate Parameters" on page 15-5
See Also: "About IP Address Validation for WebGates" on page 15-10.
Primary Cookie Domain
10g WebGate only, Chapter 30
This parameter describes the Web server domain on which the Agent is deployed,
for instance,.example.com.
You must configure the cookie domain to enable single sign-on among Web servers.
Specifically, the Web servers for which you configure single sign-on must have the
same Primary Cookie Domain value. WebGate uses this parameter to create the
ObSSOCookie authentication cookie.
This parameter defines which Web servers participate within the cookie domain and
have the ability to receive and update the ObSSOCookie. This cookie domain is not
used to populate the ObSSOCookie; rather it defines which domain the
ObSSOCookie is valid for, and which Web servers have the ability to accept and
change the ObSSOCookie contents.
Default: If the client side domain can be determined during registration, the Primary
Cookie Domain is populated with that value. However, if no domain is found, there
is no value and WebGate uses the host-based cookie.
Note: The more general the domain name, the more inclusive your single sign-on
implementation will be. For example, if you specify b.com as your primary cookie
domain, users will be able to perform single sign-on for resources on b.com and on
a.b.com. However, if you specify a.b.com as your primary cookie domain, users will
have to re-authenticate when they request resources on b.com.
State
Only in the console.
Specifies whether this registration is enabled or disabled.
Default = Enabled
Max Cache Elements Number of elements maintained in the cache. Caches are the following:
■Resource to Authentication Scheme—This cache maintains information about
Resources (URLs), including whether it is protected and, if so, the
authentication scheme used for protection.
■(11g WebGate only) Resource to Authorization Policy—This cache maintains
information about Resources and associated authorization policy—This cache
stores authentication scheme information for a specific authentication scheme
ID.
The value of this setting refers to the maximum consolidated count for elements in
these caches.
Default = 100000
Cache Timeout (seconds) Amount of time cached information remains in the WebGate caches (Resource to
Authentication Scheme, Authentication Schemes, and 11g WebGate only Resource to
Authorization Policy) when the information is neither used nor referenced.
Default = 1800 (seconds)
Token Validity Period (seconds)
11g WebGate only
Maximum valid time period for an agent token (the content of OAMAuthnCookie
for 11g WebGate). This value is the validity period for the obsso cookie. Within this
period, only authorization nap calls will pass to the OAM server. Once this period
has passed, the obsso cookie will be considered invalid and an 'obrareq.cgi' redirect
will occur. The OAM Server will validate the OAM_ID cookie and re-issue a new
obsso cookie, or challenge the user if the server side session is
expired/deleted/timed out).
Default = 3600 (seconds)
Note: For 10g WebGates, use Cookie Session Time to set the Token Validity Period.
Max Connections The maximum number of connections that this WebGate can establish with the
OAM Server. This number must be the same as (or greater than) the number of
connections that are actually associated with this agent.
Default = 1
Configuring and Managing Registered OAM Agents Using the Console
Registering and Managing OAM 11g Agents 15-17
Max Session Time (hours) Maximum time to keep network connections from this WebGate to the OAM Server
alive. After elapsed time, all the WebGate to OAM Server network connections will
be shutdown and replaced with new ones. The unit is based on the
maxSessionTimeUnits
user-defined parameter which can be 'minutes' or 'hours'.
When
maxSessionTimeUnits
is not defined, the unit is defaulted to 'hours'.
Failover Threshold Number representing the point when this WebGate opens connections to a
Secondary OAM Server.
Default = 1
For example, if you type 30 in this field and the number of connections to primary
OAM Server falls to 29, this Agent opens connections to secondary OAM Server.
AAA Timeout Threshold Number (in seconds) to wait for a response from the OAM Server. If this parameter
is set, it is used as an application TCP/IP timeout instead of the default TCP/IP
timeout.
Default = -1 (default network TCP/IP timeout is used)
If using a simple mode WebGate, you can improve the response time of the OAM
login page by changing the
aaaTimeoutThreshold
time parameter in the WebGate
profile from -1 to 10.
A typical value for this parameter is between 30 and 60 seconds. If set to a very low
value, the socket connection can be closed before a reply from OAM Server is
received, resulting in an error.
For example, suppose a WebGate is configured to talk to one primary OAM Server
and one secondary OAM Server. If the network wire is pulled from the primary
OAM Server, the WebGate waits for the TCP/IP timeout to learn that there is no
connection to the primary OAM Server. The WebGate tries to reestablish the
connections to available servers starting with the primary OAM Server. Again, the
Agent waits for the TCP/IP timeout to determine if a connection can be established.
If it cannot, the next server in the list is tried. If a connection can be established to
another OAM Server (either a primary or secondary), the requests are re-routed.
However this can take longer than desired.
When finding new connections, WebGate checks the list of available servers in the
order specified in its configuration. If there is only one primary OAM Server and
one secondary OAM Server specified, and the connection to the primary OAM
Server times out, the Agent still tries the primary OAM Server first. As a result, the
Agent cannot send requests to an OAM Server for a period greater than twice the
setting in the OAM Server Timeout Threshold.
If the OAM Server takes longer to service a request than the value of the timeout
threshold, the Agent abandons the request and retries the request on a new
connection. Note that the new connection that is returned from the connection pool
can be to the same OAM Server, depending on your connection pool settings. Also,
other OAM Server may also take longer to process the request than the time
specified on the threshold. In these cases, the Agent can continue to retry the request
until the OAM Server is shut down.
ServerConnectionReadTimeout This parameter can be configured in the ASDK Agent User Defined Parameters
section, for further timeout fine-tuning. This setting can be configured for TCP read
timeout if required. The read timeout is the timeout on waiting to read data.
Specifically, if the server fails to send a byte n seconds after the last byte, a read
timeout error will be raised.
poolTimeOut This parameter can be configured in the ASDK Agent User Defined Parameters
section. poolTimeout is the maximum time a request thread will wait to get a
connection from the connection pool, before throwing an exception. The default is 30
seconds.
Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element Description
Configuring and Managing Registered OAM Agents Using the Console
15-18 Administrator's Guide for Oracle Access Management
Idle Session Timeout
10g WebGate only, Chapter 30
Default: 3600
Release 7.0.4 WebGates enforced their own idle session timeout only.
10.1.4.0.1 WebGates enforced the most restrictive timeout value among all WebGates
the token had visited.
With 10g (10.1.4.3), the 7.0.4 behavior was reinstated as the default with this element.
To set Idle Session Timeout logic:
■The default value of
leastComponentIdleTimeout
instructs the WebGate to use
the most restrictive timeout value for idle session timeout enforcement.
■A value of
currentComponentIdleTimeout
instructs the WebGates to use the
current WebGate timeout value for idle session timeout enforcement.
The idle session timeout behavior varies across WebGate versions. For example,
with WebGate 10.1.4.3 it is used to control idle timeout. If both Idle Session Timeout
and Cookie Session Time are set, the obsso cookie will be considered invalid when
one of the events happens (idle session timeout/cookie session time). In this case,
the request will go to the OAM server which will use server side parameter
validation to decide if the session has timed out/expired followed by a credential
challenge or obsso cookie reissue.
Preferred Host Specifies how the hostname appears in all HTTP requests as users attempt to access
the protected Web server. The hostname within the HTTP request is translated into
the value entered into this field regardless of the way it was defined in a user's
HTTP request.
The Preferred Host function prevents security holes that can be inadvertently
created if a host's identifier is not included in the Host Identifiers list. However, it
cannot be used with virtual Web hosting. For virtual hosting, you must use the Host
Identifiers feature.
Defaults to Name (of WebGate registration)
User Defined Parameters See Also: "About User-Defined WebGate Parameters" on page 15-5 and Oracle
Fusion Middleware Performance and Tuning Guide
Logout URL
10g and 11g WebGates
The Logout URL triggers the logout handler, which removes the cookie
(ObSSOCookie for 10g WebGates; OAMAuthnCookie for 11g WebGates) and
requires the user to re-authenticate the next time he accesses a resource protected by
Access Manager.
Default = [] (not set)
Note: This is the standard 10g WebGate configuration parameter used to trigger
initial logout through a customized local logout page as described in "Configuring
Centralized Logout for 10g WebGate with 11g OAM Servers" on page 30-22.
Additional Logout for 11g WebGate Only For 11g WebGate single sign-off behavior, specific logout elements and values
automate the redirect to a central Logout URL, callback URL, and end_URL.
See Also: Table 27–2, " Logout Details After Registration (ObAccessClient.xml)"
Logout Callback URL
11g WebGate only
The URL to
oam_logout_success
, which clears cookies during the call back. This can
be a URI format without host:port (recommended), where the OAM Server calls back
on the host:port of the original resource request. For example:
Default = /oam_logout_success
This can also be a full URL format with a host:port, where OAM Server calls back
directly without reconstructing callback URL.
Note: In the remote registration template this parameter is named
logoutCallbackUrl (Table 15–10).
See Also: Table 27–2, " Logout Details After Registration (ObAccessClient.xml)"
Logout Redirect URL
11g WebGate only
This parameter is automatically populated after agent registration completes.By
default, this is based on the OAM Server host name with a default port of 14200. For
example:
Default = http://OAMServer_host:14200/oam/server/logout
See Also: Table 27–2, " Logout Details After Registration (ObAccessClient.xml)"
Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element Description
Configuring and Managing Registered OAM Agents Using the Console
Registering and Managing OAM 11g Agents 15-19
Logout Target URL
11g WebGate only
The value is the name for the query parameter that the OPSS applications passes to
WebGate during logout; the query parameter specifies the target URL of the landing
page after logout completes.
Default: end_url
Note: The end_url value is configured using param.logout.targeturl in
jps-config.xml.
See Also: Table 27–2, " Logout Details After Registration (ObAccessClient.xml)"
Sleep for (seconds) The frequency (in seconds) with which the OAM Server checks its connections to the
directory server. For example, if you set a value of 60 seconds, the OAM Server
checks its connections every 60 seconds from the time it comes up.
Default: 60 (seconds)
Cache Pragma Header
Cache Control Header
WebGate only (not Access Clients)
These settings apply only to WebGates and control the browser's cache.
By default, both parameters are set to no-cache. This prevents WebGate from
caching data at the Web server application and the user's browser.
However, this may prevent certain operations such as downloading PDF files or
saving report files when the site is protected by a WebGate.
You can set the Access Manager SDK caches that the WebGate uses to different
levels. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html section 14.9
for details.
All of the cache-response-directives are allowed. For example, you may need to set
both cache values to public to allow PDF files to be downloaded.
Defaults: no-cache
Note: Browsers may store a local cached copy of content served by an OAM
protected resource. Some browsers, including Internet Explorer, cache content
accessed via HTTPS which may be retrieved by other users who have access to the
same computer at a future time. Please ensure that the Cache Directives are set
based on the sensitivity of the application content.
See Also: Oracle Fusion Middleware Performance and Tuning Guide
Debug Debugging can be enabled or not.
Deny on Not Protected
WebGates only (not Access Clients)
Oracle recommends enabling Deny On Not Protected.
When enabled, this element denies access to all resources to which access is not
explicitly allowed by a rule or policy. Enabling this can limit the number of times the
WebGate queries the OAM Server, and can improve performance for large or busy
Application Domains.
■11g WebGate: Always enabled, and cannot be changed
■10g WebGate: Can be disabled.
Important: Deny on Not Protected overrides Host Identifiers and Preferred Host.
Oracle recommends enabling Deny on Not Protected. Otherwise security holes can
occur in large installations with multiple Host Identifiers, virtual hosts, and other
complex configurations.
Allow Management Operations This Agent Privilege function enables the provisioning of session operations per
agent, as follows:
■Terminate session
■Enumerate sessions
■Add or Update attributes for an existing session
■List all attributes for a given session ID or read session
Default: Disabled
Note: Only privileged agents can invoke session management operations. When this
parameter is enabled, session management requests (listed above) are processed by
the OAM Server. If disabled, such requests are rejected for the agent.
11g WebGate only
Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element Description
Configuring and Managing Registered OAM Agents Using the Console
15-20 Administrator's Guide for Oracle Access Management
15.4.2 Searching for an OAM Agent Registration
Figure 15–4 shows the WebGates Search controls, defaults, and the empty Search
Results table. From this page you can create a new WebGate registration, or search for
a specific WebGate or group of WebGates (all 11g WebGates, for instance).
Allow Credential Collector Operations
11.1.2.0.0 and later WebGate only
Activates WebGate detached credential collector functionality for simple-form or
dynamic multi-factor authentication.
Default: Disabled
See Also: "Configuring 11g WebGates and Authentication Policy for DCC"
Allow Master Token Retrieval Allows the ASDK code to retrieve the OAM_ID cookie.
Allow Token Scope Operations Allows the ASDK code to scope the OAM_ID cookie to the domain level instead of
host level.
Sharepoint Impersonation User
10g WebGate only, Chapter 30
The trusted user for impersonation, in Active Directory. This user should not be
used for anything other than impersonation. The constraints are the same as any
other user in Active Directory.
Note: SharePoint impersonation is separate and distinct from the Access Manager
user impersonation feature described in the Oracle Fusion Middleware Developer's
Guide for Oracle Access Management.
Sharepoint Impersonation Password
10g WebGate only, Chapter 30
This is the trusted user password for impersonation. The constraints are the same as
any other user password in Active Directory.
Oracle recommends that the user choose a very complex password, because the
trusted user is granted powerful permissions. Also, check the box
Password Never
Expires
. The impersonation module should be the only entity that ever sees the
trusted user account. It is extremely difficult for an outside agency to discover that
the password has expired.
Primary Server List Identifies Primary Server details for this Agent. The default is based on the OAM
Server:
■Server Name
■Host Name
■Host Port
■Max Number (maximum connections this WebGate will establish with the
OAM Server (not the maximum total connections the WebGate can establish
with all OAM Servers).)
Secondary Server List Identifies Secondary OAM Server details for this agent, which must be specified
manually:
■Server Name
■Host Name
■Host Port
■Max Number (maximum connections this WebGate will establish with the
OAM Server (not the maximum total connections the WebGate can establish
with all OAM Servers).)
Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element Description
Configuring and Managing Registered OAM Agents Using the Console
Registering and Managing OAM 11g Agents 15-21
Figure 15–4 WebGate Search Controls and Create Button
If you do not know the exact name, you can use a wild card (*) in the search string.
From the search results table, you can choose an name to open and view or edit the
registration page.
The controls available on this page are described in Table 15–4. Most of the controls
apply to all three (WebGates, OSSO Agents and OpenSSO Agents) tabs; controls
specific to each tab are marked accordingly.
Table 15–4 Agent Search Controls
Control Description
Create WebGate
Create OSSO Agent
Create OpenSSO Agent
Click to open a fresh WebGate registration page.
Click to open a fresh OSSO Agent registration page.
Click to open a fresh OpenSSO Agent registration page.
Name Enter the name (or partial name and wild card (*)) as defined on the
registration page. For example: entering a* could return Agent_WebGate_
AccessDebugNew in the result table.
Vers i on
(Webgates tab only)
Choose a WebGate version to narrow the search and results:
■11g
■10g
Preferred Host
(Webgates tab only)
Enter all (or part of with a wild card (*)) hostname as it appears in HTTP
requests. For example: iam* could return IAMSuiteAgent in the result
stable.
State
(Webgates tab only)
Choose a state to narrow the search and results:
■Enabled
■Disabled
Primary Server
(Webgates tab only)
Enter the entire (or partial with a wild card (*)) Primary Server name.
Secondary Server
(Webgates tab only)
Enter the entire (or partial with a wild card (*)) Secondary Server name.
Agent ID
(OSSO Agents tab only)
Enter the entire (or partial with a wild card (*)) Agent ID value.
Configuring and Managing Registered OAM Agents Using the Console
15-22 Administrator's Guide for Oracle Access Management
Before you begin, the Agent must be a registered agent of Access Manager.
1. In the Oracle Access Management Console, click Application Security at the top of
the window.
2. In the Application Security console, click Agents.
3. If not already displayed, select the desired agent type tab.
4. Find:
■All Enabled: Select Vers ion Al l, State All, and click the Search button.
■An Agent ID (OSSO Agents tab only): enter the desired Agent ID into the
Agent ID field.
■An Agent Type (OpenSSO Agents tab only): from the Agent Type drop-down
list, select J2EE or Web, as appropriate for your search.
■A WebGate Version: From the Versi on list, choose 10g or 11g and click the
Search button.
■An Agent/WebGate Name: In the text field, enter the exact name of the
instance you want to find and click the Search button. For example:
my_OAM_WebGate
5. Click the Search Results tab to display the results table, then:
■Edit or View: Click the Edit command button in the tool bar to see the
configuration page.
■Delete: Proceed to "Deleting OAM Agent Registration Using the Console" on
page 15-23.
■Detach: Click Detach in the tool bar to expand the table to a full page.
■Reconfigure Table: Select a View menu item to alter the appearance of the
results table.
6. Apply any changes (or dismiss the page) when you finish.
15.4.3 Viewing or Editing an OAM Agent Registration Page in the Console
This procedure is the same whether you are editing a WebGate or Access Client
registration. Users with valid Administrator credentials can change any setting for
registered WebGates and programmatic Access Clients using the Oracle Access
Management Console, as described in the following procedure. For example, you
might want to revise the time-out threshold or other settings used by the OAM Proxy.
After changes, updated details are propagated through a runtime configuration
update process. There is usually no need to copy the artifacts over to the WebGate
configuration area. (Artifacts need only be copied to the WebGate directory path if the
agent name, access client password, or security mode is changed.)
Agent Type
(OpenSSO Agents tab only)
Select the target Agent type:
■J2EE
■Web
Table 15–4 (Cont.) Agent Search Controls
Control Description
Configuring and Managing Registered OAM Agents Using the Console
Registering and Managing OAM 11g Agents 15-23
Before you begin, the agent must be registered and available in the Oracle Access
Management Console.
1. From the Oracle Access Management Console, click SSO Agents.
a. Double-click OAM Agents node to display the Search page.
b. Find the Registration: See "Searching for an OAM Agent Registration".
c. Click the Agent name in the results table to open the page.
2. Modify Agent details, and Primary or Secondary Server details, as needed
(Table 15–1, Table 15–3).
3. User-Defined Parameters: Add or modify these as desired (Table 15–2).
4. Click Apply to submit changes and dismiss the Confirmation window (or close
the page without applying changes).
5. Copy the artifacts as follows (or install WebGate with the same specifications, then
copy artifacts), including any Simple or Cert mode files. For example, Open mode
files include:
6. Proceed as needed for your deployment:
Part VI, "Managing Access Manager SSO, Policies, and Testing".
15.4.4 Deleting OAM Agent Registration Using the Console
Users with valid Administrator credentials can perform the following procedure to
delete a registered WebGate or Access Client from the Oracle Access Management
Console.
Note: All changes made using the Oracle Access Management
Console are taken up without restarting the application server, and are
reflected automatically after the reconfiguration time-out period.
See Also:
■About Create OAM WebGate Page and Parameters
Agent & Artifacts Artifacts
11g WebGate/Access Client
ObAccessClient.xml and
cwallet.sso
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config.
10g WebGate/Access Client
ObAccessClient.xml
Note: Go to Chapter 30 before
completing this task.
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host
$10gWG_install_dir/oblix/lib/ObAccessClient.xml
Note: Deleting an agent registration removes only the registration
(not the associated host identifier, Application Domain, resources, or
the agent itself).
Understanding the Remote Registration Tool, Modes, and Process
15-24 Administrator's Guide for Oracle Access Management
Before you begin, evaluate the Application Domain, resources, and policies associated
with this agent and ensure that these are configured to use another agent (or be
removed).
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
a. In the Application Security console, click Agents to display the Search page.
b. Find the Registration: See "Searching for an OAM Agent Registration".
c. Select the desired registration from the results table, and open it to confirm it
is the right agent to remove, close the page.
d. Select the name in the results table, click the Delete (X) button, check the
Confirmation dialog and then close the page.
e. Confirm the Agent name is no longer listed in the navigation tree.
2. Remove the 10g Agent Instance: Perform the following steps (see "Removing a
10g WebGate from the Access Manager 11g Deployment" on page 30-27, if
needed).
a. Shut down the Web server.
b. Remove WebGate software using the utility provided in the following
directory path:
$WebGate_install_dir/oui/bin
Windows: setup.exe -d
Unix: runInstaller -d
c. Revert to the httpd.conf version before updates for WebGate. For example:
Copy: httpd.conf.ORIG
To: httpd.conf
d. Restart the Web server.
e. On the agent host, manually remove the WebGate instance directory:
11g WebGate/Access Client: $11gWebGate_instance_dir/WebGate/config.
10g WebGate/Access Client: $WebGate_install_dir/oblix/lib/
15.5 Understanding the Remote Registration Tool, Modes, and Process
As an alternative to using the console for agent registration, you can use the remote
registration utility, oamreg, with Oracle-provided templates. Administrators using the
Oracle Access Management Console or remote registration utility must have
credentials stored in the System Store (Chapter 5).
This section provides details about remote registration in the following topics:
■About Remote Registration Command Arguments and Modes
■Common Elements within Remote Registration Request Templates
■About Key Use, Generation, Provisioning, and Storage
See Also:
■Understanding OAM Agent Registration Parameters in the
Console
Understanding the Remote Registration Tool, Modes, and Process
Registering and Managing OAM 11g Agents 15-25
15.5.1 About Remote Registration Command Arguments and Modes
Before using the remote registration tool, two environment variables within the script
must be set as shown in the samples in Table 15–5, which presume the location of the
tool to be $OAM_REG_HOME on a Linux system. Your environment might be
different.
Additionally, before using the remote registration tool, you must modify several tags
in the request file, as described later (Table 15–9).
The arguments required to run the remote registration script are listed in Table 15–6.
The sample commands illustrated in Table 15–7 presume the location of the tool to be
$OAM_REG_HOME on a Linux system.
See Also: "Introduction to Remote Registration" on page 14-8
Table 15–5 Environment Variables to Set within oamreg
Environment Variable Description
OAM_REG_HOME The directory under which RREG.tar was exploded, followed by
/rreg:
$OAM_HOME/oam/server/rreg/client/rreg
JAVA_HOME The location where Java is located on the client computer. For
example: $WLS_HOME/Middleware/jdk160_11.
Note: $JAVA_HOME should point to JDK 1.6. (JDK 1.7 can also be
used in R2PS3.)
Table 15–6 Remote Registration Command Arguments: mode
Arguments Description
mode Either:
■
inband
■
outofband
input/
filename.xml
Either the absolute path to the input file (*request.xml or an
agentName_Response.xml), or the path relative to the value of $OAM_
REG_HOME.
The preferred location is $OAM_REG_HOME/input
Table 15–7 Remote Registration Command Samples
Command Type Sample (on Linux)
In-band Administrator In-band
Request
./bin/oamreg.sh inband input/*Request.xml
In-band Administrator
Submitted Request
./bin/oamreg.sh outofband input/starting_request.xml
Out-of-band Administrator
Returned Response
./bin/oamreg.sh outofband input/agentName_Response.xml
Understanding the Remote Registration Tool, Modes, and Process
15-26 Administrator's Guide for Oracle Access Management
After running the script, messages inform you of success or failure. Following a
successful registration or update, you must copy the artifacts to the Agent host, as
outlined in "Updating Agent Configuration Files" on page 14-10.
15.5.2 Common Elements within Remote Registration Request Templates
Table 15–8, shows the global elements that are common within all remote registration
request files, regardless of agent type.
[prompt_flag] value:
[-noprompt]
Optional. When -noprompt is used, oamreg does not wait for prompts
(password, and so on). Instead these values can be piped in, either from
an input file or from the command line itself using an echo command.
Examples from $OAM_REG_HOME location:
(echo username; echo password; echo WebGate_password;) |
./bin/oamreg.sh inband input/Request.xml -noprompt
config.file
(echo username; echo password; echo WebGate_password; echo
httpscert_trust_prompt;) | ./bin/oamreg.sh inband
input/Request.xml -noprompt
(echo username; echo password; echo WebGate_password; echo
cert_password;) | ./bin/oamreg.sh inband input/Request.xml
-noprompt
(echo username; echo password; echo WebGate_password; echo
httpscert_trust_prompt; echo cert_password;) |
./bin/oamreg.sh inband input/Request.xml -noprompt
See Also: "Updating Agents Remotely" on page 15-38
Note: After launching the script, Administrators are prompted for a
username and password (unless -
noprompt
is used as shown in
Table 15–7.)
Note: In Table 15–8, descriptions of each element are omitted; see
Table 15–1.
Table 15–8 Common Elements in Remote Registration Requests
Element Example
<serverAddress>
<serverAddress>http://{oam_admin_ser
ver_host}:{oam_admin_server_port}
</serverAddress>
<agentName>
<agentName>RREG_OAM</agentName>
<hostIdentifier>
<hostIdentifier>RREG_HostId11G
</hostIdentifier>
Extended Templates Only
<agentBaseUrl>
<agentBaseUrl>http://{web_server_
host):(web_server_port}
</agentBaseUrl>
Table 15–7 (Cont.) Remote Registration Command Samples
Command Type Sample (on Linux)
Understanding the Remote Registration Tool, Modes, and Process
Registering and Managing OAM 11g Agents 15-27
15.5.3 About Key Use, Generation, Provisioning, and Storage
Each registered agent has a symmetric key, regardless of the registration method
(Oracle Access Management Console versus remote registration).
Each application will have a symmetric key whether it is protected through mod_osso,
or an OAM Agent. This key is generated by the registration tool. Storage of the
application mapping, key, and type of Agent persists in the system configuration for
retrieval as needed. The following sections contain details.
■About Key Use
■About Key Generation
■About Key Accessibility and Provisioning
■About Key Storage
15.5.3.1 About Key Use
Each 11g WebGate agent has its own secret key that is shared between the agent and
the OAM Server. If one 11g WebGate is compromised, other 11g WebGates are
unaffected. The following presents an overview:
■Encrypt/Decrypt the host-based WebGate-specific OAMAuthnCookie_
<host:port>_<random number>.
■Encrypt/Decrypt the data that is redirected between WebGate and OAM Server.
15.5.3.2 About Key Generation
Figure 15–5 illustrates the process of key generation, which occurs automatically when
the agent is registered, regardless of the method used (Oracle Access Management
Console versus remote registration). There is one symmetric key per agent.
<autoCreatePolicy>
<autoCreatePolicy>true
</autoCreatePolicy>
<applicationDomain>
<applicationDomain>RREG_OAM11G
</applicationDomain>
<virtualhost>
<virtualhost>false<virtualhost>
Table 15–8 (Cont.) Common Elements in Remote Registration Requests
Element Example
Understanding the Remote Registration Tool, Modes, and Process
15-28 Administrator's Guide for Oracle Access Management
Figure 15–5 Key Generation
15.5.3.3 About Key Accessibility and Provisioning
Each Agent specific key must be accessible to the corresponding WebGate through a
secure local storage on the client machine. Cryptographic keys are not stored in the
data store. Instead, an alias to an entry in a Java keystore or CSF repository is stored;
the Partner and Trust Management API obtain the actual key when it is requested. The
agent specific secret key:
■Is provisioned during remote registration (either in-band mode or out-of-band
mode)
■Is unique so that it can uniquely identify each agent.
■Is distributed securely back to the agent (either through the wire during in-band
mode or through a separate secure channel during out-of-band mode).
■ Is saved in the Oracle Secret Store, in the SSO wallet. SSO wallet creation applies
only to 11g WebGates (not to 10g WebGates or other agent types).
■Is saved in the Oracle Secret Store, in an auto-login editable SSO wallet, upon
completion of registration.
15.5.3.4 About Key Storage
The SSO wallet containing the agent key must be located in cwallet.sso, in the
directory with ObAccessClient.xml in WebGate_instance_dir/WebGate/config (for
example, $WebTier_MW_Home/Oracle_WT1/instances).
Note: The Oracle Secret Store is a container that consolidates the
storage of secret keys and other security-related secret information
inside the Oracle Wallet, not in plain-text. The SSO wallet relies on
underlying file system security to protect its data. Opening this wallet
does not require a password. The SSO wallet depends on the
operating system and file permissions for its security.
Understanding Remote Registration Templates: OAM Agents
Registering and Managing OAM 11g Agents 15-29
The SSO wallet does not require a user password, and should be protected with the
proper file permission (700) or registry on Windows.
15.6 Understanding Remote Registration Templates: OAM Agents
Oracle provides both a short and extended registration request template for use with
the remote agent registration tool: oamreg.sh (Linux) or oamreg.bat (Windows). This
topic focuses on OAM Agent templates (WebGates and Access Clients).
Regardless of the template you choose (short or extended), only a few differences exist
between 11g and 10g OAM Agent templates, listed in Table 15–9 and stored in
$OAM_
REG_HOME/input/
.
15.6.1 OAM Agent Parameters for Remote Registration
Table 15–10 describes elements specific to OAM Agent remote registration requests.
Element names in request templates might differ slightly from counterparts in the
Oracle Access Management Console. Unless explicitly stated, all information applies
equally to requests for both 10g and 11g WebGates/Access Clients. Protected, public,
and excluded resource lists are included in both the short and extended request
templates for OAM Agents.
Table 15–9 Remote Registration Request Templates for OAM Agents
Template Type Template Name in $OAM_REG_HOME/input/
Abbreviated (Short) Form OAM11GRequest_short.xml (11g WebGates)
OAMRequest_short.xml (10g WebGates)
Extended (Full) Form OAM11gRequest.xml (11g WebGates)
OAMRequest.xml (10g WebGates)
Other Templates
Update Agent
Create Policies, Update Policies
Out-of-band Response
For a look at these specialized tasks and templates, see:
■"Updating Agents Remotely" on page 15-38
■"Managing Policies and Application Domains Remotely" on
page 25-82
■"Performing Out-of-Band Remote Registration" on page 15-35
Note: Despite being nearly identical for both 10g and 11g WebGates,
be sure to copy and use the appropriate request for your release.
Note: Descriptions of elements in Table 15–10 are in Table 15–3.
Understanding Remote Registration Templates: OAM Agents
15-30 Administrator's Guide for Oracle Access Management
Table 15–10 Elements in Extended OAM Agent Remote Registration Requests
Element Example
<serverAddress>
<agentName>
<hostIdentifier>
<agentBaseUrl>
<autoCreatePolicy>
<applicationDomain>
<virtualhost>
<allowCredentialCollectorOperations>
<allowMasterTokenRetrieval>
See Table 15–8, " Common Elements in Remote Registration Requests".
<hostPortVariationsList>
<hostPortVariationsList>
<host>host1</host>
<port>7777</port>
</hostPortVariations>
<host>host2</host>
<port>7778</port>
</hostPortVariations>
</hostPortVariationsList>
<protectedResourcesList>
<protectedResourcesList>
<resource>/</resource>
</protectedResourcesList>
<publicResourcesList>
<publicResourcesList>
<resource>/public/index.html
</resource>
</publicResourcesList>
<excludedresourcesList>
<excludedresourcesList>
<resource>/excluded/index.html
</resource>
</excludedresourcesList>
<primaryCookieDomain>
10g Request Only
In OAMRequest.xml (10g WebGates)
<hostIdentifier> is also used as preferred HTTP
host
<primaryCookieDomain>{client_domain}
</primaryCookieDomain>
<maxCacheElems>
<maxCacheElems>100000
</maxCacheElems>
<cacheTimeout>
<cacheTimeout>1800</cacheTimeout>
<tokenValidityPeriod>
11g Request Only
<tokenValidityPeriod>3600
</tokenValidityPeriod>
<cookieSessionTime>
10g WebGate only, Chapter 30
<cookieSessionTime>3600
</cookieSessionTime>
<maxConnections>
<maxConnections>1</maxConnections>
<maxSessionTime>
<maxSessionTime>24</maxSessionTime>
<idleSessionTimeout>
10g WebGate only, Chapter 30
<idleSessionTimeout>3600>
</idleSessionTimeout
<failoverThreshold>
<failoverThreshold>1
</failoverThreshold>
<aaaTimeoutThreshold>-
<aaaTimeoutThreshold>-1
</aaaTimeoutThreshold>
<sleepFor>
<sleepFor>60</sleepFor>
<debug>
<debug>false</debug>
Understanding Remote Registration Templates: OAM Agents
Registering and Managing OAM 11g Agents 15-31
<security>
<security>open</security
<denyOnNotProtected>
<denyOnNotProtected>1
</denyOnNotProtected>
<allowManagementOperations>
<allowManagementOperations>false/<allowManagementOperations>
<cachePragmaHeader>
<cacheControlHeader>
<cachePragmaHeader>no-cache
</cachePragmaHeader>
<cacheControlHeader>no-cache
</cacheControlHeader
<ipValidation>
<ipValidation>0</ipValidation>
<ipValidationExceptions>
<ipValidationExceptions>
<ipAddress>10,11,11,11</ipAddress>
<ipAddress>10,11,11,12</ipAddress>
<ipAddress>10,11,11,13</ipAddress>
</ipValidationExceptions>
<logOutUrls>
<logOutUrls>
<url>/logout1.html</url>
<url>/logout2.html</url>
</logOutUrls>
<logoutCallbackUrl>
11g Request Only
<logoutCallbackUrl>/oam_logout_success
</logoutCallbackUrl>
<logoutTargetUrlParamName>
11g Request Only
<logoutTargetUrlParamName>end_url
</logoutTargetUrlParamName>
User-Defined Parameter Names Examples
<userDefinedParameters>
<userDefinedParam>
<name>...</name>
<value>...</value>
</userDefinedParam>
MaxPostDataLength
<userDefinedParameters>
<userDefinedParam>
<name>MaxPostDataLength</name>
<value>750000</value>
</userDefinedParam>
maxSessionTimeUnits
<userDefinedParameters>
<name>maxSessionTimeUnits</name>
<value>hours</value>
</userDefinedParam>
useIISBuiltinAuthentication
<userDefinedParameters>
<name>useIISBuiltinAuthentication
</name>
<value>false</value>
</userDefinedParam>
idleSessionTimeoutLogic
10g WebGates only
<userDefinedParameters>
<name>idleSessionTimeoutLogic
</name>
<value>leastComponentIdleTimeout
</value>
</userDefinedParam>
URLInUTF8Format
<userDefinedParameters>
<name>URLInUTF8Format</name>
<value>true</value>
</userDefinedParam>
Table 15–10 (Cont.) Elements in Extended OAM Agent Remote Registration Requests
Element Example
Performing Remote Registration for OAM Agents
15-32 Administrator's Guide for Oracle Access Management
15.7 Performing Remote Registration for OAM Agents
This section includes the following topics describing how to perform remote
registration, which is similar regardless of the agent type:
■Acquiring and Setting Up the Remote Registration Tool
■Creating Your Remote Registration Request
■Performing In-Band Remote Registration
■Performing Out-of-Band Remote Registration
inactiveReconfigPeriod
Shared secret applies to only 10g WebGate
Configuration applies to only 11g WebGate.
<userDefinedParameters>
<name>inactiveReconfigPeriod</name>
<value>10</value>
</userDefinedParam>
WaitForFailover
<userDefinedParameters>
<name>WaitForFailover</name>
<value>-1</value>
</userDefinedParam>
proxySSLHeaderVar
<userDefinedParameters>
<name>proxySSLHeaderVar</name>
<value>IS_SSL</value>
</userDefinedParam>
client_request_retry_attempts
<userDefinedParameters>
<name>client_request_retry_attempts </name>
<value>1</value>
</userDefinedParam>
ContentLengthFor401Response
<userDefinedParameters>
<name>ContentLengthFor401Response
</name>
<value>0</value>
</userDefinedParam>
SUN61HttpProtocolVersion
<userDefinedParameters>
<name>SUN61HttpProtocolVersion
</name>
<value>1.0</value>
</userDefinedParam>
impersonationCredentials
<userDefinedParameters>
<name>username:password
</name>
<value>cred</value>
</userDefinedParam>
UseWebGateExtForPassthrough
<userDefinedParameters>
<name>UseWebGateExtForPassthrough
</name>
<value>false</value>
</userDefinedParam>
syncOperationMode
<userDefinedParameters>
<name>syncOperationMode</name>
<value>false</value>
</userDefinedParam>
filterOAMAuthnCookie
11g Request only.
<userDefinedParameters>
<name>filterOAMAuthnCookie</name>
<value>true</value>
</userDefinedParam>
Table 15–10 (Cont.) Elements in Extended OAM Agent Remote Registration Requests
Element Example
Performing Remote Registration for OAM Agents
Registering and Managing OAM 11g Agents 15-33
15.7.1 Acquiring and Setting Up the Remote Registration Tool
The oamreg client tool can be used anywhere, not just on the OAM Server. If the
oamreg home is already exploded, you can use the following procedure to acquire and
update the oamreg script for your operating system:
Windows: oamreg.bat
Linux: oamreg.sh
For remote registration, two variables are required: JAVA_HOME and OAM_REG_
HOME, as described in Table 15–11.
1. Locate RREG.tar.gz file in the following path:
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
2. Untar RREG.tar.gz file, which creates directories beneath
/client
containing the
required tool and templates.
3. In the oamreg script (...
/rreg/client/rreg/bin
) set environment variables as
follows:
a. Set JAVA_HOME to JDK 1.6 (Table 15–11).
JDK 1.7 can also be used in R2PS3.
b. Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your
environment (client side or server side Table 15–11).
4. Proceed with "Creating Your Remote Registration Request".
Note: Oracle Recommends using the latest tool and files by applying
the latest bundle patch and untarring RREG.tar.gz again as described
here.
Table 15–11 Variables Required for Remote Registration
Location Variable Description
Client Side JAVA_HOME The JDK 1.6 location on the computer that relies on
$JAVA_HOME already set in the environment. (JDK 1.7
can also be used in R2PS3.)
OAM_REG_HOME The absolute file location for RREG HOME (directory
under which RREG.tar was exploded, followed by /rreg
and one directory above where the scripts reside).
For example:
$OAM_HOME/oam/server/rreg/client/rreg
If $ORACLE_IDM_HOME is $MW_HOME/Oracle_IDM:
export $OAM_REG_HOME=$MW_HOME/Oracle_
IDM/oam/server/rreg
rreg folder location
(not RREG.tar.gz
location)
JAVA_HOME Relies on $JAVA_HOME already set in the environment.
OAM_REG_HOME Is already set in the script during the installation.
See Also: "About Remote Registration Command Arguments and
Modes" on page 15-25
Performing Remote Registration for OAM Agents
15-34 Administrator's Guide for Oracle Access Management
15.7.2 Creating Your Remote Registration Request
You can use the following procedure to create an appropriate *Request*.xml file to
provide input for the specific agent you want to register.
Before you begin, read "Understanding Remote Registration Templates: OAM Agents."
1. Locate the required *Request*.xml input file for the agent you want to register:
Regardless of the template you choose (short or extended), only a few differences
exist between 11g and 10g agent templates stored in
$OAM_REG_HOME/input/
. For
example:
OAM11GRequest.xml
2. Copy the request file to a new name. For example:
From: OAM11GRequest.xml
To: my11gagent_request.xml
3. In the Request file, modify information to reflect details for your agent and the
resources to protect using details in:
■Table 15–9, " Remote Registration Request Templates for OAM Agents"
■Table 15–10, " Elements in Extended OAM Agent Remote Registration
Requests"
4. Proceed with task needed for your environment:
■Performing In-Band Remote Registration
■Performing Out-of-Band Remote Registration
15.7.3 Performing In-Band Remote Registration
The OAM Administrator within the network performs all tasks. This section provides
the steps to perform in-band remote registration, regardless of agent type. For this
example, an OAM Agent is being registered using the short request on a Linux system.
Your agent type, request template, and output files will be different.
Before you begin, read:
■Acquiring and Setting Up the Remote Registration Tool
■Creating Your Remote Registration Request
1. On the computer hosting the Agent, run the registration command and specify
your own *Request*.xml as the input file. For example:
./bin/oamreg.sh inband input/
myagent_request.xml
2. Provide the registration Administrator user name and password when asked.
Example 15–1 illustrates a sample rreg registration output.
Example 15–1 rreg registration Sample Output
Welcome to OAM Remote Registration Tool!
Parameters passed to the registration tool are:
Mode: inband
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management chapter "Installing and Configuring
Oracle HTTP Server 11g WebGate for OAM"
Performing Remote Registration for OAM Agents
Registering and Managing OAM 11g Agents 15-35
Filename: /scratch/work/mw1916/idm1385/oam/server/rreg/input/1.xml
Enter admin username:oamadminuser
Username: oamadminuser
Enter admin password:
Do you want to enter a Webgate password?(y/n):
n
Do you want to import an URIs file?(y/n):
n
----------------------------------------
Request summary:
OAM Agent Name:RREG_1234
URL String:RREG_1234
Registering in Mode:inband
Your registration request is being sent to the Admin server at:
http://slc01huw.us.example.com:20081
----------------------------------------
Inband registration process completed successfully! Output artifacts are created
in the output folder.
The output folder is in the same location where RREG.tar.gz was expanded:
/rreg/output/AgentName/
3. Review the native configuration file created for the agent in the
/rreg/output/AgentName/ folder.
4. Finalize Registration: Perform the following steps to replace the earlier agent
configuration file if it is not already replaced:
a. Copy artifacts in /rreg/output/AgentName/ to update the agent
configuration. For example:
From the AdminServer (Console) host
/rreg/output/
Agent_Name/
ObAccessClient.xml
and
cwallet.sso
To the Agent host: $11gWG_install_dir/
WebGate/config
. For example:
$WebTier_MW_Home/Oracle_WT1/instances/instance1
/config/OHS/ohs1/WebGate/config
b. Restart the OAM Server hosting the agent.
5. Proceed with "Validating Remote Registration and Resource Protection".
15.7.4 Performing Out-of-Band Remote Registration
This section provides steps for Administrators outside (and inside) the network as
they work together to register an agent remotely.
During out-of-band remote registration, an administrator outside the network submits
a registration request to an Administrator within the network. After processing the
request, the in-band Administrator returns the following files to the out-of-band
Administrator to configure his environment:
Table 15–12 Files Returned by in-band Administrator to out-of-band Administrator
File Description
agentName_Response.xml Returned to, and used by, the out-of-band Administrator. Oracle
recommends that you do not open or edit agentName_Response.xml.
Performing Remote Registration for OAM Agents
15-36 Administrator's Guide for Oracle Access Management
The steps performed by each Administrator are identified:
■In-Band Administrator: Identifies a task performed by the Web server
Administrator within the network.
■Out-of-Band Administrator Identifies a task performed by the Web server
Administrator outside the network
Steps here illustrate registering an OAM Agent on a Linux system. Your templates and
output files will be different.
Before you begin, read "Acquiring and Setting Up the Remote Registration Tool."
1. Out-of-Band Administrator: Create and send your starting_request.xml file to the
in-band Administrator for processing (see "Creating Your Remote Registration
Request" on page 15-34):
$WLS_Home/Middleware/Oracle_
$IDM1/oam/server/rreg/client/rreg/output/AgentName/starting_request.xml
2. In-Band Administrator:
a. Run the registration command and specify the out-of-band Administrator's
starting_request.xml as the input file. For example:
./bin/oamreg.sh outofband input/starting_request.xml
b. Provide the Registration Administrator user name and password when asked.
c. Read messages on-screen to confirm:
Success: "... registration process completed successfully!
Response.xml location: "... created in input folder ..."
The input folder is in the same location where RREG.tar.gz was expanded:
/rreg/input/
d. Return the agentName_Response.xml file to the out-of-band Administrator
along with any other artifacts. For example:
agentName_Response.xml
3. Out-of-Band Administrator: Updates the environment, as follows.
a. On the computer hosting the Agent, run the remote registration command and
specify the received agentName_Response.xml as the input file. For example:
./bin/oamreg.sh outofband input/
agentName_
Response.xml
Native Web server configuration
files
Returned to, and used by, the out-of-band Administrator to update
his Web server.
See Also "Updating Agent Configuration Files" on page 14-10
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management chapter "Installing and Configuring
Oracle HTTP Server 11g WebGate for OAM"
See Also: Part VII, "Registering and Using Agents with Access
Manager", if needed.
Table 15–12 (Cont.) Files Returned by in-band Administrator to out-of-band
File Description
Introduction to Updating Agents Remotely
Registering and Managing OAM 11g Agents 15-37
b. Copy artifacts generated in /rreg/output/AgentName/ to update the agent
configuration (), then restart the OAM Server hosting the agent. For example,
ObAccessClient.xml and cwallet.sso:
From the AdminServer (Console) host
/rreg/output/
Agent_
Name/
ObAccessClient.xml
and
cwallet.sso
To the Agent host: $11gWG_install_dir/
WebGate/config
. For example:
$WebTier_MW_Home/Oracle_WT1/instances/instance1
/config/OHS/ohs1/WebGate/config
c. Proceed with "Validating Remote Registration and Resource Protection".
15.8 Introduction to Updating Agents Remotely
Several remote management modes are provided to help Administrators quickly
update, validate, or delete an existing agent registration. This section provides the
following topics:
■About Remote Agent Update Modes
■About Remote 11g OAM Agent Updates Template
15.8.1 About Remote Agent Update Modes
Table 15–13 presents remote agent management modes. Command parameters include
the mode, input *Request.xml file (a relative path with respect to $OAM_REG_HOME,
the preferred location for the input *Request.xml files):
./oamreg.sh <mode> <input_file> [prompt_flag] [component.oam.config_file] <mode>
value
15.8.2 About Remote 11g OAM Agent Updates Template
You use
OAM11GUpdateAgentRequest.xml
to pass specific Agent-update values to the
remote registration tool, oamreg. The primary differences between the update request
and the original registration request is that the update request.
Table 15–13 Remote Agent Update Modes and Input Files
Mode and Input Files Description and Syntax
agentUpdate mode
OAM11GUpdateAgentRequest.xml
OAMUpdateAgentRequest.xml
Allows Administrators to update existing agent attributes, regardless
of agent type:
./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml
See Also:
OpenSSOUpdateAgentRequest, Chapter 28
OSSOUpdateAgentRequest, Chapter 29
agentValidate mode
No input file needed.
Validates whether the agent is already provisioned in Oracle Access
Manager:
./bin/oamreg.sh agentValidate agentname
agentDelete mode
No input file needed.
Allows Administrators to delete the agent registration:
./bin/oamreg.sh agentDelete agentname
Table 15–14 Delta: OAM Agent Update versus Registration Request
Delta Element
Adds <ipValidation>
Updating Agents Remotely
15-38 Administrator's Guide for Oracle Access Management
15.9 Updating Agents Remotely
This section provides the following topics for agents registered with Access Manager,
regardless of agent type:
■Updating Agent Registrations Remotely
■Validating an Agent Registration Remotely
■Removing an Agent Registration Remotely
15.9.1 Updating Agent Registrations Remotely
This topic provides the steps to update agents registered with Access Manager,
regardless of agent type. Before you begin, review "About Remote Agent Update
Modes."
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. Create your update request using one of the following templates:
■OAM11GUpdateAgentRequest.xml
■OAMUpdateAgentRequest.xml (10g) Chapter 30
■OSSOUpdateAgentRequest.xml Chapter 29
■OpenSSOUpdateAgentRequest.xml Chapter 28
3. On the computer hosting the Agent, run the following command with
agentUpdate
mode specify your own *Request*.xml as the input file. For example:
./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml
4. Provide the registration Administrator user name and password when asked.
Omits <ipValidationExceptions>
<hostidentifier>
<virtualhost>
<hostportVariations>
<authCreatePolicy> and application domain-related elements
<ssoServerVersion>
<idleSessionTimeout>
See Also:
■Table 15–3, " Elements on Expanded 11g and 10g WebGate/Access
Client Registration Pages"
See Also:
■Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
■Chapter 29, "Registering and Managing Legacy OSSO Agents"
■"Managing 10g OAM Agents Remotely" on page 30-13
Table 15–14 (Cont.) Delta: OAM Agent Update versus Registration Request
Delta Element
Updating Agents Remotely
Registering and Managing OAM 11g Agents 15-39
5. Read the messages on-screen to confirm:
■Success: On-screen message confirms
agentUpdate process completed successfully!
Native Configuration File Location: "... created in output folder
..."
The output folder is in the same location where RREG.tar.gz was expanded:
/rreg/output/AgentName/
6. Finalize Agent Registration: Copy the updated ObAccessClient.xml and
cwallet.sso.
From the AdminServer (Console) host: /rreg/output/Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config. For example:
$WebTier_MW_Home/Oracle_WT1/instances/instance1/
config/OHS/ohs1/WebGate/config
7. Restart the OAM Server that is hosting this agent and proceed to "Validating an
Agent Registration Remotely".
15.9.2 Validating an Agent Registration Remotely
This topic provides the steps to validate agent registration, regardless of agent type.
Before you begin, review "About Remote Agent Update Modes."
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. On the Agent host, run the following command in
agentValidate
mode. For
example:
./bin/oamreg.sh agentValidate agentname
3. Provide the registration Administrator user name and password when asked.
4. Read the messages on-screen to confirm:
■Success: On-screen message confirms
AgentValidation process completed successfully!
15.9.3 Removing an Agent Registration Remotely
This topic provides the steps to remove a registered agent, regardless of agent type.
Before you begin, review "About Remote Agent Update Modes."
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. On the computer hosting the Agent, run the following
agentDelete
command. For
example:
./bin/oamreg.sh agentDelete agentname
3. Provide the registration Administrator user name and password when asked.
4. Read the messages on-screen to confirm:
■Success: On-screen message confirms
AgentDelete process completed successfully
!
Validating Remote Registration and Resource Protection
15-40 Administrator's Guide for Oracle Access Management
15.10 Validating Remote Registration and Resource Protection
You can use the following sections as a guide to validate registration of an agent
regardless of the agent type. You must be an in-band Administrator to perform tasks
using the Oracle Access Management Console. Out-of-band Administrators must test
authentication and access remotely.
■Validating Agent Registration using the Oracle Access Management Console
■Verifying Authentication and Access After Remote Registration
15.10.1 Validating Agent Registration using the Oracle Access Management Console
Only an in-band Administrator can use the following procedure.
1. Validate Agent Registration in the Oracle Access Management Console:
a. Confirm Agent details under Application Security in the Oracle Access
Management Console.
b. Confirm the updated Agent configuration files are in the appropriate location,
as described in "Performing Remote Registration for OAM Agents".
2. Validate Shared Components, Host identifier: Confirm that the host identifier is
defined in the Oracle Access Management Console.
3. Validate Application Domain: Under the Policy Configuration tab, confirm there
is a new Application Domain named after the registered agent. Resources in the
Application Domain should be associated with the host identifier.
4. Proceed with "Verifying Authentication and Access After Remote Registration".
15.10.2 Verifying Authentication and Access After Remote Registration
After registration, protected resource should be accessible with proper authentication
without restarting the AdminServer or OAM Server. Both in-band and out-of-band
Administrators can use the following procedure to validate proper registration and
policies.
The procedure here provides several methods for confirming that registration,
authentication, and authorization are properly configured and operational. The
procedures is nearly identical for all agent types.
1. Enter the URL for an application protected by the registered OAM Agent to
confirm that the log in page appears (proving that the authentication redirect URL
was specified appropriately). For example:
http://exampleWebserverHost.sample.com:8100/resource1.html
2. On the Log In page, enter a valid username and password when asked, and click
Login.
3. Check the OAM specific cookies are created in the browser session. For example:
ObSSOCookie:
Set-Cookie:
ObSSOCookie=GGVEuvjmrMe%2FhbItbjT24CBmJo1eCIfDIwQ1atdGdnY4mt6kmdSekSFeAAFvFrZZZ
xDfvpkfS3ZLZFbaZU2rAn0YYUM3JUWVYkYFwB%2BBK7V4x%2FeuYHj%2B8gwOyxhNYFna3iSx1MSZBE
y51KTBfsDYOiw6R%2BCxUhOO8uZDTYHI3s0c7AQSyrEiQTuUV3nv1omaFZlk1GuZa4J7ycaGbIUyqwX
See Also: Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"
Validating Remote Registration and Resource Protection
Registering and Managing OAM 11g Agents 15-41
rM0cKuBJNd6sX1LiRj9HofYQsvUV7ToqeAOpDS7z9qs5LhqU5Vq60bBn12DTX6zNX6Lcc0L5tVwvh7%
2BnOAkz2%2BoDkLs%2BBTkeGcB3ppgC9;httponly; path=/; domain=.example.com;
OAM_ID Cookie:
Set-Cookie:
OAM_ID=v1.0~0~E1EBBC9846E09857060A68E79AEEB608~AA79FC43C695162B6CDE3738F40E94DA
6408D58B879AC3B467EBBD4800743C899843672B3511141FFABCF58B2CDCB700C83CC734A913625
7C4ABDA6913C9EF5A4E05C5D03D3514F2FECACD02F1C1B9314D76B4A68CB7A8BE42AEB09AFB98B8
EB; path=/; HttpOnly
4. Proceed as follows:
■Success: If you authenticated successfully and were granted access to the
resource; the configuration is working properly. Proceed with Steps 5 through
12 for further validations.
■Failure: If you received an error during login or were denied access to the
resource, check the following:
–Login Error: Confirm that you provided a valid user id and password.
– Unavailable Resource: Confirm that the resource is available.
– Wrong Redirect URL: Verify the redirect URL in the Oracle Access
Management Console.
5. User Variations: Perform steps 1 through 4 again with user variations to confirm
appropriate behavior (either success for authorized users or failure for
unauthorized users).
6. Request Cancellation: Perform a partial log in and click Cancel to confirm that the
resource is not accessed.
7. Modified Authentication URL: Enter a nearly identical authentication URL as
you perform Steps 1 through 5 to confirm appropriate response. For example, add
a character to the URL string.
8. Updated Resource: Perform the following steps to ensure the resource is
accessible. For example:
Original Resource: /abc/test.html
Updated Resource: /abc/xyz/test.html
Without restarting the Oracle WebLogic Server:
■Access the updated resource and confirm the user is asked to authenticate and
the resource is accessible.
■Access the original resource and confirm that the resource is accessible and the
user is not asked for authentication.
9. Various URL Patterns: Verify authentication for various URL patterns as you
perform steps 1 through 5.
10. New Authentication Scheme: Perform the following steps to confirm
authentication operations without restarting the WebLogic Server.
■Add a new authentication policy that uses a different Authentication Scheme.
■Protect the resource using the new policy.
■Without restarting the Oracle WebLogic Server, perform steps 1 through 4.
Replacing the IAMSuiteAgent with an 11g WebGate
15-42 Administrator's Guide for Oracle Access Management
11. CGI Resource Header Variable and Cookies: Perform the following steps to
confirm authentication operations without having to restart the WebLogic Server.
■Add a new authentication policy to protect a Common Gateway Interface
(CGI) resource and set the Response for "Authentication Successful".
■Protect the resource using the new policy.
■Access the CGI resource.
■Check for the header values configured for the response in a CGI data dump.
12. Agent Disabled: Perform the following steps to validate accessibility and
authentication if WebGate is disabled in ObAccessClient.xml (WebGate should
pick up the enabled value from oam-config.xml).
■Disable the Agent State.
■Start the Web server and OAM Server.
■Access an application protected by the Agent and confirm that you are asked
to authenticate.
15.11 Replacing the IAMSuiteAgent with an 11g WebGate
You can skip this section if you are not replacing the IAMSuiteAgent with an 11g
WebGate.
Access Manager and Oracle Identity Manager are among the Oracle Fusion
Middleware 11g components. During initial configuration with the WebLogic Server
Configuration Wizard, the IAMSuiteAgent is registered with Access Manager 11g
along with the IDM domain host identifier and an Application Domain named for the
agent.
Oracle Fusion Middleware uses Access Manager to protected Oracle Identity
Management consoles out of the box using the IAMSuiteAgent.
To protect applications beyond containers, you can replace the IAMSuiteAgent with a
11g WebGate (to protect the same set of applications using the same Application
Domain and policies as the pre-registered IAMSuiteAgent). The following list is the
task overview for this section.
1. Registering a Replacement 11g WebGate for IAMSuiteAgent
2. Installing the Replacement 11g WebGate for IAMSuiteAgent
3. Updating the WebLogic Server Plug-in Configuration
4. Optional: Confirming the AutoLogin Host Identifier for an OAM / OIM
Integration
5. Optional: Configuring OAM Security Providers for WebLogic
6. Optional: Disabling IAMSuiteAgent
7. Configuring Centralized Logout for 11g WebGates
8. Verifying the Webgate Configuration
See Also: Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"
Replacing the IAMSuiteAgent with an 11g WebGate
Registering and Managing OAM 11g Agents 15-43
15.11.1 Registering a Replacement 11g WebGate for IAMSuiteAgent
The following procedure walks through registering a replacement 11g WebGate using
the remote registration tool, in-band mode.
In this example,
OAMRequest_short.xml
is used as a template to create an agent named
11g4IAM, protecting /.../*, and declaring a public resource,
/public/index.html
. Your
values will be different.
1. Acquire the Access Manager remote registration tool and set up the script for your
environment. For example:
a. Locate RREG.tar.gz file in the following path:
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
b. Untar RREG.tar.gz file to any suitable location. For example: exploded_dir_
for_RREG.tar/rreg/input/oamreg.
c. In the oamreg script, set the following environment variables based on your
situation (client side or server side) and information in Table 15–5:
OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
JAVA_HOME = Java_location_on_the_computer
2. Create the registration request and ensure that the
autoCreatePolicy
parameter is
set to false:
a. Locate OAMRequest_short.xml and copy it to a new file. For example:
exploded_dir_for_RREG.tar/rreg/input/oamreg/
Copy: OAM11gRequest_short.xml
To: 11g4IAM.xml
b. Edit 11g4IAM.xml to include details for your environment. For example, if you
are changing from the IAMSuiteAgent to an 11g WebGate Agent your request
might look like the following:
<OAM11gRegRequest>
<serverAddress>http://ruby.uk.example.com:7001</serverAddress>
<hostIdentifier>11g4IAM</hostIdentifier>
<agentName>11g4IAM</agentName>
<autoCreatePolicy>false</autoCreatePolicy>
<logOutUrls><url>/oamsso/logout.html</url></logOutUrls>
...retain defaults for remaining elements...
...
...
</OAM11gRegRequest>
See Also:
■Chapter 15 for more information about the remote registration
tool, processing, and request files
Note: To use IAM Suite policies with the replacement WebGate,
ensure that the WebGate registration is configured to use the
IAMSuiteAgent Host Identifier and Preferred Host.
Replacing the IAMSuiteAgent with an 11g WebGate
15-44 Administrator's Guide for Oracle Access Management
3. Register the agent. For example:
a. Locate the remote registration script.
Linux: rreg/bin/oamreg.sh
Windows: rreg\bin\oamreg.bat
b. From the directory containing the script, execute the script using inband
mode. For example:
$ ./bin/oamreg.sh inband input/11g4IAM.xml
Welcome to OAM Remote Registration Tool!
Parameters passed to the registration tool are:
Mode: inband
Filename: ...
c. When prompted, enter the following information using values for your
environment:
Enter your agent username: userame
Username: userame
Enter agent password: ********
Do you want to enter a WebGate password?(y/n)
n
iv.Do you want to import an URIs file?(y/n)
n
d. Review the final message to confirm that this was a successful registration:
Inband registration process completed successfully! Output artifacts are
created in the output folder"
4. Log in to the Oracle Access Management Console and review your new
registration:
a. From the System Configuration tab, Access Manager section, open the OAM
Agents node and locate your agent registration.
b. Double-click the agent's name to display the registration page and review the
details. For example:
c. OAM Proxy Port—From the System Configuration tab, Common
Configuration section, double-click Server Instances and locate the port on
which the OAM Proxy is running.
5. Copy the artifacts as follows (or install WebGate with the same specifications, then
copy artifacts), as described in "Installing the Replacement 11g WebGate for
IAMSuiteAgent".
See Also: "Creating Your Remote Registration Request" on
page 15-34
See Also: "Searching for an OAM Agent Registration" on page 15-20
Note: If you install a fresh WebGate, enter matching details during
installation.
Replacing the IAMSuiteAgent with an 11g WebGate
Registering and Managing OAM 11g Agents 15-45
6. Proceed to "Updating the WebLogic Server Plug-in Configuration".
15.11.2 Installing the Replacement 11g WebGate for IAMSuiteAgent
After provisioning you must install the 11g WebGate to replace the IAMSuiteAgent.
During the installation, you must provide some of the same information for the
WebGate as you did when provisioning it. Following is the task overview.
1. Install the 11g WebGate as described in Oracle Fusion Middleware Installation Guide
for Oracle Identity and Access Management.
2. Replace IAMSuiteAgent Registration as described in "Updating the WebLogic
Server Plug-in Configuration".
15.11.3 Updating the WebLogic Server Plug-in Configuration
After provisioning and installing the 11g WebGate to replace the IAMSuiteAgent, the
mod_wl_ohs.conf file requires specific entries to instruct the WebGate Web server to
forward requests to the applications on the WebLogic Server.
Example 15–2 illustrates the areas that must be changed using sample entries. Entries
for your environment will be different.
Example 15–2 Updates for the 11g WebGate in mod_wl_ohs.conf
<IfModule weblogic_module>
<Location /oamconsole>
SetHandler weblogic-handler
WebLogicHost ruby.uk.example.com
WebLogicPort 6162
</Location>
<Location apmmconsole>
SetHandler weblogic-handler
WebLogicHost ruby.uk.example.com
WebLogicPort 6162
</Location>
...
</IfModule>
Agent & Artifacts Artifacts
11g WebGate/Access Client
ObAccessClient.xml and
cwallet.sso
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config
Note: The generic name of the WebLogic Server plug-in for Apache
is mod_weblogic. For Oracle HTTP Server 11g, the name of this
plug-in is mod_wl_ohs (the actual binary name is mod_wl_ohs.so).
Examples show exact syntax for implementation.
Note: You need similar Location entries for each of the URIs for all
the applications that were earlier accessed directly on the WebLogic
Server.
Replacing the IAMSuiteAgent with an 11g WebGate
15-46 Administrator's Guide for Oracle Access Management
1. Locate the mod_wl_ohs.conf file in the following path:
$OHS-INSTANCE_HOME/config/OHS/INSTANCE_NAME/mod_wl_ohs.conf
2. Edit the file to include a Location element for each application URI that was
previously accessed directly on the WebLogic Server (see Example 15–2).
3. Save the file.
4. Restart the Web server.
5. Proceed to the following task, as needed:
■Confirming the AutoLogin Host Identifier for an OAM / OIM Integration
■Configuring OAM Security Providers for WebLogic
15.11.4 Confirming the AutoLogin Host Identifier for an OAM / OIM Integration
This topic describes how to confirm (or configure) Oracle Identity Manager (OIM)
automatic login functionality when you have Access Manager integrated with OIM.
The AutoLogin functionality when Oracle Identity Manager is integrated with Access
Manager 11g requires the 10g WebGate Web server host name and port in the list of
host identifiers for the IAMSuiteAgent.
The agentBaseUrl parameter is used to update a given Host Identifier. However, if
automatic policy creation is set to false, the remote registration utility does not create
the Application Domain and does not honor the agentBaseUrl parameter.
The following procedure shows how to confirm (or configure) the AutoLogin host
identifier for an Access Manager/Oracle Identity Manager integration. Your values
will be different. Before you begin, read "Updating the WebLogic Server Plug-in
Configuration."
1. From the Policy Configuration tab, Host Identifiers node, and select
IAMSuiteAgent.
2. In the Operations panel, confirm that all host name and port combinations are
listed for this Host Identifier.
3. Proceed to "Configuring OAM Security Providers for WebLogic".
15.11.5 Configuring OAM Security Providers for WebLogic
This section describes how to configure the WebLogic Security Providers to ensure
Single Sign On using Access Manager 11g and the 10g WebGate.
Note: Skip this step if you do not have Access Manager 11g
integrated with Oracle Identity Manager 11g.
Note: If you have a load balancer in front of the 11g WebGate Web
server, you must also include the load balancer's host name and port
during Step 3.
See Also: "Searching for a Host Identifier Definition" on page 22-16
Replacing the IAMSuiteAgent with an 11g WebGate
Registering and Managing OAM 11g Agents 15-47
Refer to following topics for more information on setting up the security providers for
the 11g WebGate.
■About Security Providers
■Setting Up Security Providers for the 11g WebGate
15.11.5.1 About Security Providers
To complete the Access Manager 11g SSO configuration when a 11g WebGate is
replacing the IAMSuiteAgent requires configuring the following security providers in
a WebLogic Server domain:
■OAM Identity Asserter: Uses token-based authentication and asserts the OAM
SSO header and token.
■OID (or OVD) Authenticator: Creates the Subject and populates it with the correct
principals.
Depending on the store where your users are located, you configure either the
Oracle Internet Directory Authenticator or the Oracle Virtual Directory
Authenticator as the primary credential authenticator.
■Default Authenticator: This default WebLogic Authentication provider allows you
to manage users and groups in one place: the embedded WebLogic Server LDAP
server. This Authenticator is used by the Oracle WebLogic Server to login
administrative users:
When you configure multiple Authentication providers, you use the JAAS Control
Flag for each provider to control how the Authentication providers are used in the
login sequence. You can choose the following the JAAS Control Flag settings, among
others:
■REQUIRED—The Authentication provider is always called, and the user must
always pass its authentication test. Regardless of whether authentication succeeds
or fails, authentication still continues down the list of providers. The OAM
Identity Asserter is required.
■SUFFICIENT—The user is not required to pass the authentication test of the
Authentication provider. If authentication succeeds, no subsequent Authentication
providers are executed. If authentication fails, authentication continues down the
list of providers. Both the Oracle Internet Directory (or Oracle Virtual Directory)
and the Default Authenticator are sufficient.
■OPTIONAL—When additional Authentication providers are added to an existing
security realm, the Control Flag is set to OPTIONAL by default. You might need to
change the setting of the Control Flag and the order of providers so that each
Authentication provider works properly in the authentication sequence.
The user is allowed to pass or fail the authentication test of this Authentication
provider. However, if all Authentication providers configured in a security realm
have the JAAS Control Flag set to OPTIONAL, the user must pass the
authentication test of one of the configured providers.
Note: Skip this step if you do not have Access Manager 11g
integrated with Oracle Identity Manager 11g.
Replacing the IAMSuiteAgent with an 11g WebGate
15-48 Administrator's Guide for Oracle Access Management
Access Manager JAR are WAR files for authentication providers are available when
you install an Oracle Fusion Middleware product (Oracle Identity Management,
Oracle SOA Suite, or Oracle WebCenter). If you have a Fusion Middleware
application, you already have the files you need.
■oamAuthnProvider.jar: Includes files for both the Access Manager Identity
Asserter for single sign-on and the Authenticator for Oracle WebLogic Server
10.3.1+. A custom Access Manager AccessGate is also provided to process requests
for Web and non-Web resources (non-HTTP) from users or applications.
■oamauthenticationprovider.war: Restricts the list of providers that you see in the
Oracle WebLogic Server Console to only those needed for use with Access
Manager.
When you deploy the extension, the Administration Console creates an
in-memory union of the files and directories in its WAR file with the files and
directories in the extension WAR file. Once the extension is deployed, it is a full
member of the Administration Console: it is secured by the WebLogic Server
security realm, it can navigate to other sections of the Administration Console, and
when the extension modifies WebLogic Server resources, it participates in the
change control process For more information, see Oracle Fusion Middleware
Extending the Administration Console for Oracle WebLogic Server.
15.11.5.2 Setting Up Security Providers for the 11g WebGate
The following procedure requires the WebLogic Server Administration Console. This
example illustrates setting up the Oracle Internet Directory provider with the OAM
Identity Asserter and Default Authenticator. The steps are the same for OVD, should
you need this.
1. No Oracle Fusion Middleware Application: Obtain the Access Manager provider:
a. Log in to Oracle Technology Network at:
http://www.oracle.com/technology/software/products/middleware/htdocs/111110
_fmw.html
b. Locate the oamAuthnProvider ZIP file with WebGates:
oamAuthnProvider<version number>.zip
c. Extract and copy oamAuthnProvider.jar to the following path on the computer
hosting Oracle WebLogic Server:
$BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar
See Also: "Configuring Authentication Providers" in Oracle Fusion
Middleware Securing Oracle WebLogic Server for a complete list of
Authentication providers and details about configuring the Oracle
Internet Directory provider to match the LDAP schema for user and
group attributes.
Note: If you have a Fusion Middleware application, you already
have the files you need and you can skip Step 1 of the following
procedure. With no Fusion Middleware application, however, you
have a stand-alone Oracle WebLogic Server and must obtain the JAR
and WAR files from Oracle Technology Network as described in Step
1.
Replacing the IAMSuiteAgent with an 11g WebGate
Registering and Managing OAM 11g Agents 15-49
2. With Oracle Fusion Middleware Application Installed:
a. Locate oamauthenticationprovider.war in the following path:
$ORACLE_HOME/modules/oracle.oamprovider_11.1.2/oamauthenticationprovi
der.war
b. Copy oamauthenticationprovider.war to the following location:
$BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
provider.war
3. Log in to the WebLogic Server Administration Console and click Security Realms,
Default Realm Name, and click Providers.
4. OAM Identity Asserter: Perform the following steps to add this provider:
a. Click Authentication, click New, and then enter a name and select a type:
Name:
OAM ID Asserter
Type: OAMIdentityAsserter
OK
b. In the Authentication Providers table, click the newly added authenticator.
c. Click the Common tab, set the Control Flag to REQUIRED, and click Save
5. OID Authenticator: Perform the following steps to add this provider.
a. Click Security Realms, Default Realm Name, and click Providers
b. Click New, enter a name, and select a type:
Name:
OID Authenticator
Type: OracleInternetDirectoryAuthenticator
OK
c. In the Authentication Providers table, click the newly added authenticator.
d. On the Settings page, click the Common tab, set the Control Flag to
SUFFICIENT, and then click Save.
e. Click the Provider Specific tab and specify the following required settings
using values for your own environment:
Host: Your LDAP host. For example:
localhost
Port: Your LDAP host listening port. For example:
6050
Principal: LDAP administrative user. For example:
cn=orcladmin
Credential: LDAP administrative user password.
User Base DN: Same searchbase as in Access Manager.
All Users Filter: For example:
(&(uid=*)(objectclass=person))
User Name Attribute: Set as the default attribute for username in the LDAP
directory. For example:
uid
Group Base DN: The group searchbase (same as User Base DN)
Do not set the All Groups filter as the default works fine as is.
Save.
Replacing the IAMSuiteAgent with an 11g WebGate
15-50 Administrator's Guide for Oracle Access Management
6. Default Authenticator: Perform the following steps to set up the Default
Authenticator for use with the Identity Asserter:
a. Go to Security Realms, Default Realm Name, and click Providers.
b. Click Authentication, Click DefaultAuthenticator to see its configuration
page.
c. Click the Common tab and set the Control Flag to SUFFICIENT.
d. Save.
7. Reorder Providers:
a. Click Security Realms, Default Realm Name, Providers.
b. On the Summary page where providers are listed, click the Reorder button
c. On the Reorder Authentication Providers page, select a provider name and
use the arrows beside the list to order the providers as follows:
OAM Identity Asserter (REQUIRED)
OID Authenticator (SUFFICIENT)
Default Authenticator (SUFFICIENT)
d. Click OK to save your changes
8. Activate Changes: In the Change Center, click Activate Changes
9. Reboot Oracle WebLogic Server.
10. Proceed as follows:
■Successful: Go to "Disabling IAMSuiteAgent".
■Not Successful: Confirm that all providers have the proper specifications for
your environment, are in the proper order, and that
oamAuthnProvider.jar
is
in the correct location as described in "About Security Providers" on
page 15-47.
15.11.6 Disabling IAMSuiteAgent
This step is optional, not required.
IAMSuiteAgent detects when the WebGate has performed the authentication and then
goes silent. However, if the agent must be disabled, then either the WLSAGENT_
DISABLED system property or environment variable must be set to true for each one
of the servers on which the agent should be disabled. This applies to both
AdminServer and OAM Servers.
You can disable the agent in one of two ways:
■Either set the WLSAGENT_DISABLED environment variable to true
■Or pass WLSAGENT_DISABLED as a System Property
Before you begin: Configuring OAM Security Providers for WebLogic, if needed.
1. On the computer hosting the IAMSuiteAgent, perform one the following tasks:
■Either set the
WLSAGENT_DISABLED
environment variable to true:
setenv WLSAGENT_DISABLED true
■Or or pass
DWLSAGENT_DISABLED=true
as a System Property:
Managing the Preferred Host in 10g WebGates
Registering and Managing OAM 11g Agents 15-51
-DWLSAGENT_DISABLED=true
2. Restart the Web server.
3. Proceed with "Configuring Centralized Logout for 11g WebGates" on page 27-4,
then return to "Verifying the Webgate Configuration".
15.11.7 Verifying the Webgate Configuration
Oracle recommends testing your environment using the 11g WebGate to ensure that all
applications that were previously protected by the IAMSuiteAgent are now protected
after configuration.
Before you begin: "Configuring Centralized Logout for 11g WebGates"
15.12 Managing the Preferred Host in 10g WebGates
In previous 10g releases, the preferred host was a mandatory parameter which could
be made optional through configuration. In the current implementation of Access
Manager, the value of the preferred host parameter in the agent profile is a mandatory
field populated when the profile is created. Thus when migrating agent profiles from
Access Manager 10g, this parameter might have no value. Because of the empty
preferred host value in a migrated agent profile, the Access Manager 11g console does
not allow the administrator to modify the agent profile. Since the current migration
process does not support migration when this parameter is empty, the following
actions have been incorporated into the migration process.
■During the migration of agent profiles with no preferred host value, the host
identifier defined as the value of AUTO_UPDATE_HOSTID will be set as the
preferred host. This will work for 11g WebGates as well as 10g WebGates.
■The ALLOWBLANKPREFERREDHOST flag will be added and action taken based
on its value. In cases where it is set to true, the empty string will be sent to the
agent as the preferred host. In cases where it is set to false, the server will send a
fatal error to the agent.
See Also:
■"Validating Authentication and Authorization in an Application
Domain" on page 25-76
■Chapter 26, "Validating Connectivity and Policies Using the
Access Tester"
Note: In the getClientConfigResponse() method, the AUTO_
UPDATE_HOSTID host identifier will be replaced with an empty
string so that the preferred host will not be set in ObAccessClient.xml.
In these cases, the WebGate will read the host from the HTTP header.
Because the user can modify the HTTP header, this vulnerability is
indicated as follows.
■The 11g Access Manager console displays the agent profile with a
red mark indicating that the value of the preferred host is blank.
■The agent's GetClientConfig() method indicates that the empty
preferred host is null.
Managing the Preferred Host in 10g WebGates
15-52 Administrator's Guide for Oracle Access Management
Use the setAllowEmptyHostIdentifier WLST command, described in the following
section, to manage this feature.
setAllowEmptyHostIdentifier
Registering and Managing OAM 11g Agents 15-53
setAllowEmptyHostIdentifier
Enables and disables the use of an empty preferred host parameter.
15
Description
Enables or disables the use of an empty preferred host parameter. The following
parameters (added to the oam-config.xml file) will be set to enable or disable an empty
preferred host parameter in the ObAccessClient.xml file.
<Setting Name="AutoUpdateHostIdentifier"
Type="xsd:string">AUTO_UPDATE_HOSTID</Setting>
<Setting Name="AllowEmptyHostIdentifier"
Type="xsd:boolean">true</Setting>
15
Syntax
setAllowEmptyHostIdentifier(enable="true/false")
15
Sample
setAllowEmptyHostIdentifier(enable ="true")
Argument Definition
enable
Set to true or false to allow for an empty host identifier or not.
setAllowEmptyHostIdentifier
15-54 Administrator's Guide for Oracle Access Management
16
Maintaining Access Manager Sessions 16-1
16
Maintaining Access Manager Sessions
An Access Manager session is created during authentication and bound to both the
user and the client with which the user has authenticated. Access Manager sessions are
maintained to provide tracking and policy enforcement (performed either manually by
an Administrator or using automated flows) for a given session's lifecycle. The Access
Manager session lifecycle consists of state transitions for session creation, updates,
idleness, and expiration.
This chapter describes concepts and procedures for Access Manager sessions.
■Introducing Access Manager Session Management
■Understanding Server-Side Session Management
■Server-Side Session Enforcement Examples
■Configuring the Server-Side Session Lifecycle
■Managing Active Server-Side Sessions
■Validating Server-Side Session Operations
■Understanding Client-Side Session Management
■Using WLST To Configure Session Management
16.1 Introducing Access Manager Session Management
With this 11gR2 PS2 release of Oracle Access Management, Access Manager sessions
can be managed from either the server side or the client side.
■Server-side session management (also referred to as Coherence-based session
management) is the default session management option developed for Access
Manager. It allows for advanced session management across nodes via
Coherence-based caching. Offering reliable performance and advanced features
(including impersonation, session sniping, identity context propagation and the
like), server side session management is recommended for most deployments -
especially internal ones where rich session management features are desired. More
details are documented in:
–"Understanding Server-Side Session Management" on page 16-2
–"Server-Side Session Enforcement Examples" on page 16-7
–"Configuring the Server-Side Session Lifecycle" on page 16-8
–"Managing Active Server-Side Sessions" on page 16-12
–"Validating Server-Side Session Operations" on page 16-15
Understanding Server-Side Session Management
16-2 Administrator's Guide for Oracle Access Management
■Client-side session management (also referred to as cookie-based session
management) manages sessions using browser cookies; it is essentially stateless.
Client side session management offers higher performance with a lightweight
footprint when compared to the Coherence-based option. It stores session details
in the browser cookie with no information saved on the server-side and is most
appropriate for very large deployments where advanced server-side session
management features are not needed. More details are documented in
"Understanding Client-Side Session Management" on page 16-16.
See "Using WLST To Configure Session Management" on page 16-16 for instructions
on how to configure the session management option.
16.2 Understanding Server-Side Session Management
This section provides the following topics:
■Securing Access Manager Sessions
■Understanding the Access Manager Session Lifecycle, States, and Enforcement
■Access Manager Sessions and the Role of Oracle Coherence
16.2.1 Securing Access Manager Sessions
Session security begins with a secure installation. For installation details see the Oracle
Fusion Middleware Installation Guide for Oracle Identity and Access Management.
The HTTPS protocol, Oracle Coherence and database encryption are some of the ways
in which Access Manager supports server-side session security. The following list
describes how this support can work.
■HTTPS Protocol
Access Manager helps prevent session fixation by providing IP address checks by
the Proxy. To further help prevent session fixation, be sure to use the secure
HTTPS protocol for communication between WebGates and OAM Servers.
■Oracle Coherence
Data is not encrypted in-memory; however, data is protected over the wire. Oracle
Coherence communicates between the different Access Manager instances on
various servers, and this communication is secured in the following ways.
–Coherence supports communication only between hosts that have been
previously identified. This is done as a range of IP addresses, or by specific
host names. Access Manager configuration files contain entries for each server
that participates in the communication. During startup, this information is
provided to Coherence ensuring that only authorized servers participate in the
communication.
Note: Cookie-based sessions can be accessed only from a browser
request context and not directly from the server.
See Also: Oracle Fusion Middleware Administrator's Guide for
details about configuring secure communications between Oracle
Fusion Middleware components using SSL.
Understanding Server-Side Session Management
Maintaining Access Manager Sessions 16-3
–Coherence uses mutually-authenticated SSL between all servers in the cluster.
The jceks keystore file, which holds the applicable keys and certificates, is
created during installation.
For more information, see "Access Manager Sessions and the Role of Oracle
Coherence" on page 16-6 as well as the Oracle Coherence documentation.
■Database Encryption
The Session Management Engine does not encrypt data. For security concerns, use
an in-database encryption such as Oracle Advanced Security.
16.2.2 Understanding the Access Manager Session Lifecycle, States, and Enforcement
The session lifecycle refers to a set of states with defined transitions from one state to
another that depend on user activity (or lack thereof), and manual (or automated)
Administrator activity. Administrators can define the following global session lifecycle
settings:
■Session Lifetime
■Idle Timeout
■Maximum number of Sessions
■Database Persistence of Active Sessions
Session lifecycle states include those in Table 16–1.
For more information, see the following topics:
■About Global Session Enforcement Checks
■About Session Removal
■About Step-Up and Step-Down Authentication and Credentials
■About Optional Application-Specific Session Enforcement
Note: Idle Timeout can also be implemented as application-specific
settings, as described later.
Table 16–1 Session Lifecycle States
State Description
Active Newly-created sessions are active. A session is created when the user is
authenticated by Access Manager.
The session remains active until Access Manager determines that the session must
transition into one of the other states in this table.
Note: Administrators can delete only active sessions.
Idle An active session becomes idle when the user does not access Access
Manager-protected content for the period defined by an Administrator.
When an active session becomes idle, the user must re-authenticate to proceed.
When re-authentication is successful, the session returns to the Active state; session
attribute values are preserved through this process.
Expired An active session expires when the duration of the session exceeds the defined
lifetime. An expired session is completely inaccessible and eligible for deletion.
When an active session expires, the user must re-authenticate to proceed.
When re-authentication is successful, a new session is created; however, session
attribute values are not preserved (as they are for Idle states).
Understanding Server-Side Session Management
16-4 Administrator's Guide for Oracle Access Management
■About Timeout with Multiple-Agent Types: OSSO and OAM Agents
■About OpenSSO Agents
16.2.2.1 About Global Session Enforcement Checks
Each Access Manager session holds the following attributes and applicable values.
■Session creation time
■Last access time
The values of these attributes are compared for session enforcement as described in
Table 16–2.
During transitions to the Idle state, underlying session attributes are preserved
because the user previously satisfied authentication criteria and the data is trusted.
However, continued access to protected resources based on that session, and resulting
modification of data within that session, is not allowed until the user re-authenticates,
proving not to be a malicious user with access to an unlocked computer.
16.2.2.2 About Session Removal
A session can be removed by any of the actions described in Table 16–3.
16.2.2.3 About Step-Up and Step-Down Authentication and Credentials
On occasion, multiple forms of authentication are required and performed within a
single session to complete a step-up flow. In a step-up flow, a user authenticates to
access protected content and later in the same session, the user requests other, more
sensitive content and is required to authenticate again to access it at a more stringent
level. In a step-up flow, multiple authentications always occur in order of the
increasing authentication level. Each session holds the Authentication Level attribute
for step-up authentication enforcement.
Table 16–2 Session Checks for State Changes
Session Check Description
Is the Session Idle? Compares the last access time against the configured Idle Timeout value.
Exceeding the configured period triggers a change from the Active to the Idle
state.
Is the Session Expired? Compares the session creation time against the configured Session Lifetime.
Exceeding the configured period triggers a change from the Active to the Expired
state.
Table 16–3 Session Removal
Action Description
Expiration Expired sessions are eligible for removal based on their creation time. Actual
removal is determined by the storage mechanism. The session is removed from the
distributed cache using a background task running on the server; it is removed
from the database using a similar background task, an optionally-enabled job
within the database itself, or both methods in combination.
Once a session has been deleted from storage on all tiers (local and distributed
caches, and from the database if enabled), the session is removed.
User Logout User Logout triggers immediate removal from the distributed cache, subject to
present volume of DB session writes and performance.
Termination Termination is identical to user log out whether the session is interactively
terminated through the Administration Console or in an automated way--as part of
an Oracle Identity Management user lockout or de-provisioning flow.
Understanding Server-Side Session Management
Maintaining Access Manager Sessions 16-5
A re-authentication level might be a step down from the session. If the
re-Authentication Level is less than that previously contained in the session, the user
has completed a step-down process. Upon successful re-authentication, the session is
restored to the Active state with an Authentication Level that is equal to the lower
level of the authentication scheme used. If the user later attempts to access content that
is protected at a higher level, step-up authentication occurs.
16.2.2.4 About Optional Application-Specific Session Enforcement
Access Manager enforces limitations on user access to resources in a more granular
way than is possible with a single set of global session timings, or single set of
authentication schemes in which access depends solely on a single authentication
level. Access to certain data has more stringent requirements, while access to all other
data is configured globally.
Administrators can choose to override global session timeout settings on a per
application basis, defined as part of Application Domain settings. Optional
application-specific session configuration provides:
■The ability to declare session idle timings on a per-application basis, which is
generally more stringent than the global idle timing defined within the
deployment as a whole.
■The ability to require the user to re-authenticate after a per-application session
inactivity timeout.
Table 16–4 describes session enforcement when you have defined Application
Domain-specific overrides to global session settings.
16.2.2.5 About Timeout with Multiple-Agent Types: OSSO and OAM Agents
The idle timeout is applied appropriately even if the session is operating in a
disconnected state. (A disconnected state occurs if mod_osso requests are being made
but not by the WebGate. In this case, the session appears to have idled out to the
server.) To enable global logout for the OSSO Agent, the Session Management Engine
reconciles a period of inactivity with the OAM Agent against a period of activity with
the OSSO Agent.
mod_osso agents support granular timeout only if the Global Inactivity TimeOut
feature is enabled (using the
editGITOValues
WLST command). The OAM_GITO
cookie is needed in special cases to support timeout with multiple types of agents
working with OAM Server (such as mod_osso and WebGate). If a user leaves an active
session (with an OAM Agent), starts a session with an OSSO Agent, and then returns
to the initial session (with the OAM Agent, now inactive), the Session Management
Engine reconciles the period of inactivity with the OAM Agent against the period of
activity with the OSSO Agent to enable global logout for the OSSO Agent.
Table 16–4 Application Domain-Specific Overrides
Override Description
Is the Session Idle? Compares the last access time against the configured Idle Timeout
value for the defined Application Domain only. Exceeding the
configured period triggers a change from the Active to the Idle state.
Is the Session Expired? Compares the session creation time against the configured Session
Lifetime. Exceeding the configured period triggers a change from the
Active to the Expired state for the defined Application Domain group
only.
Understanding Server-Side Session Management
16-6 Administrator's Guide for Oracle Access Management
16.2.2.6 About OpenSSO Agents
In the context of session management, OpenSSO agents are equivalent to WebGates.
Unlike mod_osso, OpenSSO Agents do not operate in a disconnected state.
16.2.3 Access Manager Sessions and the Role of Oracle Coherence
Access Manager sessions can be configured as Persisted or Distributed sessions. The
default Access Manager configuration is the Persisted Sessions but you can use the
Oracle Access Management Console to change this.
■When Access Manager is configured for Persisted Sessions, all user sessions are
stored in a backing database and are available across server restarts. Recently
created sessions and the most frequently used sessions will also be stored in
memory in the Coherence cache. The sessions are written out to the database in a
batched mode in an asynchronous thread, enabling faster latencies during session
creation and updates. When requested by the server, the Coherence cache
transparently fetches either its local copy or the copy stored in the backing
database based on the number of cache hits at the time. The size of the in-memory
cache can be small enough to accommodate active sessions. The size of the
Coherence cache is configurable; by default, it is defined as 100 MB.
■When Access Manager is configured for Distributed Sessions, the user sessions are
stored only in the in-memory Coherence Cache. These sessions are not available
across server cluster restarts. However if any specific node is stopped, the backup
sessions of that node will used. The total sessions retained are restricted to the size
of the Coherence cache - configurable using the Oracle Access Management
Console. If more users login than can be stored in the cache, the oldest non-active
sessions are deleted from the cache. A user whose session has been deleted from
the cache will have to login again to be recognized and granted access to protected
resources.
The Coherence cache size required for either of the described configurations is
calculated using the following formula.
S = N * (1 + b) * s / n
■S is the size of heap to be allocated to the Coherence Session cache per OAM
server. The size of the heap allocated to sessions per OAM node may be updated
in the OAM configuration file under the Setting element name
DistributedCacheMaxSize. This update to the configuration requires, at the least, a
rolling restart of the servers.
■N is the maximum number of sessions to be stored in the cache.
Note: Oracle strongly recommends that you change the value of the
Idle Timeout parameter when using the OAM_GITO cookie:
1. Login to the OAM Console as administrator.
2. Click the System Configuration tab.
3. Click Common Settings.
4. Change the value for the Idle Timeout parameter (in the Session section)
so that it matches the value of the OAM_GITO cookie as defined.
The OAM_GITO cookie is enabled and configured using the
editGITOValues
WLST command. For details, see the Oracle
Fusion Middleware WebLogic Scripting Tool Command Reference for
Identity and Access Management.
Server-Side Session Enforcement Examples
Maintaining Access Manager Sessions 16-7
■b is the number of backup copies.
■s is the average size of a session object. The average size of a session object may
vary based on attributes and responses that are stored in the session. This value
may be discovered in any installation by examining the Coherence mbeans for
backing store of SmeNearCache cache.
■n is the number of OAM server nodes that participate in the cluster.
16.3 Server-Side Session Enforcement Examples
Satisfying the authentication scheme of a given level provides access to all resources
protected at lower levels. Additionally, all authentication schemes of a given level are
viewed as equivalent. This section provides a simple session enforcement example
based on a single authentication scheme used in two application domains as well as a
more complex example based on multiple authentication schemes used in two
application domains.
■Example 1: Single Authentication Scheme
■Example 2: Multiple Authentication Schemes
16.3.1 Example 1: Single Authentication Scheme
Consider the following configuration:
■A single authentication scheme (S1) defined using Level 2
■Application domains D1 and D2
■All resources within each domain are protected with a single authentication policy,
which uses S1, and a single authorization policy.
■Global Session Configuration:
–Session Lifetime: 90 minutes
–Idle Session Timeout: 0 (session never idles out)
–Application Domain Timeout: 30 minutes
Now consider the outcomes in Table 16–5.
16.3.2 Example 2: Multiple Authentication Schemes
In previous releases of Access Manager, a session could only have its authentication
level reduced in the context of an Oracle Identity Management integration self-service
flow (such as forced password reset). In this release, step-down authentication occurs
Table 16–5 Session Content: Single Authentication Scheme
Time (Delta) Action Access Allowed or Denied Session Content
0 Access to D1 Denied due to no session null
1 Authentication with S1 and
Access to D1
Allowed because Authentication scheme is
satisfied
Level 2, authentication
time 1
21 Access to D2 Allowed Level 2, authentication
time 1
66 Access to D1 Denied due to Application Domain Timeout
(based on the parameters configured)
Level 2, authentication
time 1
67 Authentication with S1 and
Access to D1 and D2
Both Allowed because the Authentication Sceme is
satisfied
Level 2, authentication
time 67
Configuring the Server-Side Session Lifecycle
16-8 Administrator's Guide for Oracle Access Management
when a session times out as a matter of course--until the user happens to provide new
credentials that satisfy a scheme of the same level as the maximum held by the session
previously. Otherwise, from the authentication perspective, it is as if the session is new
and further step-up is required. Consider this example with two authentication
schemes (for step-up and step-down).
■Authentication schemes S1 (Level 2) and S2 (Level 3)
■Application domains D1 and D2
■All resources within each domain are protected with a single authentication policy,
and a single authorization policy
■D1 uses S1; D2 uses S2
■Global Session Configuration:
–Session Life: 240 mins
–Idle Timeout: 30 mins
–Appdomain 2 (D2) Timeout: 15 mins (appdomain setting)
When accessing resources from D1, timeout will occur after 30 minutes (global timeout
setting); D2 timeout will happen after 15 mins since its timeout value is overridden at
the global level. Table 16–6 shows the resulting outcomes.
The access order does have an impact on the outcome. For instance, the last D1 access
could have been allowed if the user had chosen to first pursue access to the D2
application after credentials had expired. For example:
■Authentication S2 with Access to D2 Allowed: L3 scheme satisfied; resulting level
of the now (again) active session same as before. Session Content: Level 3,
authentication time 51
■Access to D1 Allowed: Level 3 credentials also sufficient for Level 2-protected
access. Session Content: Level 3, authentication time 51.
16.4 Configuring the Server-Side Session Lifecycle
Session Lifecycle settings can be defined using the Oracle Access Management
Console. When you define either global or application-specific session lifecycle
settings, any timing interval set to 0 cancels the corresponding check. For example if
Table 16–6 Session Outcomes: Multiple Authentication Schemes
Time (Delta) Action Access Allowed or Denied Session Content
0 Access D1 resource
(RD1)
Access allowed after successful login Timeout for D1 will be set to
0+30=30 (30 is default global timeout
as D1 has not overriden timeout at
the Application Domain level)
1 (implies
after 1
minute)
Access D2 resource
(RD2)
Access allowed post credential challenge (user
will be prompted for credentials since D2 is
protected using a higher authentication
scheme)
Timeout of D2 will be set to 1+15=16
t>16 and t<30
(say t=20)
Access RD1 and RD2 Allowed access to RD1 because timeout of
D1=30. Allowed access to RD2 after providing
credentials since timeout of D2=16
The new timeout of D2 is 16
40 Access RD1 Allowed: D1 resource will be allowed since
timeout is 50
55 Access RD1 and RD2 Allowed to access both resources after user is
successfully challenged for credentials.
Timeout of D1 is now 85 (55+30)
Timeout of D2 is now 70 (55+15)
Configuring the Server-Side Session Lifecycle
Maintaining Access Manager Sessions 16-9
idle timeout is set to 0, sessions never idle out. With a session lifetime of 0, sessions
never expire. In all cases, applicable data is tracked and updated in the session, just as
if it is being checked on a per-request basis.
This section provides the following topics:
■About Global Session Lifecycle Settings
■About Application-Specific Session Overrides
■Viewing or Modifying Global Session Settings
■Viewing or Modifying Optional Application-Specific Session Overrides
16.4.1 About Global Session Lifecycle Settings
Access Manager session lifecycle settings are defined as part of the Common Settings
shared by all OAM Servers. Figure 16–1 shows the lifecycle attributes that you can
configure on the Common Settings page.
Figure 16–1 Global Session Details: Common Settings Page
Table 16–7 describes the global session lifecycle settings and their defaults. Sessions
can operate in a disconnected mode (mod_osso, for example). Therefore, changes to
the configuration establishing your session rules apply only to new sessions. To apply
changes immediately, Oracle recommends that you terminate existing sessions and
force users to create new ones that adhere to your new rules.
See Also: Oracle Fusion Middleware Performance and Tuning
Guide
Table 16–7 Global Session Settings
Setting Description
Session Lifetime (minutes) The amount of time, in minutes, that a user's authentication session
remains active. When the lifetime is reached, the session expires.
Default = 1440 minutes (24 hours specified in an integer representing
minutes)
A value of zero (0) disables this setting. Any value between 0 (zero) and
2147483647 is allowed.
Note: An expired session is automatically deleted from the in-memory
caches (or database).
Configuring the Server-Side Session Lifecycle
16-10 Administrator's Guide for Oracle Access Management
16.4.2 About Application-Specific Session Overrides
Application-specific access is tracked from the initial application-access time and is
updated only as further requests are made of that Application Domain. In other
words, the user's authentication and the authentication state are under control of
Access Manager and the Administrator. The current idle time for a given application is
shared between Access Manager and the application. The application provisions its
own run time data for the user on a per-session basis and needs to remove it as soon as
possible to make room for others.
Administrators can add application-specific session overrides on the Summary tab of
an Application Domain. Table 16–8 lists application-specific settings that, when
specified, override global session settings.
Idle Timeout (minutes) The amount of time, in minutes, that a user's authentication session
remains active without accessing any Access Manager protected
resources. When the user is idle for a longer period, they are asked to
re-authenticate.
Default = 15 minutes
A value of zero (0) disables this setting. Any value between 0 (zero) and
2147483647 is allowed.
Note: Timed-out sessions are not deleted from the session manager.
Session data could be removed from memory but will still be available in
the persistant store (database). After re-authentication, the same session
will be re-activated.
See Also: "About Application-Specific Session Overrides"
Maximum Number of Sessions
per User
The exact number of sessions each user can have at one time. Use this
setting to configure multiple session restrictions for all users.
Any positive integer is allowed.
Specifying the count as "1", activates a special mode. If a user who
already has a session authenticates using another device (thereby
creating a new session), then their existing session is deleted. No error is
reported and no warning is given.
Note: Too high a number impacts performance and result in a security
risk. Oracle recommends less than 20 as a reasonable limit per user.
Otherwise there can be performance impact. For tuning information, see
Oracle Fusion Middleware Performance and Tuning Guide.
(Management) Maximum
Search Results
Maximum number of sessions fetched by default for a session query if
the result set is large.
Database Persistence for Active
Sessions Enabled
Persists active sessions to the configured database session store, in
addition to the local and distributed caches. Sessions are retained even if
all managed servers die off.
Default = Enabled (checked)
If this is overkill for your environment, or you want to perform
deployment sizing to take into account the database, you can clear the
checkbox and restart all OAM Servers to disable this function.
Table 16–8 Application-Specific Session Timing Overrides
Element Description
Idle timeout Access Manager previously stored the last access time value within the session. To
enforce maximum idle time on a per-application basis, Access Manager includes a
new application-specific last access time field to hold it. This is filled with the last
access time for each subset of domains visited within the course of a session, on
which a per-application idle timeout override has been defined. This is not
needed for domains on which an override has not been defined--no checking is
done against such data.
Default: undefined
Table 16–7 (Cont.) Global Session Settings
Setting Description
Configuring the Server-Side Session Lifecycle
Maintaining Access Manager Sessions 16-11
For more information, see "Viewing or Modifying Optional Application-Specific
Session Overrides" on page 16-11.
16.4.3 Viewing or Modifying Global Session Settings
Users with valid Administrator credentials can use the following procedure to modify
common session lifecycle settings using the Oracle Access Management Console.
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Common Settings from the View menu in the
Settings section.
3. On the Common Settings page, expand the Session section.
4. Click the arrow keys beside each list to increase or decrease session lifecycle
settings as needed (Table 16–7):
■Session Lifetime (minutes)
■Idle Timeout (minutes)
■Maximum Number of Sessions per User
■(Management) Maximum Search Results - denotes the number of sessions
fetched by default for a session query if the result set is large
■Database Persistence of Active Sessions Enabled
5. Check the box to enable Database Persistence for Active Sessions.
6. Click Apply to submit the changes (or close the page without applying changes).
7. Close the page when you finish.
8. Proceed to one of the following topics:
■"Viewing or Modifying Optional Application-Specific Session Overrides"
■"Managing Active Server-Side Sessions"
16.4.4 Viewing or Modifying Optional Application-Specific Session Overrides
Users with valid Administrator credentials can use the following procedure to modify
optional session settings for one or more application domains in a named group.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Access Manager section, click Application Domains.
3. Find and open the desired domain.
4. On the Summary tab, enter the following information to create (or add) this
domain to the group that uses session overrides (Table 16–8):
■Idle Timeout
5. Click Apply to submit the changes (or close the page without applying changes).
See Also: "About Global Session Lifecycle Settings"
See Also: "About Application-Specific Session Overrides" on
page 16-10
Managing Active Server-Side Sessions
16-12 Administrator's Guide for Oracle Access Management
6. Proceed to "Managing Active Server-Side Sessions".
16.5 Managing Active Server-Side Sessions
The Oracle Access Management Console Session Management page provides Search
controls that enable Administrators to create a query based on filter conditions, save
their Search Criteria for use later, and add fields to the query form to further refine the
search.
In the database store configuration, the session might exist in the database but not in
the cache. Session searches are based on the system time stamp. The database is
queried for sessions updated earlier than the time stamp (minus the write delay). The
cache is queried for sessions updated later than this time stamp. Resulting data found
in the cache and the database is merged. If duplicate results exist, cache data prevails.
Detailed performance metrics are generated for search operations.
This section describes how to locate and delete one or more sessions for a single user,
or for all users. It provides the following information:
■About the Session Management Pages
■Locating and Managing Active Sessions
16.5.1 About the Session Management Pages
Figure 16–2 illustrates the Session Management page, accessible from the
Configuration section of the Oracle Access Management Console. Additional details
follow the figure.
Figure 16–2 Common Configuration: Session Management Page
Table 16–9 describes Session Management page and Search controls that enable you to
create a query that is based on filter conditions.
Table 16–9 Session Management Controls and the Results Table
Name Description
Delete All User Sessions ... Choose this command button to delete the active sessions of all users.
Note: A Confirmation window appears where you can confirm or decline
the operation.
Managing Active Server-Side Sessions
Maintaining Access Manager Sessions 16-13
Saved Search Drop down menu that lists any search criteria saved previously for reuse.
The list of searches is made available whenever you save search criteria.
The drop down menu also has a Personalize ... option in addition to the
saved searches. If you choose Personalize, you can change the behavior
of the saved search criteria by making new choices such as Set as Default
or Run Automatically.
Match All Any Enables you to match either any of the criteria you have specified or
match all of the criteria you have specified during the search.
Note: When a resource is protected
byAnonymousScheme
, it is not
displayed in a session search.
User ID Enter a specific userID in the field and then click the Search button to
display all active sessions for this user. Incomplete strings and wild cards
are allowed. A drop down menu includes options like Starts With,
Equals, Contains and the like to assist in your search.
Client IP Address Enter a Client IP Address and then click the Search button to display all
active sessions for this user. Incomplete strings and wild cards are
allowed. The same list is available to assist your Userid search and your
Client IP Address.
Search Click this button to initiate a search based on criteria in the form.
Reset Click this button to clear the form of all criteria.
Add Fields Displays a drop down menu from which you can select different options
to add to your search form. This can include Client IP Address, ID Store,
Impersonating and other options.
1. Click the Add Fields button.
2. Select items in the list to add them to the form and click Save.
After adding an item, notice that a list is available to assist with the
search.
Reorder Displays a pop-up dialog allowing you to reorder the search fields.
View Choose commands from the View menu above the results table to
configure the table. Commands include:
■Columns: Displays a menu with the following options you can use
to hide or display specific details in the table:
■Detach: Expands the results table to a full-screen view
■Attach: Restores the Session Management page view.
■Reorder Columns: Specifies a new order for columns containing
session data in the results table.
Delete Choose this command button (red X) after selecting items in the results
table to delete.
Note: When session search criteria is generic (using just a wild card (*),
for example), there is a limitation on deleting a session from a large list of
sessions. Oracle recommends that your session search criteria is
fine-grained enough to obtain a relatively small set of results (ideally 20
or less).
Also: A Confirmation window appears where you can confirm or decline
the operation.
Detach Click Detach to expand the results table to a full-page view.
Note: If the table is already a detached full-page, click Detach to restore
the Session Management page.
Table 16–9 (Cont.) Session Management Controls and the Results Table
Name Description
Managing Active Server-Side Sessions
16-14 Administrator's Guide for Oracle Access Management
16.5.2 Locating and Managing Active Sessions
Users with valid Administrator credentials can use information in the following
procedure to configure the search results table, locate the active sessions of a specific
user, delete one or more sessions for a specific user, or delete all sessions for all users.
When a resource is protected by
AnonymousScheme
, it is not displayed in a session
search.
Skip any steps that do not apply to your requirements. The OAM Server must be
running.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Session Management.
The Session Management Search page appears with the Username field and a
results table.
3. Add Fields: From the Add Fields list, choose the desired field name (Table 16–9).
4. Choose Operators: Open the list of operators for the chosen search field, and
choose the desired function.
5. Find sessions:
a. In the desired query field, enter your criteria (with or without a wild card (*)).
b. Click the Search button to locate sessions that match either any or all your
criteria.
c. Review the results table.
d. Repeat if needed to further refine your search.
6. Configure the Results Table: Use functions on the View menu to create the
desired results table.
7. Delete sessions:
a. In the results table, click one or more sessions to remove.
b. Click the Delete (x) button to delete the selected sessions.
c. Click Yes to confirm deleting selected sessions (or click No to cancel the delete
operation).
Results table (not named) After searching for the active sessions of a specific user, results are
displayed in the table. Details include:
■Session ID: A unique, OAM-generated session Id.
■User ID:
■Impersonating:
■Creation Time: The day and time the session was created.
■Last Accessed: The day and time the session was last accessed
■Client IP: The IP address of the specified user.
■ID Store
■Impersonator
See Also: "About the Session Management Pages"
Table 16–9 (Cont.) Session Management Controls and the Results Table
Name Description
Validating Server-Side Session Operations
Maintaining Access Manager Sessions 16-15
d. Notify the user, if needed.
8. Delete sessions for all users:
a. Click the Delete All Sessions button in the upper-right corner.
b. Click Yes when you are asked to confirm.
9. Close the Session Management page when you finish.
10. Proceed to "Validating Server-Side Session Operations".
16.6 Validating Server-Side Session Operations
Use the following procedure to verify your configured session lifecycle operations.
1. Authenticate:
a. Access a resource from a browser using a credential other than your
Administrative credential.
b. Verify that the session exists, as described in "Locating and Managing Active
Sessions".
2. Multiple Sessions:
a. From a second browser (with cookies removed), access the same resource.
b. Verify that two sessions exist.
3. Delete all sessions, (Step 7 of "Locating and Managing Active Sessions") and
confirm that the Active sessions are removed.
4. Re-authentication Verification:
a. From the second browser (Step 2), access a different resource to confirm that
you must re-authenticate.
b. Enter credentials for the resource.
c. Verify that a session was created.
5. Database Verification:
a. Delete all sessions.
b. Connect to the database and run the following query:
SQL> select * from oam_session
c. Confirm that you see the following results:
no row selected
d. From the second browser, access a different resource.
e. Connect to the database and run the following query
SQL> select * from oam_session
f. Confirm that you see one row of data:
1 rows selected
g. Select rows from OAM_SESSION_ATTRIBUTES and confirm that data exists
for the user.
Understanding Client-Side Session Management
16-16 Administrator's Guide for Oracle Access Management
16.7 Understanding Client-Side Session Management
Client-side (or cookie-based) session management is a light weight session
management solution that reduces server-side overhead and provides better
scalability. It uses client-side cookies as the persistent mechanism for SSO sessions,
making the server stateless. Client-Side session management supports the following
features:
■Authentication
■Authorization (excluding session constrains and responses)
■OAM & OIM integration over TAP - excluding session deletion on attribute
change (account lock/disable, etc.)
■Step up authentication
■Inactivity time out with single web domain
16.8 Using WLST To Configure Session Management
The following WLST commands can be used to configure for server-side (default) or
client-side (cookie-based) session management.
■displaySSOSessionType
■configSSOSessionType
16.8.1 displaySSOSessionType
Online and offline command that allows you to view the session management
configuration.
16.8.1.1 Description
Allows you to view the session type configuration.
16.8.1.2 Syntax
displaySSOSessionType(domainHome="<domainHome>")
16.8.1.3 Example
displaySSOSessionType(domainHome="/oracle/product/OAM/domains/oam_domain")
16.8.2 configSSOSessionType
Online and offline command that allows you to configure session management as
COOKIE-BASED or DEFAULT.
16.8.2.1 Description
Configure session management for Access Manager.
Argument Definition
domainHome
Specifies the location for the Weblogic Server OR Cell Path for
WebSphere. This parameter is mandatory for WebSphere. When
Offline, a value is mandatory; when online, optional.
Using WLST To Configure Session Management
Maintaining Access Manager Sessions 16-17
16.8.2.2 Syntax
configSSOSessionType(type="<ssoSessionType>",
cookieDomain="<cookieDomain>",domainHome="<domainHome>")
16.8.2.3 Examples
configSSOSessionType(type="COOKIE_BASED",cookieDomain-".example.com")
configSSOSessionType(type="COOKIE_BASED",cookieDomain-".example.com",
domainHome="domainHome1")
configSSOSessionType(type="Default",cookieDomain=".example.com")
Argument Definition
type
Specifies the type of session store. Accepted values are COOKIE_
BASED or DEFAULT.
cookieDomain
Specifies the value of the SSO Session Timeout cookie domain.
domainHome
Specifies the location for the Weblogic Server OR Cell Path for
WebSphere. This parameter is mandatory for WebSphere. When
Offline, a value is mandatory; when online, optional.
Using WLST To Configure Session Management
16-18 Administrator's Guide for Oracle Access Management
Part V
Par t V
Implementing Multi-Data Centers
Oracle Access Management allows for distribution of identical copies of directory
service data across more than one data center. These multiple data centers (referred to
as multi-data centers) provide a scalable deployment model to support access
management requirements for millions of users.
The chapters in this section provide details on implementing and managing a
Multi-Data Center environment.
■Chapter 17, "Understanding Multi-Data Centers"
■Chapter 18, "Configuring Multi-Data Centers"
■Chapter 19, "Synchronizing Data In A Multi-Data Center"
■Chapter 20, "Setting Up the Multi-Data Center: A Sequence"
17
Understanding Multi-Data Centers 17-1
17
Understanding Multi-Data Centers
[15]
Oracle Access Manager allows for distribution of identical copies of directory service
data across more than one data center. These multiple data centers (referred to as
multi-data centers) provide a scalable deployment model to support access
management requirements for millions of users.
The Access Manager Multi-Data Center topology scales horizontally - within a single
data center by clustering multiple nodes, or across multiple data centers. This model
provides for load balancing as well as failover capabilities in the case that one of the
nodes or data centers goes down. This chapter contains introductory details.
■Introducing the Multi-Data Center
■Understanding Multi-Data Center Deployments
■Deploying Active-Active Multi-Data Center Topology
■Load Balancing Between Access Management Components
■Understanding Time Outs and Session Syncs
■Replicating a Multi-Data Center Environment
■Multi-Data Center Recommendations
17.1 Introducing the Multi-Data Center
Large organizations using Access Manager 11g typically deploy their applications
across multi-data centers to distribute load as well as address disaster recovery.
Deploying Access Manager in multi-data centers allows for the transfer of user session
details transparently after configuration of single sign-on (SSO) between them. The
scope of a data center comprises protected applications, WebGate agents, Access
Manager servers and other infrastructure entities including identity stores and
databases.
The Multi-Data Center approach supported by Access Manager is a Master-Clone
deployment in which the first data center is specified as the Master and one or more
Clone data centers mirror it. (Master and Clone data centers can also be referred to as
Supplier and Consumer data centers.) A Master Data Center is duplicated using
Test-to-Production (T2P) tools to create one or more cloned Data Centers. See Oracle
Fusion Middleware Administrator's Guide for information on T2P.
Note: Access Manager 11g supports scenarios where applications are
distributed across two or more data centers.
Introducing the Multi-Data Center
17-2 Administrator's Guide for Oracle Access Management
During setup of the Multi-Data Center, session adoption policies are configured to
determine where a request would be sent if the Master Data Center is down.
Following the setup, a manner of replicating data from the Master to the Clone(s) will
be designated. This can be done using the Automated Policy Sync (APS) Replication
Service or it can be done manually. See Chapter 18, "Configuring Multi-Data Centers"
and Chapter 19, "Synchronizing Data In A Multi-Data Center" for details on the setup
and synchronization process.
A data center may include applications, data stores, load balancers and the like. Each
data center includes a full Access Manager installation. The WebLogic Server domain
in which the instance of Access Manager is installed will not span data centers.
Additionally, data centers maintain user to data center affinity. Figure 17–1 illustrates
the Multi-Data Center system architecture.
Figure 17–1 Multi-Data Center System Architecture
All applications are protected by WebGate agents configured against Access Manager
clusters in the respective local data centers. Every WebGate has a primary server and
one or more secondary servers; WebGate agents in each data center have Access
Manager server nodes from the same data center in the primary list and nodes from
other data centers in the secondary list. Thus, it is possible for a user request to be
routed to a different data center when:
■A local data center goes down.
■There is a load spike causing redistribution of traffic.
■Certain applications are deployed in only one data center.
■WebGates are configured to load balance within one data center but failover across
data centers.
The following sections contain more information on how the Multi-Data Center
solution works.
■Understanding Cookies for Multi-Data Center
Note: Global load balancers are configured to route HTTP traffic to
the geographically closest data center. No load balancers are used to
manage Oracle Access Protocol traffic.
Introducing the Multi-Data Center
Understanding Multi-Data Centers 17-3
■Understanding Session Adoption During Authorization
■Understanding Session Indexing
■Supported Multi-Data Center Topologies
17.1.1 Understanding Cookies for Multi-Data Center
The following sections contain information on the SSO cookies enhanced and used by
the Multi-Data Centers.
■OAM_ID Cookie
■OAMAuthn / ObSSO WebGate Cookies
■OAM_GITO (Global Inactivity Time Out) Cookie
17.1.1.1 OAM_ID Cookie
The OAM_ID cookie is the SSO cookie for Access Manager and holds the attributes
required to enable the MDC behavior across all Data Centers. If a subsequent request
from a user in the same SSO session is routed to a different Data Center in the
Multi-Data Center topology, session adoption is triggered per the configured session
adoption policies. Session adoption refers to the action of a Data Center creating a local
user session based on the submission of a valid authentication cookie (OAM_ID) that
indicates a session for the user exists in another other Data Center in the topology. (It
may or may not involve re-authentication of the user.) When a user session is created
in a Data Center, the OAM_ID cookie will be augmented/updated with the
clusterid
of the Data Center, a
sessionid
and the
latest_visited_clusterid
.
In Multi-Data Center deployments, OAM_ID is a host-scoped cookie. Its domain
parameter is set to a virtual host name which is a singleton across data centers and is
mapped by the global load balancer to the Access Manager servers in the Access
Manager data center based on the load balancer level user traffic routing rules (for
example, based on geographical affinity). The OAM_ID cookie is not accessible to
applications other than the Access Manager servers.
17.1.1.2 OAMAuthn / ObSSO WebGate Cookies
OAMAuthn is the WebGate cookie for 11g and ObSSO is the WebGate cookie for 10g.
On successful authentication and authorization, a user will be granted access to a
protected resource. At that point, the browser will have a valid WebGate cookie with
the
clusterid:sessionid
of the authenticating Data Center. If authentication followed
by authorization spans across multiple Data Centers, the Data Center authorizing the
user request will trigger session adoption by retrieving the session's originating
clusterid
from the WebGate cookie. (WebGates need to have the same host name in
each data center due to host scoping of the WebGate cookies.) After adopting the
session, a new session will be created in the current Data Center with the synced
session details.
Introducing the Multi-Data Center
17-4 Administrator's Guide for Oracle Access Management
17.1.1.3 OAM_GITO (Global Inactivity Time Out) Cookie
OAM_GITO is a domain cookie set as an authorization response. The session details of
the authentication process will be recorded in the OAM_ID cookie. If the authorization
hops to a different Data Center, session adoption will occur by creating a new session
in the Data Center servicing the authorization request and setting the session index of
the new session as the incoming
sessionid
. Since subsequent authentication requests
will only be aware of the clusterid:sessionid mapping available in the OAM_ID cookie,
a session hop to a different Data Center for authorization will go unnoticed during the
authentication request. To address this gap, an OAM_GITO cookie (which also
facilitates timeout tracking across WebGate agents) is introduced.
During authorization, the OAM_GITO cookie is set as a domain cookie. For
subsequent authentication requests, the contents of the OAM_GITO cookie will be
read to determine the latest session information and the inactivity/idle time out
values. The OAM_GITO cookie contains the following data.
■Data Center Identifier
■Session Identifier
■User Identifier
■Last Access Time
■Token Creation Time
17.1.2 Understanding Session Adoption During Authorization
Multi-Data Center session adoption is supported during the authorization flow. After
successful authentication, the OAMAuthn cookie will be augmented with the cluster
Note: The WebGate cookie cannot be updated during authorization
hence the newly created
sessionid
cannot be persisted for future
authorization references. In this case, the remote sessionid and the
local sessionids are linked through
session indexing
. During a
subsequent authorization call to a Data Center, a new session will be
created when:
■MDC is enabled.
■A session matching the sessionid in the WebGate cookie is not
present in the local Data Center.
■There is no session with a Session Index that matches the
sessionid in the WebGate cookie.
■A valid session exists in the remote Data Center (based on the
MDC SessionSync Policy).
In these instances, a new session is created in the local Data Center
with a Session Index that refers to the sessionid in the WebGate
cookie.
Note: For the OAM_GITO cookie, all WebGates and Access Manager
servers should share a common domain hierarchy. For example, if the
server domain is
.us.example.com
then all WebGates must have (at
least)
.example.com
as a common domain hierarchy; this enables the
OAM_GITO cookie to be set with the
.example.com
domain.
Introducing the Multi-Data Center
Understanding Multi-Data Centers 17-5
ID details of the Data Center where authentication has taken place. During
authorization, if the request is routed to a different Data Center, Access Manager
runtime checks to determine whether it is a Multi-Data Center scenario by looking for
a valid remote session. If one is located, the Multi-Data Center session adoption
process is triggered per the session adoption policy.
The session adoption policy can be configured so that the clone Access Manager
cluster would make a back-end request for session details from the master Access
Manager cluster using the Oracle Access Protocol (OAP). The session adoption policy
can also be configured to invalidate the previous session so the user has a session only
in one data center at a given time. Following the session adoption process, a new
session will be created in the Data Center servicing the authorization request.
More details on session adoption can be found in the Section 17.2, "Understanding
Multi-Data Center Deployments."
17.1.3 Understanding Session Indexing
During an authorization call to a Data Center, a new session will be created in the local
Data Center with a Session Index that refers to the session identifier in the
OAMAuth/ObSSO cookie. This will occur if all of the following conditions are met:
■Session matching Session ID in the OAMAuth/ObSSO cookie is not present in the
local Data Center.
■MDC is enabled.
■No session with Session Index matching Session ID in the OAMAuth/ObSSO
cookie.
■Valid Session exists in the remote Data Center based on the MDC SessionSync
Policy.
17.1.4 Supported Multi-Data Center Topologies
Access Manager supports several Multi-Data Center topologies. The following
sections contain details on these modes.
■ The MDC Active-Active Mode
■ The MDC Active-Passive Mode
■ The MDC Active-Hot Standby Mode
17.1.4.1 The MDC Active-Active Mode
An Active-Active topology is when Master and Clone data centers are exact replicas
and active at the same time. They cater to different sets of users based on defined
criteria; geography, for example. A load balancer routes traffic to the appropriate Data
Center. Figure 17–2 illustrates a Multi-Data Center set up in Active-Active mode
during normal operations.
Note: Since OAMAuthn cookie updates are not supported during
authorization, the newly created session's session index will be set to
that of the incoming session ID. See Understanding Session Indexing.
Introducing the Multi-Data Center
17-6 Administrator's Guide for Oracle Access Management
Figure 17–2 Active-Active Deployment Mode
In Figure 17–2, the New York Data Center is designated as the Master and all policy
and configuration changes are restricted to it. The London Data Center is designated
as a Clone and uses T2P tooling and utilities to periodically synchronize data with the
New York Data Center. The global load balancer is configured to route users in
different geographical locations (US and Europe) to the appropriate data centers (New
York or London) based on proximity to the data center (as opposed to proximity of the
application being accessed). For example, all requests from US-based User 1 will be
routed to the New York Data Center (NYDC) and all requests from Europe-based User
2 will be routed to the London Data Center (LDC).
In this example, if NYDC was overloaded with requests, the global load balancer
would start routing User 1 requests to the clone Access Manager cluster in LDC. The
clone Access Manager cluster can tell (from the user's OAM_ID cookie) that there is a
valid session in the master cluster and would therefore create a new session without
prompting for authentication or re-authentication. Further, the session adoption policy
can be configured such that the clone Access Manager cluster would make a back-end
request for session details from the master Access Manager cluster using the Oracle
Access Protocol (OAP). The session adoption policy can also be configured to
invalidate the remote session (the session in NYDC) so the user has a session only in
one data center at a given time.
Figure 17–3 illustrates how a user might be rerouted if the Master cluster is overloaded
or down. If the Master Access Manager cluster were to go completely down, the clone
Access Manager cluster would try to obtain the session details of User 1 but since the
latter would be completely inaccessible, User 1 would be forced to re-authenticate and
establish a new session in the clone Access Manager cluster. In this case, any
information stored in the previous session is lost.
Note: The Access Manager clusters in Figure 17–2 are independent
and not part of the same Oracle WebLogic domain. WebLogic domains
are not recommended to span across data centers.
Understanding Multi-Data Center Deployments
Understanding Multi-Data Centers 17-7
Figure 17–3 Active-Active Mode Failover
More details on an Active-Active topology can be found in "Deploying Active-Active
Multi-Data Center Topology."
17.1.4.2 The MDC Active-Passive Mode
An Active-Passive topology is when the primary Data Center is operable but the clone
Data Center is not. In this topology, the clone can be brought up within a reasonable
time in cases when the primary Data Center fails. Thus, in the Active-Passive Mode
one of the data centers is passive and services are not started. In this use case, the data
center does not have to be brought up immediately but within a reasonable amount of
time in cases when the primary data center fails. There is no need to do an MDC setup
although policy data will be kept in sync.
17.1.4.3 The MDC Active-Hot Standby Mode
Active–Hot Standby is when one of the Data Centers is in hot standby mode. In this
case, traffic will not be routed to the Hot Standby Data Center unless the Active Data
Center goes down. In this use case, you do not need additional data centers for traffic
on a daily basis but only keep one ready. Follow the Active-Active Mode steps to
deploy in Active-Hot Standby Mode but do not route traffic to the center defined as
Hot Standby. The Hot Standby center will continue to sync data but will only be used
when traffic is directed there by the load balancer or by an administrator.
17.2 Understanding Multi-Data Center Deployments
In a Multi-Data Center deployment, each data center will include a full Access
Manager installation; WebLogic Server domains will not span the Data Centers. Global
load balancers will maintain user to Data Center affinity although a user request may
be routed to a different Data Center when:
■The data center goes down.
■A load spike causes redistribution of traffic.
■Each Data Center is not a mirror of the other. For example, certain applications
may only be deployed in a single Data Center.
Note: An Active-Active topology with agent failover is when an
agent has Access Manager servers in one Data Center configured as
primary and Access Manager servers in the other Data Centers
configured as secondary to aid failover scenarios.
Understanding Multi-Data Center Deployments
17-8 Administrator's Guide for Oracle Access Management
■WebGates are configured to load balance within the Data Center and failover
across Data Centers.
Figure 17–4 illustrates a basic Multi-Data Center deployment.
Figure 17–4 Multi-Data Center Deployment
The following sections describe several deployment scenarios.
■Understanding Session Adoption Without Re-authentication, Session Invalidation
or Session Data Retrieval
■Understanding Session Adoption Without Re-authentication But With Session
Invalidation & Session Data Retrieval
■Understanding Session Adoption Without Re-authentication & Session
Invalidation But With On-demand Session Data Retrieval
■Understanding Authentication & Authorization Requests Served By Different
Data Centers
■Understanding Logout and Session Invalidation
■Understanding Stretch Cluster Deployments
17.2.1 Understanding Session Adoption Without Re-authentication, Session
Invalidation or Session Data Retrieval
The following scenario illustrates the flow when the Session Adoption Policy is
configured without re-authentication, remote session invalidation and remote session
data retrieval. It is assumed the user has affinity with DC1.
1. User is authenticated by DC1.
On successful authentication, the OAM_ID cookie is augmented with a unique
data center identifier referencing DC1 and the user can access applications
protected by Access Manager in DC1.
2. Upon accessing an application deployed in DC2, the user is routed to DC2 by a
global load balancer.
Note: The OAP connection used for back channel communication
does not support load balancing or failover so a load balancer needs to
be used.
Understanding Multi-Data Center Deployments
Understanding Multi-Data Centers 17-9
3. Access Manager in DC2 is presented with the augmented OAM_ID cookie issued
by DC1.
On successful validation, Access Manager in DC2 knows that this user has been
routed from the remote DC1.
4. Access Manager in DC2 looks up the Session Adoption Policy.
The Session Adoption Policy is configured without reauthentication, remote
session invalidation or remote session data retrieval.
5. Access Manager in DC2 creates a local user session using the information present
in the DC1 OAM_ID cookie (lifetime, user) and re-initializes the static session
information ($user responses).
6. Access Manager in DC2 updates the OAM_ID cookie with its data center
identifier.
Data center chaining is also recorded in the OAM_ID cookie.
7. User then accesses an application protected by Access Manager in DC1 and is
routed back to DC1 by the global load balancer.
8. Access Manager in DC1 is presented with the OAM_ID cookie issued by itself and
updated by DC2.
On successful validation, Access Manager in DC1 knows that this user has
sessions in both DC1 and DC2.
9. Access Manager in DC1 attempts to locate the session referenced in the OAM_ID
cookie.
■If found, the session in DC1 is updated.
■If not found, Access Manager in DC1 looks up the Session Adoption Policy
(also) configured without reauthentication, remote session invalidation and
remote session data retrieval.
10. Access Manager in DC1 updates the OAM_ID cookie with its data center identifier
and records data center chaining as previously in DC2.
17.2.2 Understanding Session Adoption Without Re-authentication But With Session
Invalidation & Session Data Retrieval
The following scenario illustrates the flow when the Session Adoption Policy is
configured without re-authentication but with remote session invalidation and remote
session data retrieval. It is assumed the user has affinity with DC1.
1. User is authenticated by DC1.
On successful authentication, the OAM_ID cookie is augmented with a unique
data center identifier referencing DC1.
2. Upon accessing an application deployed in DC2, the user is routed to DC2 by a
global load balancer.
3. Access Manager in DC2 is presented with the augmented OAM_ID cookie issued
by DC1.
On successful validation, Access Manager in DC2 knows that this user has been
routed from the remote DC1.
4. Access Manager in DC2 looks up the Session Adoption Policy.
Understanding Multi-Data Center Deployments
17-10 Administrator's Guide for Oracle Access Management
The Session Adoption Policy is configured without reauthentication but with
remote session invalidation and remote session data retrieval.
5. Access Manager in DC2 makes a back-channel (OAP) call (containing the session
identifier) to Access Manager in DC1 to retrieve session data.
The session on DC1 is terminated following data retrieval. If this step fails due to a
bad session reference, a local session is created as documented in Section 17.2.1,
"Understanding Session Adoption Without Re-authentication, Session Invalidation
or Session Data Retrieval."
6. Access Manager in DC2 creates a local user session using the information present
in the OAM_ID cookie (lifetime, user) and re-initializes the static session
information ($user responses).
7. Access Manager in DC2 rewrites the OAM_ID cookie with its own data center
identifier.
8. The user then accesses an application protected by Access Manager in DC1 and is
routed to DC1 by the global load balancer.
9. Access Manager in DC1 is presented with the OAM_ID cookie issued by DC2.
On successful validation, Access Manager in DC1 knows that this user has
sessions in DC2.
10. Access Manager in DC1 makes a back-channel (OAP) call (containing the session
identifier) to Access Manager in DC2 to retrieve session data.
If the session is found, a session is created using the retrieved data. If it is not
found, the OAM Server in DC1 creates a new session. The session on DC2 is
terminated following data retrieval.
17.2.3 Understanding Session Adoption Without Re-authentication & Session
Invalidation But With On-demand Session Data Retrieval
Multi-Data Center supports session adoption without re-authentication except that the
non-local session are not terminated and the local session is created using session data
retrieved from the remote DC. Note that the OAM_ID cookie is updated to include an
attribute that indicates which data center is currently being accessed.
17.2.4 Understanding Authentication & Authorization Requests Served By Different
Data Centers
Consider a scenario where an authentication request is served by the New York Data
Center (NYDC) but the authorization request is presented to the London Data Center
(LDC) because of user affinity. If Remote Session Termination is enabled, the scenario
requires a combination of the OAM_ID cookie, the OamAuthn/ObSSO authorization
cookie and the GITO cookie to perform the seamless Multi-Data Center operations.
This flow (and Figure 17–5 following it) illustrates this. It is assumed that the user has
affinity with NYDC.
1. Upon accessing APP1, a user is authenticated by NYDC.
On successful authentication, the OAM_ID cookie is augmented with a unique
data center identifier referencing NYDC. The subsequent authorization call will be
served by the primary server for the accessed resource, NYDC. Authorization
generates the authorization cookie with the NYDC identifier (cluster-id) in it and
the user is granted access to the APP1.
2. User attempts to access APP2 in LDC.
Understanding Multi-Data Center Deployments
Understanding Multi-Data Centers 17-11
3. The WebGate for APP2 finds no valid session in LDC and initiates authentication.
Due to user affinity, the authentication request is routed to NYDC where seamless
authentication occurs. The OamAuthn cookie contents are generated and shared
with the APP2 WebGate.
4. The APP2 WebGate forwards the subsequent authorization request to APP2's
primary server, LDC with the authorization cookie previously generated.
During authorization, LDC will determine that this is a Multi-Data Center scenario
and a valid session is present in NYDC. In this case, authorization is accomplished
by syncing the remote session as per the configured session adoption policies.
5. A new session is created in LDC during authorization and the incoming session id
is set as the new session's index.
Subsequent authorization calls are honored as long as the session search by index
returns a valid session in LDC. Each authorization will update the GITO cookie
with the cluster-id, session-id and access time. The GITO cookie will be re-written
as an authorization response each time.
lf a subsequent authentication request from the same user hits NYDC, it will use
the information in the OAM_ID and GITO cookies to determine which Data
Center has the most current session for the user. The Multi-Data Center flows are
triggered seamlessly based on the configured Session Adoption policies.
Understanding Multi-Data Center Deployments
17-12 Administrator's Guide for Oracle Access Management
Figure 17–5 Requests Served By Different Data Centers
17.2.5 Understanding Logout and Session Invalidation
In Multi-Data Center scenarios, logout ensures that all server side sessions across Data
Centers and all authentication cookies are cleared out. For session invalidation,
termination of a session artifact over the back-channel will not remove the session
cookie and state information maintained in the WebGates. However, the lack of a
server session will result in an Authorization failure which will result in
re-authentication. In the case of no session invalidation, the logout clears all server
side sessions that are part of the current SSO session across Data Centers. This flow
(and Figure 17–6 following it) illustrates logout. It is assumed that the user has affinity
with NYDC.
1. User with affinity to NYDC gets access to APP1 after successful authentication
with NYDC.
2. User attempts to access APP2.
Understanding Multi-Data Center Deployments
Understanding Multi-Data Centers 17-13
At this point there is a user session in NYDC as well as LDC (refer to section 2.4.5)
as part of SSO.
3. User logs out from APP1.
Due to affinity, the logout request will reach NYDC.
4. The NYDC server terminates the user's SSO session and logs out from all the SSO
partners.
5. The NYDC server sends an OAP terminate session request to all relevant Data
Centers associated with the SSO session - including LDC.
This results in clearing all user sessions associated with the SSO across Data
Centers.
Figure 17–6 Logout and Session Invalidation
17.2.6 Understanding Stretch Cluster Deployments
For data centers that are geographically very close and have a guaranteed latency of
less than 5 milliseconds, customers can choose a Stretch Cluster deployment. In this
case, unlike the traditional Multi Data Center deployment described in the preceding
sections, a single OAM cluster is stretched across multiple data centers; there are some
OAM nodes in one Data Center and the remaining nodes in another Data Center.
Though the deployment is spread across two data centers, Access Manager treats this
as a single cluster. The policy database would reside in one of the Data Centers. The
following limitations apply to a Stretch Cluster Deployment.
■Access Manager depends on the underlying WebLogic and Coherence layers to
keep the nodes in sync. The latency between Data Centers must be less than 5
milliseconds at all times. Any spike in the latency may cause instability and
unpredictable behavior.
■The cross data center chatter at runtime in a Stretch Cluster deployment is
relatively more than that in the traditional Multi Data Center deployment. In case
Deploying Active-Active Multi-Data Center Topology
17-14 Administrator's Guide for Oracle Access Management
of the latter, the runtime communication between Data Centers is restricted to
use-cases where a session has to be adopted across Data Centers.
■Since it is a single cluster across Data Centers, it does not offer the same level of
reliability/availability as a traditional multi data center deployment. The policy
database can become a single point of failure. In a traditional Multi Data Center
deployment, each Data Center is self-sufficient and operates independent of the
other Data Center which provides far better reliability.
Figure 17–7 illustrates a Stretch Cluster deployment while Figure 17–8 below it
illustrates a traditional MDC deployment. Oracle does recommend a traditional multi
data center deployment over a Stretch Cluster deployment. See also Section 17.1,
"Introducing the Multi-Data Center" for other topology illustrations.
Figure 17–7 Stretch Cluster Deployment
Figure 17–8 Traditional MDC Deployment
17.3 Deploying Active-Active Multi-Data Center Topology
An Active-Active topology is when Master and Clone Data Centers are exact replicas
of each other (including applications, data stores and the like). They are active at the
same time and cater to different sets of users based on defined criteria - geography, for
example. A load balancer routes traffic to the appropriate Data Center. Identical Access
Manager clusters are deployed in both locales with New York designated as the
Master and London as the Clone.
Deploying Active-Active Multi-Data Center Topology
Understanding Multi-Data Centers 17-15
Figure 17–9 illustrates the topology for a Multi-Data Center deployment in
Active-Active mode. The New York Data Center is designated as the Master and all
policy and configuration changes are restricted to it. The London Data Center is
designated as a Clone and uses T2P tooling and utilities to periodically synchronize
data with the New York Data Center. The global load balancer is configured to route
users in different geographical locations (US and Europe) to the appropriate data
centers (New York or Europe) based on proximity to the data center (as opposed to
proximity of the application being accessed). For example, all requests from US-based
User 1 will be routed to the New York Data Center (NYDC) and all requests from
Europe-based User 2 will be routed to the London Data Center (LDC).
Figure 17–9 Active-Active Topology
The Global Load Balancer is configured for session stickiness so once a user has been
assigned to a particular data center, all subsequent requests from that user would be
routed to the same data center. In this example, User 1 will always be routed to the
New York Data Center and User 2 to the London Data Center.
User requests in the respective data centers are intercepted by different WebGates
depending on the application being accessed. Each WebGate has the various nodes of
the Access Manager cluster within the same data center configured as its primary
servers. In this case, the WebGates load balance and failover the local data center.
Note: An Active-Active topology with agent failover is when an
agent has Access Manager servers in one Data Center configured as
primary and Access Manager servers in the other Data Centers
configured as secondary to aid failover scenarios.
Load Balancing Between Access Management Components
17-16 Administrator's Guide for Oracle Access Management
Any number of Clone data centers can be configured to distribute the load across the
globe. The only condition is that all Clone data centers are synchronized from a single
Master using T2P. Figure 17–10 below depicts an Active-Active Multi-Data Center
deployment across five data centers.
Figure 17–10 Active-Active Topology Across Multiple Data Centers
17.4 Load Balancing Between Access Management Components
The topology described earlier shows global and local load balancers for routing the
end user HTTP traffic to various data centers. Additionally, customers can choose to
deploy load balancers between the access manager components to simplify the
configuration of the access manager components by using virtual host names. For
example, instead of configuring the primary servers in each WebGate in the NYDC as
ssonode1.ny.acme.com, ssonode2.ny.acme.com and so on, they can all point to a single
virtual hostname like sso.ny.acme.com and the load balancer will resolve the DNS to
direct them to various nodes of the cluster. However, while introducing a load
balancer between Access Manager components, there are a few constraining
requirements to keep in mind.
■OAP connections are persistent and need to be kept open for a configurable
duration even while idle.
■The WebGates need to be configured to recycle their connections proactively prior
to the Load Balancer terminating the connections, unless the Load Balancer is
capable of sending TCP resets to both the Webgate and the server ensuring clean
connection cleanup.
Note: Administrators have the flexibility to configure the primary
servers for every WebGate in different orders based on load
characteristics. Running monitoring scripts in each data center will
detect if any of the Access Manager components – the WebGates or the
servers – are unresponsive so administrators can reconfigure the load
balancers to direct user traffic to a different data center.
Load Balancing Between Access Management Components
Understanding Multi-Data Centers 17-17
■The Load Balancer should distribute the OAP connection uniformly across the
active Access Manager Servers for each WebGate (distributing the OAP
connections according the source IP), otherwise a load imbalance may occur.
Figure 17–11 illustrates a variation of the deployment topology with local load
balancers (LBR 3 and LBR 4) front ending the clusters in each data center. These local
load balancers can be Oracle HTTP Servers (OHS) with
mod_wl_ohs
. The OAP traffic
still flows between the WebGates and the Access Manager clusters within the data
center but the load balancers perform the DNS routing to facilitate the use of virtual
host names.
Figure 17–11 Load Balancing Access Manager Components
Figure 17–12 illustrates a second variation of the deployment topology with the
introduction of a global load balancer (GLBR2) to front end local load balancers (LBR3
and LBR4). In this case, the host names can be virtualized not just within the data
center but across the data centers. The WebGates in each data center would be
configured to load balance locally but fail over remotely. One key benefit of this
topology is that it guarantees high availability at all layers of the stack. Even if the
entire Access Manager cluster in a data center were to go down, the WebGates in that
data center would fail over to the Access Manager cluster in the other data center.
Note: For information on monitoring Access Manager server health
with a load balancer in use, see Section 11.6, "Monitoring the Health of
an Access Manager Server."
Understanding Time Outs and Session Syncs
17-18 Administrator's Guide for Oracle Access Management
Figure 17–12 Global Load Balancer Front Ends Local Load Balancer
17.5 Understanding Time Outs and Session Syncs
The following sections contain information on how the Multi-Data Center deals with
session time outs and syncs.
■Ensuring Maximum Session Constraints
■Configuring Policies for Idle Timeout
■Expiring Multi-Data Center Sessions
■Synchronizing Sessions and Multi-Data Center Fail Over
17.5.1 Ensuring Maximum Session Constraints
Credential Collector user affinity ensures that maximum session constraints per user
are honored. There is no Multi-Data Center session store to validate allowed
maximum sessions per user.
17.5.2 Configuring Policies for Idle Timeout
The OAM_ID and OAM_GITO cookies are used to calculate and enforce idle
(inactivity) timeouts. The OAM_GITO cookie, though, can be set only if there is a
common sub-domain across WebGates. Thus, Multi-Data Center policies should be
configured based on whether or not the OAM_GITO cookie is set. Table 17–1
documents the policy configurations.
Understanding Time Outs and Session Syncs
Understanding Multi-Data Centers 17-19
17.5.3 Expiring Multi-Data Center Sessions
Session expiration will be managed by the Data Center with which the user has
affinity. Users have affinity to a particular Data Center based on the global trffic
manager/load balancer.
17.5.4 Synchronizing Sessions and Multi-Data Center Fail Over
Access Manager server side sessions are created and maintained based on single
sign-on (SSO) credentials. The attributes stored in the session include (but are not
limited to) the user identifier, an identity store reference, subject, custom attributes,
partner data, client IP address and authentication level. SSO will be granted if the
server can locate a valid session corresponding to the user's request.
In a Multi-Data Center scenario, when a user request hops across Data Centers, the
Data Center servicing the request should validate for a legitimate session locally and
across Data Centers. If a valid session for a given request exists in a remote Data
Center, the remote session needs to be migrated to the current Data Center based on
the MDC session synchronization policies. (See Section 17.2, "Understanding
Multi-Data Center Deployments" for details.) During this session synchronization, all
session attributes from the remote session are synced to the newly created session in
the Data Center servicing the current request.
The Multi-Data Center also supports WebGate failover across Data Centers. When a
WebGate fails over from one Data Center to a second, the session data can not be
synchronized because the first Data Center servers are down. Thus, the second Data
Center will decide whether or not to proceed with the session adoption based on the
setting configured for
SessionContinuationOnSyncFailure
. When true, even if the
OAP communication to the remote Data Center fails, the Data Center servicing the
current request can proceed to create a new session locally based on the mandatory
attributes available in the cookie. This provides seamless access to the requested
resource despite the synchronization failure. Table 17–2 summarizes prominent session
Table 17–1 Multi-Data Center Policy Configurations for Idle Timeout
OAM_GITO Set Multi-Data Center Policies
Yes
Idle timeout will be
calculated from the latest
OAM_GITO cookie
SessionMustBeAnchoredToDataCenterServicingUser=<true/false>
SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_retry_attempts=<number>
SessionDataRetrievalOnDemandMax_conn_wait_
time=<milliseconds>
SessionContinuationOnSyncFailure=<true/false>
MDCGitoCookieDomain=<sub domain>
No
Idle time out will be
calculated from the
OAM_ID cookie because
OAM_GITO is not
available
SessionMustBeAnchoredToDataCenterServicingUser=false
SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_retry_attempts=<number>
SessionDataRetrievalOnDemandMax_conn_wait_
time=<milliseconds>
SessionContinuationOnSyncFailure=<true/false>
#MDCGitoCookieDomain= This setting should be commented or
removed
Understanding Time Outs and Session Syncs
17-20 Administrator's Guide for Oracle Access Management
synchronization and failover scenarios. The parameters in this table are explained in
greater detail in Section 18–3, " partnerInfo.properties Properties."
Table 17–2 Session Synchronization and Failover Scenarios
MDC
Deployment MDC Policy
Validate
Remote
Session
Session
Synchronized
in DC
Servicing
User From
Remote DC
Terminate
Remote
Session User Challenged
Active-Active SessionMustBeAnchoredToDataCen
terServicingUser=true
SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=<number>
SessionDataRetrievalOnDemandMa
x_conn_wait_time=<milliseconds>
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=<sub
domain>
Yes Yes Yes When a valid
session could not
be located in a
remote DC
Understanding Time Outs and Session Syncs
Understanding Multi-Data Centers 17-21
Active-Active SessionMustBeAnchoredToDataCen
terServicingUser=false
SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=<number>
SessionDataRetrievalOnDemandMa
x_conn_wait_time=<millisecon
ds>
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=<sub
domain>
Yes Yes No When a valid
session could not
be located in a
remote DC
Active-Standby SessionMustBeAnchoredToDataCen
terServicingUser=true
SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=<number>
SessionDataRetrievalOnDemandMa
x_conn_wait_time=<millisecon
ds>
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=<sub
domain>
Could
not
validate
as the
remote
DC is
down
No, since the
remote DC is
down
Could not
terminate
as the
remote
DC is
down
Yes
Active-Standby SessionMustBeAnchoredToDataCen
terServicingUser=true
SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=<number>
SessionDataRetrievalOnDemandMa
x_conn_wait_time=<milliseconds>
SessionContinuationOnSyncFailure
= true
MDCGitoCookieDomain=<sub
domain>
Could
not
validate
as the
remote
DC is
down
No, since the
remote DC is
down
Could not
terminate
as the
remote
DC is
down
No
Provides seamless
access by creating
a local session
from the details
available in the
valid cookie
Table 17–2 (Cont.) Session Synchronization and Failover Scenarios
MDC
Deployment MDC Policy
Validate
Remote
Session
Session
Synchronized
in DC
Servicing
User From
Remote DC
Terminate
Remote
Session User Challenged
Replicating a Multi-Data Center Environment
17-22 Administrator's Guide for Oracle Access Management
17.6 Replicating a Multi-Data Center Environment
Data in the Multi-Data Center environment must be replicated from the Master
(supplier) to the Clones (consumers) as part of the initial setup procedure. Following
this initial replication, the data must be synced across data centers on a regular basis.
The following sections have more details.
■Replicating Data Using the WLST
■Syncing Data Using Automated Policy Synchronization
The following artifacts must be replicated and synced regularly.
■WebGate Profiles
While the WebGate profile is replicated to the Clone, the primary server list and
logout URL details are updated with information about the Clone data center.
■Authentication Modules
■OAM Proxy Configurations
■Session Manager configurations
■Policy and partner data
For more details on replication and syncing data, see Chapter 19, "Synchronizing Data
In A Multi-Data Center."
17.6.1 Replicating Data Using the WLST
Initial replication of data (when setting up the Multi-Data Center) must be done
manually using the WLST. Following this initial replication, WLST commands or the
Automated Policy Sync Replication Service (discussed in Syncing Data Using
Automated Policy Synchronization) can be used to sync the already replicated data.
When using the WLST, partner profiles and policies are exported from the Master Data
Center and then imported to the Clone Data Center. Replication of data in a
Multi-Data Center environment is a requirement and using WLST for this purpose is
the minimum method for accomplishing this. For more details, see Section 19.1.3,
"Manually Syncing Data in a Multi-Data Center."
17.6.2 Syncing Data Using Automated Policy Synchronization
Automated Policy Synchronization (APS, also referred to as the Replication Service) is
a set of REST API used to automatically replicate data from the Master Data Center to
Clone Data Centers. It can be configured to keep Access Manager data synchronized
across multiple data centers. A valid replication agreement between the data centers
must be present before APS can run. For more details, see Section 19.1,
"Understanding the Multi-Data Center Sync."
17.7 Multi-Data Center Recommendations
This section contains recommendations regarding the Multi-Data Center functionality.
■Using a Common Domain
Note: APS is not used to do a complete replication from scratch. You
will first need to replicate data manually using the WLST to establish
a base line. APS is only designed to keep data centers in sync.
Multi-Data Center Recommendations
Understanding Multi-Data Centers 17-23
■Concerning the DCC and the OAM_GITO
■Using an External Load Balancer
■Honoring Maximum Sessions
■WebGate Cookie Cannot Be Refreshed During Authorization
17.7.1 Using a Common Domain
It is recommended that WebGates be domain-scoped in a manner that a common
domain can be inferred across all WebGates and the OAM Server Credential
Collectors. This allows for WebGates to set an encrypted GITO cookie to be shared
with the OAM Server. For example, if WebGates are configured on
applications.abc.com and the OAM Server Credential Collectors on server.abc.com,
abc.com is the common domain used to set the GITO cookie. In scenarios where a
common domain cannot be inferred, setting the GITO cookie is not practical as a given
Data Center may not be aware of the latest user sessions in another Data Center. This
would result in the Data Center computing session idle-timeout based on old session
data and could result in re-authenticating the user even though a more active session
lives elsewhere.
When there is no common cookie domain across WebGates and OAM servers, make
the following configuration changes to address idle time out issues.
■Run the
enableMultiDataCentreMode
WLST command after removing the
MDCGitoCookieDomain property from the input properties file.
■Because a WebGate cookie cannot be refreshed during authorization, set the value
of the WebGate cookie validity lower than the value of the session idle time out
property. Consider a session idle time out value of 30 minutes and a WebGate
cookie validity value of 15 minutes; in this case, every 15 minutes the session will
be refreshed in the authenticating Data Center.
17.7.2 Concerning the DCC and the OAM_GITO
The OAM_GITO cookie is not applicable when using the DCC. Because of this:
■The #MDCGitoCookieDomain= setting should be commented out.
■The SessionMustBeAnchoredToDataCenterServicingUser parameter must be set to
false.
■The WebGate cookie expiration interval should be set as documented in "Using a
Common Domain."
Note: A similar issue occurs during server fail-over when the
SessionContinuationOnSyncFailure
property is set. The expectation
is to retrieve the session from contents of the OAM_ID cookie. Since
it's not possible to retrieve the actual inactivity time out value from the
GITO cookie, a re-authentication could result.
Note: For 10G WebGates, since the token is not expired by the
WebGate, the server will continue to honor a 10G WebGate cookie
until the session in the base DC (authenticating DC) idles out.
Multi-Data Center Recommendations
17-24 Administrator's Guide for Oracle Access Management
17.7.3 Using an External Load Balancer
Access Manager uses the 11g SDK API to retrieve session data but this API does not
support SDK based load-balancing across the configured set of primary servers. Use
an external TCP based load balancer to front-end the OAP endpoints of the Data
Center nodes where high performance is expected.
17.7.4 Honoring Maximum Sessions
A typical Multi-Data Center scenario authenticates users against the Data Center with
which the user geography has an affinity. In the rare scenarios where user
authentication and session creation for a given user spans across member Data Centers
(bypassing geographic affinity and load spike), the maximum sessions the user has in
the whole Multi-Data Center topology would not be honored.
17.7.5 WebGate Cookie Cannot Be Refreshed During Authorization
Because a WebGate cookie cannot be refreshed during authorization, set the value of
the WebGate cookie validity lower than the value of the session idle time out property.
Consider a session idle time out value of 30 minutes and a WebGate cookie validity
value of 15 minutes; in this case, every 15 minutes the session will be refreshed in the
authenticating Data Center. Setting the WebGate cookie expiration to less than 2
minutes is the recommendation.
Note: Failover between primary and secondary OAM servers is
supported in the current release of 11g SDK APIs.
Note: This will not work for 10G WebGates because the 10G
WebGate token expiration is driven by the server and not the
WebGate. The server will continue to honor a 10G WebGate cookie
until the session in the base DC (authenticating DC) idles out. A
logout will work by clearing browser cookies; the dangling server side
session will continue to exist but is considered harmless.
18
Configuring Multi-Data Centers 18-1
18
Configuring Multi-Data Centers
[16]
The Multi-Data Center feature is disabled by default. This chapter contains details on
how to enable and configure the Multi-Data Center functionality.
The following sections have details.
■Before Setting Up a Multi-Data Center
■Understanding the Primary Use Cases
■Setting Up a Multi-Data Center
■Adding A Second Clone to An Existing Multi-Data Center Setup
■Understanding Multi-Data Center Security Modes
■WLST Commands for Multi-Data Centers
18.1 Before Setting Up a Multi-Data Center
The following prerequisites must be satisfied before beginning the Multi-Data Center
(MDC) configuration process documented in Setting Up a Multi-Data Center.
■Ensure you have a fully functioning Oracle Access Management environment with
all applicable WebGates configured.
■Partners (WebGates or agents) are anchored to a single Data Center thus, partner
registration is done at the individual Data Centers.
■All Data Center clusters must be front ended by a single Load Balancer. The load
balancer should send all requests in a user session consistently to the same
backend server (persistence, stickiness) and it should be route traffic
geographically (geo-affinity).
■Clocks on the machines in which Access Manager and agents are deployed must
be in sync. Non-MDC Access Manager clusters require the clocks of WebGate
agents be in sync with Access Manager servers. This requirement applies to the
MDC as well. If the clocks are out of sync, token validations will not be consistent
resulting in deviations from the expected behaviors regarding the token expiry
interval, validity interval, timeouts and the like.
■The identity stores in a Multi-Data Center topology must have the same Name.
■WebLogic Server domains do not span Data Centers.
■Any firewall between Data Centers must allow communication over the Oracle
Access Protocol (OAP) channel. This entails opening the necessary ports and
taking into account the lifetime of the connection. In regards to the latter, the
Understanding the Primary Use Cases
18-2 Administrator's Guide for Oracle Access Management
MaxSessionTime parameter in the WebGate profile should be set to less than the
firewall timeout value.
18.2 Understanding the Primary Use Cases
Table 18–1 lists the primary MDC use cases.
18.3 Setting Up a Multi-Data Center
The MDC feature is disabled by default. To set up an Access Manager MDC, start with
an Access Manager cluster, set all MDC global configurations and designate the cluster
as the Master Data Center. Following this, set up the Clone Data Center.
The following sections document the process for setting up an MDC. They include
running the commands documented in Section 18.6, "WLST Commands for Multi-Data
Centers."
Table 18–1 MDC Use Cases
MDC
Deployment MDC Policy
Validate
Remote
Session
Session
Synchroni
zed in DC
Servicing
User From
Remote
DC
Terminate
Remote
Session
User
Challenged
Active-Active SessionMustBeAnchoredToDataCenterServ
icingUser=false
SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_
retry_attempts=<number>
SessionDataRetrievalOnDemandMax_
conn_wait_time=<milliseconds>
SessionContinuationOnSyncFailure= false
MDCGitoCookieDomain=<sub domain>
Yes Yes No When a valid
session could
not be
located in a
remote DC
Active-Standb
y
SessionMustBeAnchoredToDataCenterServ
icingUser=false
SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_
retry_attempts=<number>
SessionDataRetrievalOnDemandMax_
conn_wait_time=<milliseconds>
SessionContinuationOnSyncFailure= true
MDCGitoCookieDomain=<sub domain>
Could not
validate
as the
remote
DC is
down
No, since
the remote
DC is down
Could not
terminate
as the
remote DC
is down
No
Provides
seamless
access by
creating a
local session
from the
details
available in
the valid
cookie
Note: Before beginning this procedure, ensure that you have
completed the points documented in "Before Setting Up a Multi-Data
Center."
Setting Up a Multi-Data Center
Configuring Multi-Data Centers 18-3
■Enabling the Master Data Center
■Setting Up the Clone Data Center
18.3.1 Enabling the Master Data Center
The following procedure contains more details.
1. Set up the primary Access Manager Data Center and designate it as the Master.
A Master Data Center can be an existing Access Manager cluster or a vanilla
installation.
a. Make note of the clusterId.
The Access Manager bootstrap assigns a unique
clusterId
to the Access
Manager cluster. To set a custom clusterId, use the
setMultiDataCentreClusterName
WLST command documented in
Section 18.6.7, "setMultiDataCentreClusterName."
b. Enable Multi-Data Center mode by running the
enableMultiDataCentreMode
WLST command.
enableMultiDataCentreMode
sets an Access Manager cluster as Master, by
default, and applies the global configurations. See Section 18.6.1,
"enableMultiDataCentreMode" for details on the command and a sample
properties file used for input. See Understanding the Primary Use Cases for
details on the primary MDC scenarios.
c. Validate the MDC configuration by running the
validateMDCConfig
WLST
command.
See Section 18.6.8, "validateMDCConfig."
d. Restart the Admin server.
2. Register and seed Partner Profiles for the Multi Data Centers.
Each Data Center will use an Oracle Access Protocol (OAP) channel to fetch
sessions from a remote DC. This runtime session sync can be initiated by a Master
or Clone and thus each Data Center requires a WebGate agent profile (created
using the Oracle Access Management Console) to be registered as a Partner Profile
in the cluster.
This procedure will register two profiles, DCMaster and DCClone1. These profiles
are used for the back channel OAP communication mentioned above. A WebGate
profile should also be defined for the Master and all Clone Data Centers.
a. Log in to the Oracle Access Management Console as System Administrator
and click Application Security at the top of the window.
Note: To explicitly set the DC type as Master or Clone, use the
setMultiDataCenterType
WLST command documented in
Section 18.6.5, "setMultiDataCenterType."
Note: These registrations can be performed in the Master DC and the
configurations will be applied to all clones created using T2P process.
Setting Up a Multi-Data Center
18-4 Administrator's Guide for Oracle Access Management
b. In the Application Security console, click SSO Agent Registration in the
Quick Start Wizards section.
The SSO Agent Registration tab opens.
c. Configure the DCMaster agent profile by entering the required details
including Version, Name (DCMaster) and Security Mode.
The security mode of the MDC partner profile should match the security mode
defined for the Access Manager server. See Understanding Multi-Data Center
Security Modes for details on the property files for each security mode. These
files will be used as input when the
addPartnerForMultiDataCentre
WLST
command is executed below.
d. Uncheck Auto Create Policies and click Finish.
A DCMaster tab is displayed. Ensure that the Allow Management Operation
option is selected in the newly created agent profile.
e. Repeat the steps to create the DCClone1 agent profile.
f. Execute the
addPartnerForMultiDataCentre
WLST command to seed the
DCMaster and DCClone1 agent profiles to the Master Data Center.
The WLST command would be run twice on the Master Data Center as
follows:
addPartnerForMultiDataCentre(propfile= "/path/DCMaster.properties")
addPartnerForMultiDataCentre(propfile= "/path/DCClone1.properties"
Example 18–1 and Example 18–2 illustrate the property files used as input.
The
RESTEndpoint
property takes a value of the HTTP or HTTPS endpoint of
the Access Manager AdminServer used to invoke replication related REST
services. HTTPS is preferred.
Example 18–1 DCMaster.properties for Master
remoteDataCentreClusterId=DC1
#webgate profile for session fetch created earlier and its password in DC1
oamMdcAgentId=DCMaster
AccessClientPasswd=secret
PrimaryHostPort=dc1.us.example.com:5575
SecondaryHostPort=dc1.example.com:5576
oamMdcSecurityMode=OPEN
trustStorePath=NA
keyStorePath=NA
globalPassPhrase=NA
keystorePassword=NA
agentVersion=11g
RESTEndpoint=https://<DCMaster Admin Server>:<port>
Example 18–2 DCClone1.properties for Clone
remoteDataCentreClusterId=DC2
#webgate profile for session fetch created earlier and its password in DC2
oamMdcAgentId=DCClone1
AccessClientPasswd=secret
PrimaryHostPort=dc2.us.example.com:5575
Setting Up a Multi-Data Center
Configuring Multi-Data Centers 18-5
SecondaryHostPort=dc2.example.com:5576
oamMdcSecurityMode=OPEN
trustStorePath=NA
keyStorePath=NA
globalPassPhrase=NA
keystorePassword=NA
agentVersion=11g
RESTEndpoint=https://<DCClone1 Admin Server:port>
After running the WLST commands, the agent profiles will be recognized by
the Master as the profiles to use for runtime session sync. See
addPartnerForMultiDataCentre for more details.
18.3.2 Setting Up the Clone Data Center
The Data Center set up in Enabling the Master Data Center is designated as the Master
and will be cloned using T2P tools for any additional Data Centers. All configuration
and policy changes are propagated from the Master to a Clone using the WLST
commands provided as part of T2P Tooling. The T2P process is explained in the
following documents.
■See Oracle Fusion Middleware Administrator's Guide for information on T2P when
using WebLogic Server.
■See Oracle Fusion Middleware Third-Party Application Server Guide for Oracle Identity
and Access Management for information on T2P when using Websphere Server.
1. Execute the following commands on the Master Data Center.
Ensure that the AdminServer and all Managed Servers are running. The $T2P_
HOME directory is just a location where all the artifacts of this process are saved.
$MIDDLEWARE_HOME/oracle_common/bin/copyBinary.sh -javaHome $JAVA_HOME
-archiveLoc $T2P_HOME/oamt2pbin.jar
-sourceMWHomeLoc $MIDDLEWARE_HOME
-idw true
-ipl $MIDDLEWARE_HOME/oracle_common/oraInst.loc
-silent true
-ldl $T2P_HOME/oam_cln_log;
$MIDDLEWARE_HOME/oracle_common/bin/copyConfig.sh -javaHome $JAVA_HOME
-archiveLoc $T2P_HOME/oamt2pConfig.jar
-sourceDomainLoc $DOMAIN_HOME
-sourceMWHomeLoc $MIDDLEWARE_HOME
-domainHostName admin-dc1.us.example.com
-domainPortNum 7001
-domainAdminUserName weblogic
-domainAdminPassword $T2P_HOME/t2p_domain_pass.txt
-silent true
-ldl $T2P_HOME/oam_cln_log_config
Note: At this point in the procedure, the clone DC has not been
setup but it is assumed that the service host and port information are
known so can be defined in the
DCClone1.properties
file. If the
information is not known, you can register the clone DC partner after
the T2P process. In this case, only DCMaster will be registered now so
the WLST command for the second DC has to be executed first in the
Master DC and then in the clone DC after the T2P process is
completed.
Setting Up a Multi-Data Center
18-6 Administrator's Guide for Oracle Access Management
-opssDataExport true
-debug true;
2. Copy the following files to the clone machine.
The clone machine should not have any Oracle Access Management software
installed on it.
$MIDDLEWARE_HOME/oracle_common/bin/pasteBinary.sh
$MIDDLEWARE_HOME/oracle_common/jlib/cloningclient.jar
$MIDDLEWARE_HOME/oracle_common/oraInst.loc
3. Execute the following commands on the Clone Data Center to copy all contents of
$T2P_HOME directory from the master to the $T2P_HOME directory of the clone.
$T2P_HOME/pasteBinary.sh -javaHome $JAVA_HOME -al $T2P_HOME/oamt2pbin.jar
-tmw $MIDDLEWARE_HOME -silent true -idw true -esp false
-ipl $T2P_HOME/oraInst.loc -ldl $T2P_HOME/oam_cln_log_p
-silent true
$MIDDLEWARE_HOME/oracle_common/bin/extractMovePlan.sh -javaHome $JAVA_HOME
-al $T2P_HOME/oamt2pConfig.jar
-planDirLoc $T2P_HOME/moveplan/
4. Edit the extracted Moveplan.xml on the Clone Data Center to provide relevant
details.
Each Clone Data Center will use a fresh set of OAM related schemas which need
to be created using RCU in their respective databases. The new schema names and
passwords need to be referenced in the moveplan.
$MIDDLEWARE_HOME/oracle_common/bin/pasteConfig.sh -javaHome $JAVA_HOME
-archiveLoc $T2P_HOME/oamt2pConfig.jar
-targetMWHomeLoc $MIDDLEWARE_HOME
-targetDomainLoc $DOMAIN_HOME
-movePlanLoc $T2P_HOME/moveplan/moveplan.xml
-domainAdminPasswordFile $T2P_HOME/t2p_domain_pass.txt
-ldl $T2P_HOME/oam_cln_log_paste_p
-silent true
5. Use pack and unpack to copy managed servers on separate hosts.
See Oracle Fusion Middleware Creating Templates and Domains Using the Pack and
Unpack Commands for details.
6. Configure any or all Clone Data Centers as follows.
a. Set a unique data center identifier for the clone DC using the
setMultiDataCentreClusterName
WLST command.
setMultiDataCentreClusterName(clusterName="DC2")
Note: Backup the original Moveplan.xml before editing.
cp $T2P_HOME/moveplan/moveplan.xml $T2P_
HOME/moveplan/moveplan.xml.org
Note: This step may be skipped if it was already done through the
T2P process.
Understanding Multi-Data Center Security Modes
Configuring Multi-Data Centers 18-7
b. Set the type to Clone for the Clone DC.
setMultiDataCenterType(DataCenterType="Clone")
Optionally the configuration and policy updates can be disabled on the Clone
by executing
setMultiDataCenterWrite(WriteEnabledFlag="false")
. After
executing the command, the Clone becomes read only for policy and
configuration artifacts. See setMultiDataCenterWrite for details.
7. Verify access to the Oracle Access Management Console and single sign-on
between data centers.
To this point, one master and one clone are set up. Multiple clones can be set up
similarly as required by repeating the cloning process. The above commands need to
be executed for each of the clone DCs as per the topology using the appropriate cluster
name each time.
18.4 Adding A Second Clone to An Existing Multi-Data Center Setup
To add another clone to an already existing MDC environment follow these steps. The
specifics are documented in "Setting Up a Multi-Data Center."
1. Register a Partner Profile for the new Clone DC (DC3) on the Master DC.
2. Seed the data center partner on the Master DC.
3. Setup the new Clone DC.
4. Setup replication for the new Clone DC.
5. Customize with transformation rules if required.
18.5 Understanding Multi-Data Center Security Modes
A Multi-Data Center relies on the Oracle Access Protocol (OAP) channel for inter data
center session management operations and back channel communication. The security
mode of the MDC partner profile should match the security mode defined for the
Access Manager server: OPEN, SIMPLE or CERT.
The following sections have details about the security modes.
■OPEN Security Mode
■SIMPLE Security Mode
■CERT Security Mode
Note: An MDC partner profile is exposed by each data center and
used by other data centers to communicate with it. Registering an
MDC partner is a two step process. Consider an MDC with three data
centers. In DC1, expose an MDC partner profile by creating a 10g or
11g WebGate (DC1_MDC_Partner). Then, register DC1_MDC_Partner
in DC2 and DC3 using addPartnerForMultiDataCentre. See
Section 18.6.3, "addPartnerForMultiDataCentre" for details.
Understanding Multi-Data Center Security Modes
18-8 Administrator's Guide for Oracle Access Management
18.5.1 OPEN Security Mode
This is the default mode of the Access Manager deployment. No configuration is
needed. The following is a sample input properties file for use with the
addPartnerForMultiDataCentre
WLST command.
remoteDataCentreClusterId=
<CLUSTER ID OF REMOTE DC FOR WHICH THE AGENT IS BEING ADDED>
oamMdcAgentId=
<AGENT ID OF THE REGISTERED PARTNER IN datacenter ABOVE>
PrimaryHostPort=<fully-qualified-host-name:OAM-port>
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=<fully-qualified-host-name:OAM-port>
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=<ACCESS CLIENT PASSWORD OF oamMdcAgentId IN datacenter>
oamMdcSecurityMode=OPEN
agentVersion=<WEBGATE AGENT VERSION 10g or 11g>
#NA ----> Not Applicable
trustStorePath=NA
keyStorePath=NA
globalPassPhrase=NA
keystorePassword=NA
18.5.2 SIMPLE Security Mode
Follow the instructions in Appendix C.5, "Configuring Simple Mode Communication
with Access Manager" to set up the Access Manager servers in SIMPLE mode. In short,
create an MDC partner profile in each of the member data centers in SIMPLE mode,
and add it to each of the other data centers. The following is a sample input properties
file for use with the
addPartnerForMultiDataCentre
WLST command.
remoteDataCentreClusterId=
<CLUSTER ID OF REMOTE DC FOR WHICH THE AGENT IS BEING ADDED>
oamMdcAgentId=<AGENT ID OF THE REGISTERED PARTNER IN datacenter ABOVE>
PrimaryHostPort=<fully-qualified-host-name:OAM-port>
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=<fully-qualified-host-name:OAM-port>
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=<ACCESS CLIENT PASSWORD OF oamMdcAgentId IN datacenter>
oamMdcSecurityMode=SIMPLE
agentVersion=<WEBGATE AGENT VERSION 10g or 11g>
#Copy the oamclient-truststore.jks & oamclient-keystore.jks from
#<DOMAIN_HOME>/output/webgate-ssl/ from 'datacenter with cluster ID
#remoteDataCentreClusterId' above into the local DC say /scratch/MDCArtifacts/ and
#refer them in the below parameters
trustStorePath=</scratch/MDCArtifacts/oamclient-truststore.jks>
keyStorePath=</scratch/MDCArtifacts/oamclient-keystore.jks>
#Use the online WLST command displaySimpleModeGlobalPassphrase() to list
#the global passphrase in SIMPLE mode. Admins can also update this in the UI
#@ System Configuration-->Access Manager-->Access Manager Settings-->
#Access Protocol-->Simple Mode Configuration-->Global Passphrase.
#globalPassPhrase & keystorePassword are the same for SIMPLE mode
globalPassPhrase=<passphrase resulted in using the above steps>
keystorePassword=<same as globalPassPhrase>
Understanding Multi-Data Center Security Modes
Configuring Multi-Data Centers 18-9
18.5.3 CERT Security Mode
Follow the instructions in Appendix C.4, "Configuring Cert Mode Communication for
Access Manager" to set up the Access Manager servers in CERT mode. In short, create
an MDC partner in each of the member data centers in CERT mode, and generate the
'clientTrustStore.jks' and 'clientKeyStore.jks' keystores to be used by the MDC partner
using the following procedure.
1. Run the following openssl command from a Linux command prompt to generate
aaa_key.pem & aaa_req.pem.
openssl req -new -keyout aaa_key.pem -out aaa_req.pem -utf8
Use the certreq command to generate the certificate and chain.
2. Create aaa_cert.pem using the following procedure.
a. Open aaa_req.pem in a text editor and copy the contents.
Exclude the trailing spaces from your selection.
b. Paste the copied text into Signcsr.
Include [-----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE
REQUEST-----].
c. Copy the output into a text editor and save it as aaa_cert.pem.
3. Create aaa_chain using the following procedure.
a. Open certreq.
b. Click on chain.pem and copy/paste the contents into a text editor and save it
as aaa_chain.pem.
Excluding traiing and leading spaces from your selection.
4. Encrypt the private key (aaa_key.pem) using the following command.
openssl rsa -in aaa_key.pem -passin pass: -out aaa_key.pem -passout
pass:Welcome1 -des
The password used in this command must be defined as the access client
password or agent key password while registering the MDC partner.
5. Copy aaa_key.pem, aaa_cert.pem and aaa_chain.pem to a temporary location.
For example, /tmp/clientCertArtifacts/
6. Convert aaa_cert.pem and aaa_key.pem into DER format using one of the
following commands.
-openssl x509 -in /tmp/clientCertArtifatcs/aaa_cert.pem -inform PEM -out
/tmp/clientCertArtifatcs/aaa_cert.der -outform DER;
-openssl pkcs8 -topk8 -nocrypt -in /tmp/clientCertArtifatcs/aaa_key.pem
-inform PEM -out /tmp/clientCertArtifatcs/aaa_key.der -outform DER;
7. Import the aaa_key.der and aaa_cert.der into clientKeyStore.jks; and the aaa_
chain.pem into clientTrustStore.jks with the below steps
-cd $IDM_HOME/oam/server/tools/importcert/;
-unzip importcert.zip;
-java -cp importcert.jar
oracle.security.am.common.tools.importcerts.CertificateImport -keystore
WLST Commands for Multi-Data Centers
18-10 Administrator's Guide for Oracle Access Management
/tmp/clientCertArtifatcs/clientKeyStore.jks -privatekeyfile
/tmp/clientCertArtifatcs/aaa_key.der -signedcertfile
/tmp/clientCertArtifatcs/aaa_cert.der -storetype jks -genkeystore yes
-keytool -importcert -file /tmp/clientCertArtifatcs/aaa_chain.pem -trustcacerts
-keystore /tmp/clientCertArtifatcs/clientTrustStore.jks -storetype JKS
Enter the keystore passwords when prompted. The password needs to be defined
in the input properties file for the addPartnerForMultiDataCentre WLST
command as well.
8. If not done when creating the certificates for the WebGate, import the aaa_key.der
and aaa_cert.der formatted certificates into the .oamkeystore using the same
Oracle provided importcert.jar used inthe previous step.
-java -cp importcert.jar
oracle.security.am.common.tools.importcerts.CertificateImport
-keystore /scratch/Oracle/Middleware/domains/
base_domain/config/fmwconfig/.oamkeystore -privatekeyfile
/tmp/clientCertArtifacts/aaa_key.der -signedcertfile
/tmp/clientCertArtifacts/aaa_cert.der -alias mycertmode1 -storetype JCEKS
alias is the alias name defined when setting CERT mode in Access Manager.
The following is a sample input properties file for use with the
addPartnerForMultiDataCentre WLST command.
remoteDataCentreClusterId=
<CLUSTER ID OF REMOTE DC FOR WHICH THE AGENT IS BEING ADDED>
oamMdcAgentId=<AGENT ID OF THE REGISTERED PARTNER IN datacenter ABOVE>
PrimaryHostPort=<fully-qualified-host-name:OAM-port>
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=<fully-qualified-host-name:OAM-port>
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=<ACCESS CLIENT PASSWORD OF oamMdcAgentId IN datacenter>
oamMdcSecurityMode=CERT
agentVersion=<WEBGATE AGENT VERSION 10g or 11g>
trustStorePath=</tmp/clientCertArtifatcs/clientTrustStore.jks >
keyStorePath=</tmp/clientCertArtifatcs/clientKeyStore.jks >
globalPassPhrase=NA
#use keystore password used for generating keystore in the previous step
keystorePassword=<keystore password given while generating keystore>
18.6 WLST Commands for Multi-Data Centers
The following WebLogic Scripting Tool (WLST) commands are specific to Multi-Data
Center deployment. More information is in the following sections.
■enableMultiDataCentreMode
■disableMultiDataCentreMode
■addPartnerForMultiDataCentre
■removePartnerForMultiDataCentre
■setMultiDataCenterType
■setMultiDataCenterWrite
WLST Commands for Multi-Data Centers
Configuring Multi-Data Centers 18-11
■setMultiDataCentreClusterName
■validateMDCConfig
■exportAccessStore
■importAccessStore
See the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for
information on the WebLogic Scripting Tool.
18.6.1 enableMultiDataCentreMode
Online command used to enable Multi-Data Center mode.
18.6.1.1 Description
This command enables Multi-Data Center mode. It takes a value equal to the full path
to, and name of, the MDC.properties file.
18.6.1.2 Syntax
enableMultiDataCentreMode(propfile="../MDC_properties/oamMDCProperty.properties")
Note: Setting the SSO Token version to 5 is not supported from the
administration console. To do this, modify the Access Manager
Settings page and run the
enableMultiDataCentreMode
WLST
command to set.
Argument Definition
propfile
Mandatory. Takes a value equal to the full path to, and name of, the
oamMDCProperty.properties
file. Table 18–2 documents the
properties that comprise
the file.
Example 18–3 (following the
table) is a sample oamMDCProperty.properties file.
Table 18–2 oamMDC.properties Properties
Property Definition
SessionMustBeAnchoredToDataCenterServicing
User
Takes a value of True (Invalidate) or False
(No Invalidation).
SessionDataRetrievalOnDemand Takes a value of True (Cross DC retrieval) or
False (No). Data retrieval can be turned off
without disabling MDC. If False, session data
is not transferred but SSO is still performed
as the user moves across DCs.
NOTE: SessionDataRetrievalOnDemand
must be set to False when deploying in
Co-existence mode. See Oracle Fusion
Middleware Migration Guide for Oracle Identity
and Access Management for information on
co-existence scenarios.
Reauthenticate Takes a value of True (force reauthentication)
or False (No forced reauthentication).
SessionDataRetrievalOnDemandMax_retry_
attempts
Takes a value equal to a binary that
represents the number of times to retry data
retrieval when it fails. Default is 2.
WLST Commands for Multi-Data Centers
18-12 Administrator's Guide for Oracle Access Management
Example 18–3 Sample oamMDCProperty.properties File
SessionMustBeAnchoredToDataCenterServicingUser=false
SessionDataRetrievalOnDemand=true
Reauthenticate=true
SessionDataRetrievalOnDemandMax_retry_attempts=3
SessionDataRetrievalOnDemandMax_conn_wait_time=80
SessionContinuationOnSyncFailure=true
#MDCGitoCookieDomain=.example.com <This setting should be provided only if there
is a common cookie subdomain across the WGs and DCs>
18.6.1.3 Example
The following command enables this data center.
enableMultiDataCentreMode(propfile="../MDC_properties/oamMDCProperty.properties")
18.6.2 disableMultiDataCentreMode
Online command used to disable Multi-Data Center mode.
18.6.2.1 Description
This command disables Multi-Data Center mode.
18.6.2.2 Syntax
disableMultiDataCentreMode()
There are no arguments for this command.
18.6.2.3 Example
The following command disables Multi-Data Center mode.
SessionDataRetrievalOnDemandMax_conn_
wait_time
Takes a value equal to a binary that
represents the total amount of time in
seconds to wait for a connection. Default is
1000.
SessionContinuationOnSyncFailure Decides the session adoption action on fail
over. When set to 'true', the session will
continue on the DC servicing the current
request even though the parent DC is
down/not reachable. The session will be
created in the DC servicing the current
request from the mandatory minimal
information available in the incoming token.
When set to 'false', the user will be
challenged on fail-over scenarios.
MDCGitoCookieDomain Specifies the domain with which the OAM_
GITO cookie should be set. In MDC
deployments where a common cookie
domain hierarchy cannot be derived, this
setting should be commented or removed as
described in Inactivity time outs scenario.
Table 18–2 (Cont.) oamMDC.properties Properties
Property Definition
WLST Commands for Multi-Data Centers
Configuring Multi-Data Centers 18-13
disableMultiDataCentreMode()
18.6.3 addPartnerForMultiDataCentre
In an MDC deployment with
n
number of Data Centers, each Data Center has a
registered partner to communicate with each of the other (n-1) Data Centers. This
makes the total number of partner registrations (n) x (n-1). This online command is
used to add a partner for inter Data Center OAP communication.
18.6.3.1 Description
This command adds a partner to the Data Center. It takes a value equal to the full path
to, and name of, the
partnerInfo.properties
file.
18.6.3.2 Syntax
addPartnerForMultiDataCentre(propfile="../MDC_properties/partnerInfo.properties")
Table 18–3 documents the properties that comprise
partnerInfo.properties
. See
Understanding Multi-Data Center Security Modes for properties file samples.
Note: An MDC partner profile is exposed by each data center and
used by other data centers to communicate with it. Registering an
MDC partner is a two step process. Consider an MDC with three data
centers. In DC1, expose an MDC partner profile by creating a 10g or
11g WebGate (DC1_MDC_Partner). Then, register DC1_MDC_Partner
in DC2 and DC3 using addPartnerForMultiDataCentre. See
Section 18.6.3, "addPartnerForMultiDataCentre" for details.
Argument Definition
propfile
Mandatory. Takes a value equal to the path to, and name of, the
partnerInfo.properties file.
RESTEndpoint
Optional. Takes as a value the HTTP/HTTPS URL from which the
Access Manager REST services can be accessed.
Table 18–3 partnerInfo.properties Properties
Property Definition
remoteDataCentreClusterId Cluster id of the remote Data Center with which the OAP
communication needs to be established.
oamMdcAgentId Partner ID of the registered partner profile in the remote Data
Center. The "allow management operations" flag for this partner
should be set in the remote Data Center.
PrimaryHostPort Takes a fully-qualified-host-name:OAM-port for the primary Access
Manager server corresponding to the remote DC identified by
remoteDataCentreClusterId; for example:
PrimaryHostPort=abc.example.com:5575
WLST Commands for Multi-Data Centers
18-14 Administrator's Guide for Oracle Access Management
18.6.3.3 Example
The following command defines this data center as a Master.
addPartnerForMultiDataCentre(propfile="../MDC_properties/partnerInfo.properties")
18.6.4 removePartnerForMultiDataCentre
Online command used to remove a registered remote partner from the Data Center
configuration.
18.6.4.1 Description
This command removes a registered remote partner from a configured Data Center. It
takes a value equal to a valid remoteDataCentreClusterId.
18.6.4.2 Syntax
removePartnerForMultiDataCentre=("<cluster_ID>")
SecondaryHostPort Takes a fully-qualified-host-name:OAM-port for the secondary
Access Manager server corresponding to the remote DC
identified by remoteDataCentreClusterId; for example:
SecondaryHostPort=abc.example.com:5577
Consider an OAM MDC member Data Center with two
managed servers at abc.example.com with ports as follows:
oam_server1 (5575) and oam_server2 (5577). High
availability/failover of the OAP SDK partner can be achieved by
setting the PrimaryHostPort and SecondaryHostPort as below.
PrimaryHostPort=abc.example.com:5575
SecondaryHostPort=abc.example.com:5577
AccessClientPasswd The access client password of the MDC partner registered in the
remote Data Center.
oamMdcSecurityMode Defines the MDC security mode. Takes a value of
OPEN/SIMPLE/CERT. (CERT Mode is preferred, SIMPLE is
fine but OPEN is discouraged.)
For SIMPLE and CERT modes, the following values should be
supplied appropriately. For OPEN mode, these values are not
applicable. See Understanding Multi-Data Center Security
Modes.
agentVersion Valid agent version 11g/10g.
trustStorePath Absolute path to the truststore file [SIMPE/CERT].
keyStorePath Absolute path to the keyStore file [SIMPLE/CERT].
globalPassPhrase Global passphrase set during the partner registration
[SIMPLE/CERT].
keystorePassword Key store password set during partner configuration
[SIMPLE/CERT].
Argument Definition
cluster_ID
Mandatory. Takes a string value equal to the cluster ID.
Table 18–3 (Cont.) partnerInfo.properties Properties
Property Definition
WLST Commands for Multi-Data Centers
Configuring Multi-Data Centers 18-15
18.6.4.3 Example
The following command defines the partner to be removed.
removePartnerForMultiDataCentre("99bf9-adc2120609")
18.6.5 setMultiDataCenterType
Online command used to set the type of data center - either Master or Clone.
18.6.5.1 Description
In an MDC deployment one Data Center is designated as the Master and the others as
a Clone. Essentially all MDC wide global configurations and policy updates should be
applied to the Master and propagated to the Clones using the supported T2P
commands. This command sets the type of the data center. Values are Master or Clone.
18.6.5.2 Syntax
setMultiDataCenterType(DataCenterType="<Master|Clone>")
18.6.5.3 Example
The following command defines this data center as a Master.
setMultiDataCenterType(DataCenterType="Master")
18.6.6 setMultiDataCenterWrite
Online command used to set write protection for modifications to system and policy
configurations on the Clone Data Center.
18.6.6.1 Description
A Clone Data Center can be write protected by setting
WriteEnabledFlag
to false. In
this case, the Clone Data Center will not allow updates through the Oracle Access
Management Console or WLST commands. Data synchronization will still continue to
update as the command is used to write protect the Clone Data Center against
accidental updates after the initial set up is complete.
18.6.6.2 Syntax
setMultiDataCenterWrite(WriteEnabledFlag="<true|false>")
18.6.6.3 Example
The following example protects the Clone Data Center from accidental overwrites.
setMultiDataCenterWrite(WriteEnabledFlag = "false")
Argument Definition
DataCenterType
Mandatory. Takes a string value of Master or Clone.
Argument Definition
WriteEnabledFlag
Mandatory. Takes a string value of true or false.
WLST Commands for Multi-Data Centers
18-16 Administrator's Guide for Oracle Access Management
18.6.7 setMultiDataCentreClusterName
Online command to set the cluster name of the Data Center to the supplied string.
18.6.7.1 Description
This command sets the Multi-Data Center cluster name. Value is a string.
18.6.7.2 Syntax
setMultiDataCentreClusterName(clusterName="<string_value>")
18.6.7.3 Example
The following command enables this data center.
setMultiDataCentreClusterName(clusterName="MyCluster")
18.6.8 validateMDCConfig
Online command used to insure the Multi-Data Center configuration is correct.
18.6.8.1 Description
This command validates that the required entries in the Multi-Data Center
configuration are present in
oam-config.xml
. For the MDC solution, a new Access
Manager event named
mdc_session_update
is required to create or update MDC
sessions during authorization. The Access Manager event model requires a set of
configurations to be present in the
oam-config.xml
configuration file. The required
configurations cannot be added statically so
validateMDCConfig
validates the required
entries for
mdc_session_update
and seeds any configurations not already present.
18.6.8.2 Syntax
validateMDCConfig()
There are no arguments for this command.
18.6.8.3 Example
The following command validates the MDC configuration.
validateMDCConfig()
18.6.9 exportAccessStore
Online command to create a ZIP file of the Master Data Center UDM metadata.
18.6.9.1 Description
This command will create a ZIP file of the Master Data Center UDM metadata.
18.6.9.2 Syntax
exportAccessStore(toFile="<name and location of ZIP", namePath="/")
Argument Definition
clusterName
Mandatory. Takes a string equal to the cluster name.
WLST Commands for Multi-Data Centers
Configuring Multi-Data Centers 18-17
18.6.9.3 Example
exportAccessStore(toFile="/master/location/dc1metadata.zip", namePath="/")
18.6.10 importAccessStore
Online command to import a ZIP file of the Master Data Center UDM metadata to a
Clone Data Center.
18.6.10.1 Description
This command will import a ZIP file of the Master Data Center UDM metadata to the
Clone Data Center.
18.6.10.2 Syntax
importAccessStore(fromFile="<name and location of ZIP", namePath="/")
18.6.10.3 Example
importAccessStore(fromFile="/master/location/dc1metadata.zip", namePath="/")
WLST Commands for Multi-Data Centers
18-18 Administrator's Guide for Oracle Access Management
19
Synchronizing Data In A Multi-Data Center 19-1
19
Synchronizing Data In A Multi-Data Center
[17]
The Multi-Data Center infrastructure can be configured to keep Access Manager data
synchronized across multiple data centers. This can be done using the Automated
Policy Synchronization Replication Service or data can be replicated manually.
The following sections contain details on the replication procedures.
■Understanding the Multi-Data Center Sync
■Enabling Data Replication
■Syncing Master and Clone Metadata
■Using and Customizing Transformation Rules
■Modifying a Rule Document
■Using REST API for Replication Agreements
■Replicating Domains in Identity Manager Deployments
■Best Practices for Replication
19.1 Understanding the Multi-Data Center Sync
The Multi-Data Center (MDC) infrastructure can be configured to keep Access
Manager data synchronized across multiple data centers. This release introduces
Automated Policy Synchronization (APS), a replication mechanism that removes
administrator and manual intervention from the data synchronization process. Policy,
system configuration and partner metadata are all synchronized with APS.
APS (also referred to as the Replication Service) is a set of REST API. The binaries are
installed as part of the Access Manager application and deployed in the AdminServer.
It is disabled by default but can be enabled by setting the
oracle.oam.EnableMDCReplication
property to true. After enabling the service, create
a pull model Replication Agreement between the Clone data center and the Master.
The Clone polls for changes from the Master as long as the Replication Agreement is
valid for it. Conversely, the Master will respond to the Clone's request as long as it
finds a valid replication agreement. The Clone applies the changes locally
Note: T2P tooling is required for creating a Clone (also referred to as
a Consumer) from a Master (also referred to as a Supplier). Once the
MDC infrastructure is deployed (as documented in Chapter 18,
"Configuring Multi-Data Centers"), APS can be enabled to
automatically sync any changes from the Master to the Clones.
Understanding the Multi-Data Center Sync
19-2 Administrator's Guide for Oracle Access Management
When setting up the Replication Service, the following may occur:
■Establishment of a Replication Agreement with the registration of one data center
as a replication Clone and another in a separate geographical location as its
Master; the changes are pulled from the Master and applied to the Clone.
■Definition of data center specific configurations which may not be replicated
across data centers.
■Tracking of Access Manager configuration changes in each data center and
querying the current replication state in any of the data centers.
■Generation of a changelog which can be applied in the context of a similar setup
running in another data center.
■Trigger of a pull from the Master data center if there is a need; for example, if
automated replication fails.
■Replication of Access Manager configuration artifacts in the Master-Clone model.
The following sections contain additional details.
■How Replication Works
■Understanding the Replication Agreement
■Manually Syncing Data in a Multi-Data Center
19.1.1 How Replication Works
Replication works in a Master-Clone topology. In this topology, multiple Clones pull
changes from a single Master. One Data Center is defined by the administrator as the
Master and one or more other Data Centers are Clones. The administrator makes
changes to the Master that are replicated to the Clones. Only Master to Clone
replication is supported; changes to Clones are not replicated back to the Master.
To partake in replication, the Master data center (initiator of the replication) and the
Clone data center (receiver of the changes) must have a Replication Agreement stored
in the Access Manager data store. Table 19–1 documents the states in which replication
can be deployed.
Note: APS is optional; administrator-initiated import and export
based replication is still available using the T2P tooling and WLST
command procedure used previous to this release.
Note: APS does not sync IDS Profiles, OAM Keystores and Oracle
Platform Security Services artifacts (jps-config.xml changes, credential
store configuration and the like).
Note: Multi-master replication is not supported.
Understanding the Multi-Data Center Sync
Synchronizing Data In A Multi-Data Center 19-3
Figure 19–1 illustrates the replication flow.
Figure 19–1 Replication Flow
Each Clone pulls changes from the Master. A replication thread runs on the Clone after
the pre-configured interval of time and fetches changes from the Replication Service
(REST endpoint) running on the Master environment.
For every cloned environment, the Master keeps track of a change sequence number
indicating when it was last synced. The Master also keeps track of the list of changes
(Create/Update/Delete) that have been pulled by the Clones in a changelog using
specific change sequence numbers. When updating configuration metadata, the Clone
can also change environment specific parameter values depending on transformation
rules. See Using and Customizing Transformation Rules for details.
19.1.2 Understanding the Replication Agreement
Configuration changes (defined as journals) are replicated from a Master node to Clone
nodes. On receiving the journals, each node updates it's configuration to match the
journal and remain in a synchronized state. The nodes, though, need to enter a
Replication Agreement to receive change journals.
When a new data center is added to an existing MDC topology, it has to bootstrap
itself to be in sync with the existing data centers. This bootstrap operation will get the
current Access Manager policies, system configuration, partner metadata and server
keys for the existing MDC topology. After the bootstrap operation, the new data center
Table 19–1 Replication States
State Definition
Active An Access Manager domain (including Admin and managed
servers) is setup to serve access requests. In an active state, the
Access Manager server provides the web access management
functionality without additional MDC features.
Bootstrapping This state is optional for some Data Centers; for example, the
first one in an MDC topology. A Data Center goes through this
intermediate state when added to an existing MDC topology.
The new DC contacts the master and bootstraps itself to the
same state. The bootstrap includes synchronizing the server
keys, policy artifacts, partners, and system configuration. After
completion of bootstrapping, the DC will be Replication Ready.
Replication Ready In this state, MDC is enabled, the DC is made part of the
topology, and the replication service is enabled. Once enabled, a
clone can be registered with the master via a Replication
Agreement. Once established, clone DCs can query and start
pulling changelogs from the master.
Enabling Data Replication
19-4 Administrator's Guide for Oracle Access Management
captures the last change sequence number from the topology's Master so that during
replication it can be used to determine the current state.
To establish a Replication Agreement, the Clone data center must know the Master's
changelog sequence number. If the data center is added to the topology on 'day 0' and
the Replication Agreement was created on 'day 1', there is a need to bootstrap again.
To avoid this and to keep the flow simple, creating a Replication Agreement should
take care of the bootstrap and actual replication agreement creation. The steps to create
the Replication Agreement are documented in Section 18.3, "Setting Up a Multi-Data
Center."
19.1.3 Manually Syncing Data in a Multi-Data Center
Data in an MDC topology can also be synced manually. The manual option uses WLST
export and import calls to migrate the data from one data center to another. Partner
profiles and policies should both be exported and imported using WLST. The WLST
commands are documented in Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference for Identity and Access Management.
19.2 Enabling Data Replication
The following procedures will enable data replication on the Master and Clone Data
Centers.
1. Enable Replication for the Master Data Center using the following procedure.
a. Set the
oracle.oam.EnableMDCReplication
VM property to
true
in the
setDomainEnv.sh/cmd
file on the Master Data Center machine.
-Doracle.oam.EnableMDCReplication=true
b. Stop and start the Access Manager AdminServer.
c. Validate that the REST endpoints are enabled by running the following
command.
curl -u <user> 'https://dc1-admin.example.com:7002/
oam/services/rest/_replication/hello
2. Enable Replication for the Clone Data Center(s) using the following procedure.
a. Set the
oracle.oam.EnableMDCReplication
VM property to
true
in the
setDomainEnv.sh/cmd
file on the Clone Data Center machine.
-Doracle.oam.EnableMDCReplication=true
Figure 19–2 EnableMDCReplication Java Property
Note: Automated bootstrap is the ideal scenario but you can execute
T2P tooling first to ensure the Master and Clones are in the same state.
Syncing Master and Clone Metadata
Synchronizing Data In A Multi-Data Center 19-5
b. Stop and start the Access Manager AdminServer.
c. Validate that the REST endpoints are enabled by running the following
command.
curl -u <user> 'https://dc1-admin.example.com:7002/
oam/services/rest/_replication/hello
d. Repeat this process on all Clone Data Centers.
19.3 Syncing Master and Clone Metadata
The process for syncing metadata across an MDC involves first syncing Access
Manager UDM metadata and then creating a replication agreement (as discussed in
Understanding the Replication Agreement). The procedures are documented in the
following sections.
■Syncing the UDM Metadata
■Creating the Replication Agreement
■Modifying the Replication Agreement
19.3.1 Syncing the UDM Metadata
It is required to sync Access Manager UDM metadata stored in the Master to all
Clones and this step must be executed before creating the replication agreement.
1. Execute the
exportAccessStore
WLST command on the Master Data Center to
create a ZIP file containing the UDM metadata.
exportAccessStore(toFile="/master/location/dc1metadata.zip",
namePath="/")
2. Copy
dc1metadata.zip
to the Clone DC location.
3. Execute the
importAccessStore
WLST command on the Clone Data Center to
import the UDM metadata.
importAccessStore(fromFile="/clone/location/dc1metadata.zip",
namePath="/")
4. Repeat on all Clone DCs.
19.3.2 Creating the Replication Agreement
This is a one time operation which will enable the Clone DCs to pull changes from the
master DC. The replication agreement can be created using any REST client. In this
procedure, we use the standard curl utility. This command will:
■Insert an entry in the Master's Replication Agreement store containing details
regarding the Clone that wants to pull changes.
■Insert an entry in the Clone's Replication Agreement store containing details
regarding the Master from which it will pull changes. Replication configuration
values like the poll interval will also be set.
1. Ensure the Master and Clone DC REST endpoints are up and running.
2. Execute the following command on the Master DC.
Syncing Master and Clone Metadata
19-6 Administrator's Guide for Oracle Access Management
This command will use the
repluser
specified for replication queries from the
Master to the Clone. repluser is expected to be available in the default identity
stores for all involved DCs.
curl -u <repluser> -H 'Content-Type: application/json' -X POST
'https://supplier.example.com:7002/oam/services/rest/
_replication/setup' -d '{"name":"DC12DC2",
"source":"DC1","target":"DC2","documentType":"ENTITY"}'
The following is an example of output for the command.
{"enabled":"true","identifier":"201409231329353668","ok":"true",
"pollInterval":"900","startingSequenceNumber":"110","state"
:"READY"}
Be sure to note the values of the replication identifier, pollInterval and
startingSequence Number. The identifier is a reference specific to this Replication
Agreement and is used for replication related queries. The pollInterval is a value
(in seconds) after which the Clone will poll for changes against the Master.
(Typically policy and configuration are not changed often so this number can be as
high as the default value of 900 seconds.) The startingSequenceNumber is the
value before which all records will be unavailable. In the example, all records
before the value of 110 are unavailable. It is implicit that bootstrapping happened
before creating the Replication Agreement thus the Clone can start pulling
changes from sequence number 110. The Clone also has an entry created in its local
replication table which keeps track of the last sequence number. The starting
sequence process is illustrated in Figure 19–3.
Figure 19–3 Starting Sequence Illustrated
The create replication agreement command will return details of an already
existing replication agreement if applicable. In this case, the value of ok will be
false.
{"enabled":"true","identifier":"201409231329353668","ok":"false",
"pollInterval":"900","startingSequenceNumber":"110",
"state":"READY"}
Syncing Master and Clone Metadata
Synchronizing Data In A Multi-Data Center 19-7
3. Restart the Master and Clone AdminServers.
Once the replication agreement is created and the AdminServers restarted, the
Clone will start polling for changes. The default poll interval is ‘900’ seconds or 15
minutes. The poll interval can be changed by executing an edit replication
agreement command. For example, the following command will change the
polling interval to 60 seconds. Restart the Clone AdminServer after running the
command.
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com:7002/oam/services/rest/
_replication/201409231
329353668' -d '{"pollInterval":"60","replicaType":"CONSUMER"}''
To query the details of a Clone’s replication agreement (including the polling interval),
use the following command.
curl -u <repluser>
'https://supplier.example.com:7002/oam/services/rest/_replication/201409231
329353668?type=consumer'
The output would be similar to the following.
{"enabled":"true","identifier":"201409231329353668","ok":"true",
"pollInterval":"60","startingSequenceNumber":"110","state":"READY"}
To query the details of a Master’s replication agreement (including the polling
interval), use the following command.
curl -u <repluser>
'https://supplier.example.com:7001/oam/services/rest/_replication/201409231
329353668'
The output would be similar to the following. (The poll Interval of the Master’s
replication agreement does not affect the actual replication.)
{"enabled":"true","identifier":"201409231329353668","ok":"true",
"pollInterval":"3600","startingSequenceNumber":"110","state":"ACTIVE"}
In R2PS3, the following command can also be used on the Master or the Clone to get
details of any replication agreements. In cases where the replication agreement
identifier is unknown, this command can be used to list all the replication agreement
identifiers for input in the previous commands.
Note: If a specific user needs to be used for replication, the user’s
credentials can be provided in the command in the format "BASIC
base64(user:password)".
For example, "BASIC base64(weblogic:welcome1)" is specified as
"BASIC d2VibG9naWM6d2VsY29tZTE=" in the following command.
curl -u <repluser> -H 'Content-Type: application/json' -X POST
'https://supplier.example.com:7002/oam/services/rest/
_replication/setup' -d
'{"source":"DC1","target":"DC2","documentType":"ENTITY","config":
{"entry":{"key":"authorization","value":"BASIC
d2VibG9naWM6d2VsY29tZTE="}}}''
Basic Authorization is supported for replication REST API.
Syncing Master and Clone Metadata
19-8 Administrator's Guide for Oracle Access Management
curl -k -u weblogic
'https://oamadmin.example.com:7002/oam/services/rest/_replication/agreements'
Sample output 1:
{"featureEnabled":"true","identifiers":"201411211137273612","ok":"true"}
Sample output 2:
{"featureEnabled":"true","identifiers":["201411211137273612","201411211137273900"]
,"ok":"true"}
To remove a replication agreement, first disable it on the Clone side, then disable it on
the Master side and then delete it on both sides. The following commands illustrate
this process.
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com:7002/oam/services/rest/_replication/201409231
329353668' -d '{"enabled":"false","replicaType":"CONSUMER"}''
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com:7002/oam/services/rest/_replication/201409231
329353668' -d '{"enabled":"false","replicaType":"SUPPLIER"}''
curl -u weblogic:welcome1 -H 'Content-Type: application/json' -X DELETE
'https://supplier.example.com:7001/oam/services/rest/_replication/201409231
329353668'
19.3.3 Modifying the Replication Agreement
Using the Replication Agreement identifier, changes can be made to the Replication
Agreement configuration. In this example, the value of pollInterval will be changed to
60 seconds.
Service responds back with JSON object that is the status of replication agreement
before making the change. You need to fetch replication agreement status again to see
updated configuration.
1. Execute the following command to get the current status of the Replication
Agreement.
curl -u weblogic:****** -H ’Content-Type: application/json’
’http://oam1-nyc.example.com:7001/oam/services/rest/
_replication/201409040157218184’
The JSON response would be:
{“enabled”:”true”,”identifier”:”201409040157218184?,”ok”:”true”,
”pollInterval”:”3600?,”startingSequenceNumber”:”101?,”state”:”ACTIVE”}
2. Execute the following command to modify the value of pollInterval.
curl -u weblogic:****** -H ’Content-Type: application/json’
-X PUT ’http://oam1-nyc.example.com:7001/oam/services/rest/
_replication/201409040157218184’
-d ’{“pollInterval”:”60?,”replicaType”:”consumer”}’
The JSON response would be:
{“enabled”:”true”,”identifier”:”201409040157218184?,”ok”:”true”,”pollInterval”:
”3600?,”startingSequenceNumber”:”101?,”state”:”ACTIVE”}
3. Restart the AdminServer on both Master and Clone machines.
Using and Customizing Transformation Rules
Synchronizing Data In A Multi-Data Center 19-9
4. Execute the following command to get the current status of the Replication
Agreement.
This will validate that the change has been made. Note the value of pollInterval in
the JSON Response is different from the value returned in the first step of this
procedure.
curl -u weblogic:****** -H ’Content-Type: application/json’
’http://oam1-nyc.example.com:7001/oam/services/rest/
_replication/201409040157218184’
The JSON response would be:
{“enabled”:”true”,”identifier”:”201409040157218184?,”ok”:”true”,
”pollInterval”:”60?,”startingSequenceNumber”:”101?,”state”:”ACTIVE”}
19.4 Using and Customizing Transformation Rules
Transformation rules are used by APS. The transformation rules illustrated in
Example 19–1 are the default rules provided by Access Manager. A Clone can be
configured to override these OOTB rules. This section documents how some of these
rules can be modified and how to configure Access Manager to recognize these custom
rules.
Example 19–1 Default Transformation Rules
<?xml version="1.0" encoding="UTF-8"?>
<mdc-transform-rule>
<changes-to-include entity-path="/policy"/>
<changes-to-include
entity-path="/config/NGAMConfiguration/DeployedComponent/Agent/WebGate/Instance">
<replace attribute-match="/*/PrimaryServerList/*/host" value-match="(.*)">
<replace-with
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}</replace-with>
</replace>
<replace attribute-match="/*/UserDefinedParameters/logoutRedirectUrl"
value-match="(.*)://(.*):(.*)/oam/server/logout">
<replace-with
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverprotocol}</replace-with>
<replace-with
n="2">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}</replace-with>
<replace-with
n="3">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverport}</replace-with>
</replace>
<replace attribute-match="/*/logoutRedirectUrl"
value-match="(.*)://(.*):(.*)/oam/server/logout">
<replace-with
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverprotocol}</replace-with>
<replace-with
n="2">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}</replace-with>
<replace-with
n="3">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
Using and Customizing Transformation Rules
19-10 Administrator's Guide for Oracle Access Management
erverProfile/OAMSERVER/serverport}</replace-with>
</replace>
</changes-to-include>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/Authenticat
ionModules"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/oamproxy"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/Sme/Session
Configurations"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerPr
ofile/OAMSERVER">
<ignore attribute-match="/serverprotocol"/>
<ignore attribute-match="/serverhost"/>
<ignore attribute-match="/serverport"/>
</changes-to-include>
<changes-to-include
entity-path="/config/NGAMConfiguration/DataCenterConfiguration/Cluster">
<ignore attribute-match="/DataCenterType"/>
<ignore attribute-match="/ClusterId"/>
<ignore attribute-match="/WriteEnabledFlag"/>
</changes-to-include>
</mdc-transform-rule>
These transformation rules make changes to WebGate agent definitions. The following
information details how you can modify these changes for the PrimaryServerList and
logoutRedirectUrl attributes.
■PrimaryServerList updates the primary server list for all WebGate agents and
replaces them with the Access Manager server host from the Clone environment.
This change can be viewed in the oam-config.xml file; it replaces the value of the
PrimaryServerList attribute with the value equal to
${DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAM
SERVER/serverhost}; for example, oam1-lon.example.com. The limitation of this
rule is that it updates all servers in the primary list. You can use the transformation
rule in Example 19–2 to update servers in PrimaryServerList with the different
Clone servers.
Example 19–2 Modified PrimaryServerList Transformation Rule
<changes-to-include entity-path=
”/config/NGAMConfiguration/DeployedComponent/Agent/WebGate/Instance”>
<replace attribute-match=”/*/PrimaryServerList/0/host” value-match=”(.*)”>
<replace-with
n=”1?>${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Instance/oam_server1/host”}
</replace-with>
</replace>
<replace attribute-match=”/*/PrimaryServerList/1/host” value-match=”(.*)”>
<replace-with
n=”1?>${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Instance/oam_server2/host”}
</replace-with>
</replace>
</changes-to-include>
A load balancer is recommended between the WebGate and Access Manager
server. In this case, you do not have to update the PrimaryServerList across data
Modifying a Rule Document
Synchronizing Data In A Multi-Data Center 19-11
centers and can remove this transformation rule from the XML. However, you do
need to update the PrimaryServerList parameter for IAMSuiteAgent and
accessgate-oic unless you have configured these agents to communicate with the
load balancer as well. Example 19–3 illustrates how to change the transformation
rule to update the PrimaryServerList only for IAMSuiteAgent and accessgate-oic
agents and not WebGate agents.
Example 19–3 Modified Transformation Rule for Different Agents
<changes-to-include entity-path=”/config/NGAMConfiguration/DeployedComponent/
Agent/WebGate/Instance”>
<replace attribute-match=”/IAMSuiteAgent/PrimaryServerList/
*/host” value-match=”(.*)”>
<replace-with
n=”1?>${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/OAMServerProfile/OAMSERVER/serverhost”}
</replace-with>
</replace>
<replace attribute-match=”/accessgate-oic/PrimaryServerList/
*/host” value-match=”(.*)”>
<replace-with
n=”1?>${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/OAMServerProfile/OAMSERVER/serverhost”}
</replace-with>
</replace>
</changes-to-include>
■The logoutRedirectUrl attribute updates the logout URL protocol, host and port
for all WebGate agents with respective values from the Clone. If a load balancer is
used globally to define the logout URL for all WebGate agents in the Master
environment, you don’t need to replace the logout URL in the Clone environment
and can remove the transformation rule. If you are using a DCC authentication
scheme and a global load balancer host name to define the DCC login and logout
URL, then again you don’t need to replace the login and logout URL in the Clone
environment and can remove the transformation rule.
To configure Access Manager to use custom transformation rules, update the
setDomainEnv.xml
file on the Clone machine. Each Clone can use different
transformation rules. Be sure to restart the Clone’s AdminServer after changing a
transformation rule. Figure 19–4 illustrates how to apply these custom rules.
Figure 19–4 Applying Custom Transformation Rules
19.5 Modifying a Rule Document
A rule document is created for the purpose of replicating. The allowed transformation
rules are represented by the XML document in Example 19–4.
Example 19–4 Replication Rules XML File
<?xml version="1.0" encoding="UTF-8"?>
<mdc-transform-rule>
Modifying a Rule Document
19-12 Administrator's Guide for Oracle Access Management
<changes-to-include entity-path="/policy"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Agent/WebGate/Instance">
<replace attribute-match="/*/PrimaryServerList/*/host" value-match="(.*)">
<replace-with n="1">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
</replace>
<replace attribute-match="/*/UserDefinedParameters/logoutRedirectUrl"
value-match="(.*)://(.*):(.*)/oam/server/logout">
<replace-with n="1">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverprotocol}</replace-with>
<replace-with n="2">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
<replace-with n="3">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverport}</replace-with>
</replace>
<replace attribute-match="/*/logoutRedirectUrl"
value-match="(.*)://(.*):(.*)/oam/server/logout">
<replace-withn="1">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverprotocol}</replace-with>
<replace-with n="2">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
<replace-with n="3">
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverport}</replace-with>
</replace>
</changes-to-include>
<changes-to-include entity-
path="/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/
AuthenticationModules"/>
<changes-to-include entity-
path="/config/NGAMConfiguration/DeployedComponent/Server/NGA
MServer/Profile/oamproxy"/>
<changes-to-include entity-
path="/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/Sme/SessionConfigurations"/>
<changes-to-include entity-
path="/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/OAMServerProfile/OAMSERVER">
<ignore attribute-match="/serverprotocol"/>
<ignore attribute-match="/serverhost"/>
<ignore attribute-match="/serverport"/>
</changes-to-include>
<changes-to-include entity-
path="/config/NGAMConfiguration/DataCenterConfiguration/Cluster">
<ignore attribute-match="/DataCenterType"/>
<ignore attribute-match="/ClusterId"/>
<ignore attribute-match="/WriteEnabledFlag"/>
</changes-to-include>
</mdc-transform-rule>
The rule document will mention the XPath of system configuration artifacts to be
replicated for a clone. If there is any transformation to be done during replication for
the entry in XPath, it can be provided as replacement rule for that clone. To add a new
Using REST API for Replication Agreements
Synchronizing Data In A Multi-Data Center 19-13
XPath for replication to a clone, create a new transformation XML file, using the above
XML document as a template. Add and remove XPaths as required. For example,
adding the following XPath as the child of an <mdc-transformation-rule> node and
saving the file to the clone’s file system will modify Available Services.
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Descriptors/
OAMSEntityDescriptor" />
Set the following VM property in the Clone’s adminserver (setDomainEnv.sh) to use
the newly created transformation rule document for replication instead of the OOTB
one.
-Doracle.oam.MDCRuleFile=/path/to/rule/mdcrule.xml
For developer recommendations when using replication, see Section 19.8, "Best
Practices for Replication."
19.6 Using REST API for Replication Agreements
The following sections contain details on how to use the REST API provided by Access
Manager.
■Querying for Replication Agreement Details
■Modifying an Existing Replication Agreement
■Deleting a Replication Agreement
19.6.1 Querying for Replication Agreement Details
A REST request can be executed at the Master's endpoint to query the details of the
Replication Agreement between a Master and a Clone.
GET http://oam1.example.com/oam/services/rest/
_replication/201312040602298762 HTTP/1.1
Content-Type: application/json
To query details of a Clone, use the following:
GET http://oam1.example.com/oam/services/rest/
_replication/201312040602298762?type=CONSUMER HTTP/1.1 HTTP/1.1
Content-Type: application/json
19.6.2 Modifying an Existing Replication Agreement
Replication Agreement properties (enabled status, poll interval and the like) can be
updated by executing a REST request at the Master's endpoint. Either the Master or
Clone Replication Agreement will be updated as specified by the value of the
replicaType parameter. The clone will poll for changes, apply them and wait the
duration specified as the pollInterval.
PUT http://supplier.example.com/oam/services/rest/
_replication/201312040602298762 HTTP/1.1
Content-Type: application/json
{"enabled":"false","pollInterval":"60","replicaType":"CONSUMER"}
This example will disable the Clone Replication Agreement and change the poll
interval to '60' seconds. If a value for replicaType is not defined (or it is defined as
SUPPLIER), the Master's Replication Agreement will be updated.
Replicating Domains in Identity Manager Deployments
19-14 Administrator's Guide for Oracle Access Management
To edit the poll interval using cURL, use the following command. Note that the
replicaType value for updating the clone in this case is SUPPLIER or CONSUMER.
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com/oam/services/rest/_replication/201409231329353668'
-d '{"pollInterval":"60","replicaType":"CONSUMER"}'
Table 19–2 lists properties that can be modified using cURL and REST.
19.6.3 Deleting a Replication Agreement
A Replication Agreement can be deleted by executing the following REST API at the
master DC's endpoint. Replication Agreements that are currently active and in use
cannot be deleted until the Master and Clone have been disabled.
DELETE http://oam1.example.com/oam/services/rest/_replication/
201312040602298762 HTTP/1.1
19.7 Replicating Domains in Identity Manager Deployments
If you have a deployment where Access Manager 11.1.2.1.0 and Oracle Identity
Manager (11.1.2.1.0) are integrated in the same domain T2P cannot be used for domain
replication because Identity Manager does not support it. In this case, Access Manager
and Identity Manager should be installed in different domains using the following
procedure.
1. Install Access Manager.
2. Run
configureSecurityStore (-create)
.
3. Start Access Manager.
Remember to enable TRACE logging with instrumented EAR.
4. Install Identity Manager.
Table 19–2 Modifying Replication Agreement Properties
Property Modification Command
BatchSize Number of change records (journals) returned by the master as a result of a
getChanges query by clone. Ideally the default batch size of 32 is sufficient as all
changes are pulled in multiple batches as part of fetching. However if the setup
needs a large batch size, execute the following command:
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://master.example.com/oam/services/rest/_
replication/<replid>'
-d '{"batchSize":"100","replicaType":"SUPPLIER"}'
User Context In rare instances, the user context for replication poll may need to be modified.
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com:7002/oam/services/rest/_
replication/201409231329353668'
-d '{"replicaType":"CONSUMER",
"config":{"entry":{"key":"authorization","value":"
BASIC cG9sbHVzZXI6c2VjcmV0"}}}'
'cG9sbHVzZXI6c2VjcmV0' is a base 64 encoded value for polluser credentials.
Any user credentials can be used here instead of the repluser which is used to
execute the command.
Best Practices for Replication
Synchronizing Data In A Multi-Data Center 19-15
5. Run
configureSecurityStore (-join)
.
6. Update the default passwords for the Access Manager and Identity Manager
domains in
$DOMAIN_HOME/config/fmwconfig/default-keystore.jks
password
using the
keytool
command.
7. Set the same password values in the CSF using the EM console.
a. Navigate to the domain_name of the appropriate Weblogic domain.
b. Right click the domain_name and navigate to Security --> Credentials.
c. Expand the
oracle.wsm.security
Credential map and edit the value of
keystore-csf-key
.
d. Update password and confirm password fields with the password.
This password should be same as the new password for
default-keystore.jks
in both Access Manager and Identity Manager
domains
8. Map oracle.wsm.security with the Key keystore-csf-key.
9. Start Identity Manager.
10. Restart Access Manager and Identity Manager.
19.8 Best Practices for Replication
The following points and the information in the sections should be taken into account
when setting up data replication.
■It is recommended that as many Policy Domain artifacts are created as possible
before cloning. This will help the replication manager work efficiently during
incremental updates.
■The OAM server instance list will be used as the Well Known Addresses (WKA) to
create a Coherence cluster so do not add other data center servers to the server
instance list.
■To allow for a WebGate profile to point to a remote data center in the secondary
server list, use the Other option to provide OAP with the host and port details of
the remote data center.
■Enabling Replication Logs
■Changing the User Identifier
19.8.1 Enabling Replication Logs
To get detailed logs on replication agreement and replication poll related issues, enable
the logger ‘oracle.oam.replication’ by executing the WLST command
setLogLevel(logger="oracle.oam.replication", level="TRACE:32", persist="0",
target="AdminServer")
This will enable logger only till next shutdown of AdminServer. To keep the logger
state across restart, set the persist attribute to “1”
19.8.2 Changing the User Identifier
While creating replication agreement if you have not specified any authorization
header of the user to be used for replication if the user’s password got changed at later
Best Practices for Replication
19-16 Administrator's Guide for Oracle Access Management
point, you can edit the replication agreement with the latest user identity and
password using the following command.
curl -u <repluser> -H 'Content-Type: application/json' -X PUT
'https://supplier.example.com:7002/oam/services/rest/_replication/201409231
329353668' -d '{"replicaType":"CONSUMER","config":{"entry":
{"key":"authorization","value":"BASIC d2VibG9naWM6d2VsY29tZTE="}}}'
20
Setting Up the Multi-Data Center: A Sequence 20-1
20
Setting Up the Multi-Data Center: A Sequence
[18]
The sequence of steps in this chapter will help you to setup a Multi-Data Center with
four nodes using Oracle Access Manager 11.1.1.2. The configuration spans two Data
Centers with two nodes per Data Center. The nodes are configured in Active/Active
Mode.
This chapter contains the following section.
■Before You Begin
■Setting Up a Multi-Data Center
■Enabling Automated Policy Synchronization
■Troubleshooting the Multi-Data Center Setup
20.1 Before You Begin
Read the following chapters before beginning the steps documented in this sequence
for an understanding of Multi-Data Center and its features.
■Chapter 17, "Understanding Multi-Data Centers"
■Chapter 18, "Configuring Multi-Data Centers"
■Chapter 19, "Synchronizing Data In A Multi-Data Center"
Confirm the following before you begin the Multi-Data Center set-up sequence.
■Check that your operating system is up-to-date with all necessary patches applied.
■Mount the binaries you will be using. The applicable Oracle software includes:
–Oracle Fusion Middleware Identity and Access Management 11g (11.1.2.3.0)
–Oracle WebLogic Server 10g (10.3.6)
–Oracle Database 11g (11.2.0.4)
–Oracle Fusion Middleware Repository Creation Utility 11g (11.1.2.3.0)
■Add
/etc/hosts
entries on all four nodes being configured.
■Verify that the Oracle Database is connected and accessible.
■Verify that each machine has more than 30 GB space available and more than 8GB
of memory available.
Setting Up a Multi-Data Center
20-2 Administrator's Guide for Oracle Access Management
20.2 Setting Up a Multi-Data Center
Be sure to follow this sequence as documented for a successful set-up of a Multi-Data
Center with data replication using T2P. The configuration spans two Data Centers with
two nodes per Data Center. The nodes are configured in Active/Active Mode.
1. Install the Java Development Kit (JDK) 1.7.0.60 on all four of the Nodes and set the
appropriate environment variables.
2. Run the Repository Creation Utility (RCU) 11.1.2.3.0 on Data Center 1 and Data
Center 2.
This will create and load the appropriate database schemas for Oracle Identity and
Access Management products.
3. Install WebLogic Server 10g (10.3.6) on Data Center 1, Node 1.
This process creates the Middleware Home (<MW_HOME>).
4. Install the Oracle Identity and Access Management 11g (11.1.2.3.0) software on
Data Center 1, Node 1.
Oracle Identity and Access Management contains the Oracle Access Management
suite which includes Oracle Access Manager. The default name of this Oracle
product home directory after installation is Oracle_IDM1.
5. Run the Oracle Fusion Middleware Configuration Wizard script to configure
Oracle Access Management on Data Center 1, Node 1.
The Wizard script is
Oracle_IDM1/common/bin/config.sh
script (on Linux or
UNIX), or
Oracle_IDM1\common\bin\config.cmd
(on Windows). Minimally, you
will be configuring:
■a new WebLogic domain
■an Oracle Access Management Administration Server
■an Oracle Access Management Managed Server
■Oracle Access Manager
6. Run the
configureSecurityStore.py
script on Data Center 1, Node 1 to configure
the Database Security Store.
a.
<MW_HOME>/oracle_common/common/bin/wlst.sh
b.
<MW_HOME>/Oracle_IDM1/common/tools/configureSecurityStore.py
-c IAM -d <MW_HOME>/user_projects/domains/OAMDomain
-p Oracle123 -m create -v
7. Modify the following WebLogic scripts on Data Center 1, Node 1.
a. Open
startWeblogic.sh
and
startManagedWeblogic.sh
using vi and enter
the appropriate value for WLS_USER.
Enter the password when asked; do not hard code it here.
b. Save
startWeblogic.sh
and
startManagedWeblogic.sh
.
c. Open
setDomainEnv.sh
using vi and add the following line:
USER_MEM ARGS=“-Xms1024m -Xmx1024m -XX:MaxPermSize=512m"
d. Save
setDomainEnv.sh
.
8. Create and run a
cConfig.sh
script in the MDC folder on Data Center 1, Node 1.
Setting Up a Multi-Data Center
Setting Up the Multi-Data Center: A Sequence 20-3
The
cConfig.sh
script concatenates the necessary environment variables and
copyConfig.sh
into one script. You will need to create the MDC folder to serve as
the T2P_HOME.
a. Add the following contents and save as
cConfig.sh
.
export JAVA_HOME=/u01/app/jdk1.7.0_60;
export MW_HOME=/u01/app/Middleware;
export T2P_HOME=/u01/bits/MDC;
export WL_DOMAIN_HOME=$MW_HOME/user_projects/domains/OAMDomain;
b. Source
cConfig.sh
.
$<>. cConfig.sh
9. Execute
copyBinary.sh
on Data Center 1, Node 1.
copyBinary.sh
and
pasteBinary.sh
will be used to avoid a time-consuming
installation process on the remaining nodes. When running
copyBinary.sh
, the
Administration and Managed Servers can be running or stopped.
a. Change to the
bin
directory.
cd $MW_HOME/oracle_common/bin/;
b. Run the script.
./copyBinary.sh -javaHome $JAVA_HOME
-archiveLoc $T2P_HOME/oamt2pbin.jar -sourceMWHomeLoc $MW_HOME
-idw true -ipl $MW_HOME/oracle_common/oraInst.loc -silent true
-ldl $T2P_HOME/oam_cln_log
10. Copy the following files to the MDC folder on Data Center 1, Node 1.
■$T2P_HOME/cConfig.sh (already in the MDC folder)
■$T2P_HOME/oamt2pbin.jar (already in the MDC folder)
■$MW_HOME/oracle_common/bin/pasteBinary.sh
■$MW_HOME/oracle_common/jlib/cloningclient.jar
■$MW_HOME/oracle_common/oraInst.loc
11. Copy the MDC folder (populated with the five files) to Data Center 1, Node 2, and
Data Center 2, Nodes 1 and 2.
12. Execute
pasteBinary.sh
on Data Center 1, Node 2.
a. Source
cConfig.sh
.
$<>. cConfig.sh
b. Run
pasteBinary.sh
on Data Center 1, Node 2.
$T2P_HOME/pasteBinary.sh -javaHome $JAVA_HOME
-al $T2P_HOME/oamt2pbin.jar -tmw $MW_HOME -silent true
-idw true -esp false -ipl $T2P_HOME/oraInst.loc
-ldl $T2P_HOME/oam_cln_log -silent true
13. Create a Managed Server JAR on Data Center 1, Node 1 and copy it to Data Center
1, Node 2.
pack.sh
is used to create the JAR and is located in the <MW_HOME>/oracle_
common/common/bin directory. The pack and unpack (used in the next step)
scripts must be executed in the same Data Center only whereas copyConfig and
Setting Up a Multi-Data Center
20-4 Administrator's Guide for Oracle Access Management
pasteConfig (used later in the procedure) must be executed to the Master node of
the other Data Center and then run Pack/UnPack within those data centers.
a. Run
pack.sh
.
./pack.sh -domain=$MW_HOME/user_projects/domains/OAMDomain
-template=OAMManagedServer.jar -template_name=“OAM Domain” -managed=true
b. Copy
OAMManagedServer.jar
to the MW_HOME/oracle_
common/common/bin directory on Data Center 1, Node 2.
14. Unpack the Managed Server JAR on Data Center 1, Node 2 using
unpack.sh
.
The JAR is used as a template to create the OAMDomain Domain Structure on
Data Center 1, Node 2.
a.
mkdir -p $MW_HOME/user_projects/domains/OAMDomain
b.
cd <MW_HOME>/oracle_common/common/bin
c.
./unpack.sh -domain=$MW_HOME/user_projects/domains/OAMDomain
-template=OAMManagedServer.jar
15. Modify the following WebLogic scripts on Data Center 1, Node 2.
a. Open
startManagedWeblogic.sh
using vi and enter the appropriate values for
WLS_USER and WLS_PW.
b. Save
startWeblogic.sh
and
startManagedWeblogic.sh
.
c. Open
setDomainEnv.sh
using vi and add the following line:
USER_MEM ARGS=“-Xms1024m -Xmx1024m -XX:MaxPermSize=512m"
d. Save
setDomainEnv.sh
.
At this point in the sequence, the Data Center 1 cluster and its two nodes are
configured and ready for Multi-Data Center configurations. Start the
Administration Server and the oam_server1 and oam_server2 Managed Servers.
Disable the SSL port number 14101.
16. Enable Multi-Data Center mode on Data Center 1, Node 1.
a.
cd $T2P_HOME/MDC
b. Create
OAMMDC.properties
on Data Center 1, Node 1 using vi.
Add the following lines to
OAMMDC.properties
and save.
SessionMustBeAnchoredToDataCenterServicingUser=false
SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_retry_attempts=3
SessionDataRetrievalOnDemandMax_conn_wait_time=80
SessionContinuationOnSyncFailure=true
MDCGitoCookieDomain=.customerpoc.com
c. Change to the ../Oracle_IDM1/common/bin directory and run WLST.
d.
./wlst.sh
e.
connect()
f.
domainRuntime()
g.
enableMultiDataCentreMode(propfile=“../OAMMDC.properties”)
h.
setMultiDataCentreClusterName(clusterName="<string_value>”)
Setting Up a Multi-Data Center
Setting Up the Multi-Data Center: A Sequence 20-5
i.
setMultiDataCenterWrite(WriteEnabledFlag="true")
j.
validateMDCConfig()
k.
exit()
17. Create
oamt2pconfig.jar
on Data Center 1, Node 1 and copy it to Data Center 2,
Node 1.
copyConfig.sh
is located in $MW_HOME/oracle_common/bin/ and must be
executed on the Master node. To run
copyConfig.sh
, the Administration and
Managed Servers should be up and running.
a. Source
cConfig.sh
.
$<>. cConfig.sh
b. Create
$T2P_HOME/t2p_domain_pass.txt
using vi.
Add a password value for use with copyConfig.sh; for example, Oracle123
(without quotes).
c.
./copyConfig.sh -javaHome $JAVA_HOME
-archiveLoc $T2P_HOME/oamt2pConfig.jar
-sourceDomainLoc $WL_DOMAIN_HOME
-sourceMWHomeLoc $MW_HOME
-domainHostName oam1-dc1.customerpoc.com
-domainPortNum 7001 -domainAdminUserName weblogic
-domainAdminPassword $T2P_HOME/t2p_domain_pass.txt
-silent true -ldl $T2P_HOME/oam_cln_log_config
-opssDataExport true -debug true
d. Copy
oamt2pconfig.jar
to the Data Center 2, Node 1.
18. Execute
pasteBinary.sh
on Data Center 2, Node 1.
a. Source
cConfig.sh
.
$<>. cConfig.sh
b. Run:
$T2P_HOME/pasteBinary.sh -javaHome $JAVA_HOME
-al $T2__HOME/oamt2pbin.jar -tmw $MW_HOME -silent true
-idw true -esp false -ipl $T2P_HOME/oraInst.loc
-ldl $T2P_HOME/oam_cln_log -silent true
19. Execute
pasteBinary.sh
on Data Center 2, Node 2.
a. Source
cConfig.sh
.
$<>. cConfig.sh
b. Run:
$T2P_HOME/pasteBinary.sh -javaHome $JAVA_HOME
-al $T2__HOME/oamt2pbin.jar -tmw $MW_HOME -silent true
-idw true -esp false -ipl $T2P_HOME/oraInst.loc
-ldl $T2P_HOME/oam_cln_log -silent true
20. Execute
extractmovePlan.sh
on Data Center 2, Node 1.
a.
mkdir $T2P_HOME/moveplan
b.
cd $MW_HOME/oracle_common/bin/
Setting Up a Multi-Data Center
20-6 Administrator's Guide for Oracle Access Management
c. Source
cConfig.sh
.
$<>. cConfig.sh
d.
./extractMovePlan.sh -javaHome $JAVA_HOME -al $T2P_
HOME/oamt2pConfig.jar -planDirLoc $T2P_HOME/moveplan/
e. Backup the moveplan and then make the following modifications using vi.
Search and Replace the hostnames
:1,$s/oam1-dc1/oam1-dc2/g
:1,$s/oam2-dc1/oam2-dc2/g
Search and replace datasource names
:1,$s/DC1/DC2/g
Search for the two instances of "Password File” and add the previously
created t2p_domain_pass.txt Password File location as a <value>.
<value>/u01/bits/final/MDC/t2p_domain_pass.txt</value>
f. Create $T2P_HOME/t2p_pass.txt with a password value you want.
This file is used to create new components on the target environment with the
associated password. The moveplan has a reference to it so that when the
components are created the password will be assigned.
21. Run the
psa.sh
PSA script to update the Oracle Platform Security Services (OPSS)
schema on Data Center 2, Node 1.
The script is in the Oracle_IDM1/bin/ directory. Use the following procedure to
verify that the PSA has updated the OPSS version from 11.1.1.7.0 to 11.1.1.7.2.
a. Connect to the system as sysdba.
You can use SQL Plus or SQL Developer.
b. Enter the following SQL statement.
select * from DC2_OPSS.JPS_ATTRS where JPS_
ATTRS.ATTRNAME='orclProductVersion';
22. Execute
pasteConfig.sh
on Data Center 2, Node 1.
The same JDK used on the source must be used on the target.
$MW_HOME/oracle_common/bin/pasteConfig.sh
-javaHome $JAVA_HOME -archiveLoc $T2P_HOME/oamt2pConfig.jar
-targetMWHomeLoc $MW_HOME -targetDomainLoc $WL_DOMAIN_HOME
-movePlanLoc $T2P_HOME/moveplan/moveplan.xml -domainAdminPassword
$T2P_HOME/t2p_domain_pass.txt -ldl $T2P_HOME/oam_cln_log
-silent true
23. Modify the following WebLogic scripts on Data Center 2, Node 1.
a. Open
startWeblogic.sh
and
startManagedWeblogic.sh
using vi and enter
the appropriate values for WLS_USER and WLS_PW.
Note: Comment out all keystore <> tags in the moveplan if there is
an issue.
Setting Up a Multi-Data Center
Setting Up the Multi-Data Center: A Sequence 20-7
b. Save
startWeblogic.sh
and
startManagedWeblogic.sh
.
c. Open
setDomainEnv.sh
using vi and add the following line:
USER_MEM ARGS=“-Xms1024m -Xmx1024m -XX:MaxPermSize=512m"
d. Save
setDomainEnv.sh
.
24. Create a Managed Server JAR on Data Center 2, Node 1 and copy it to Data Center
2, Node 2.
pack.sh
is used to create the JAR and is located in the
<MW_HOME>/oracle_
common/common/bin
directory. The pack and unpack (used in the next step) scripts
must be executed in the same Data Center only.
a. Run
pack.sh
.
./pack.sh -domain=$MW_HOME/user_projects/domains/OAMDomain
-template=OAMManagedServer.jar -template_name=“OAM Domain” -managed=true
b. Copy
OAMManagedServer.jar
to the
<MW_HOME>/oracle_common/common/bin
directory on Data Center 2, Node 2.
25. Unpack the Managed Server JAR on Data Center 2, Node 2 using
unpack.sh
.
The JAR will be used as a template to create the OAMDomain Domain Structure
on Data Center 2, Node 2.
a.
mkdir -p $MW_HOME/user_projects/domains/OAMDomain
b.
cd <MW_HOME>/oracle_common/common/bin
c.
./unpack.sh -domain=$MW_HOME/user_projects/domains/OAMDomain
-template=OAMManagedServer.jar
26. Modify the following WebLogic scripts on Data Center 2, Node 2.
a. Open
startManagedWeblogic.sh
using vi and enter the appropriate values for
WLS_USER and WLS_PW.
b. Save
startWeblogic.sh
and
startManagedWeblogic.sh
.
c. Open
setDomainEnv.sh
using vi and add the following line:
USER_MEM ARGS=“-Xms1024m -Xmx1024m -XX:MaxPermSize=512m"
d. Save
setDomainEnv.sh
.
At this point in the sequence, the Data Center 2 cluster and its two nodes are
configured and ready for Multi-Data Center configurations. Start the
Administration Server and the oam_server1 and oam_server2 Managed Servers.
Disable the SSL port number 14101.
27. Enable Multi-Data Center mode on Data Center 2, Node 1.
a. Restart the Administration Server on Data Center 2, Node 1.
b. Change to the ../Oracle_IDM1/common/bin directory and run WLST.
c.
./wlst.sh
d.
connect()
e.
domainRuntime()
f.
enableMultiDataCentreMode(propfile=“//OAMMDC.properties”)
g.
setMultiDataCentreClusterName(clusterName="<string_value>”)
Setting Up a Multi-Data Center
20-8 Administrator's Guide for Oracle Access Management
h.
setMultiDataCenterWrite(WriteEnabledFlag="true")
i.
exit()
28. Create two WebGate agents using the Oracle Access Management Console on Data
Center 1, Node 1 only.
■Name the agents MDC-DC1 and MDC-DC2
■Check AccessClientPassword and AllowManagementOperations
■Be sure the Primary Server List has Access Server listed as “Other” - ideally it
will have global load balancer/LTM entries rather than the local hosts entries.
29. Create the MDCPartner-DC1 and MDCPartner-DC2 property files using vi
Create these files on both Data Center 1, Node 1 and Data Center 2, Node 1 with
the following data.
vi MDCPartner-DC1.properties
remoteDataCentreClusterId=FINALDC1
oamMdcAgentId=MDC-DC1
PrimaryHostPort=oam1-dc1.poc.com:5575
SecondaryHostPort
AccessClientPasswd
oamMdcSecurityMode=Open
agentVersion=11g
trustStorePath
keyStorePath
globalPassPhrase
keystorePassword
RESTEndpoint=http://oam1-dc1.poc.com:7001
vi MDCPartner-DC2.properties
remoteDataCentreClusterId=FINALDC2
oamMdcAgentId=MDC-DC2
PrimaryHostPort=oam1-dc2.poc.com:5575
SecondaryHostPort
AccessClientPasswd
oamMdcSecurityMode=Open
agentVersion=11g
trustStorePath
keyStorePath
globalPassPhrase
keystorePassword
RESTEndpoint=http://oam1-dc2.poc.com:7001
30. Register the partners on Data Center 1, Node 1 using wlst.sh.
a. Change to the ../Oracle_IDM1/common/bin directory and run WLST.
b.
./wlst.sh
c.
connect()
d.
domainRuntime()
e.
addPartnerForMultiDataCentre(propfile=“../MDCPartner-DC1.properties”)
f.
addPartnerForMultiDataCentre(propfile=“../MDCPartner-DC2.properties”)
g.
setMultiDataCenterType(DataCenterType=“Master”)
h.
exit()
Enabling Automated Policy Synchronization
Setting Up the Multi-Data Center: A Sequence 20-9
31. Register the partners on Data Center 2, Node 1 using wlst.sh.
a. Change to the ../Oracle_IDM1/common/bin directory and run WLST.
b.
./wlst.sh
c.
connect()
d.
domainRuntime()
e.
addPartnerForMultiDataCentre(propfile=“../MDCPartner-DC1.properties”)
f.
addPartnerForMultiDataCentre(propfile=“../MDCPartner-DC2.properties”)
g.
setMultiDataCenterType(DataCenterType=“Clone”)
h.
exit()
32. Export the partner and policy information from Data Center 1, Node 1 and then
import it to Data Center 2, Node 1.
a. Change to the ../Oracle_IDM1/common/bin directory and run WLST to
export from Data Center 1, Node 1.
b.
./wlst.sh
c.
connect()
d.
exportPartners(pathTempOAMPartnerFile=“<oampartner.xml>”)
e.
exportPolicy(pathTempOAMPolicyFile=“<oampolicy.xml>”)
f.
exit()
g. Copy
oampolicy.xml
and
oampartner.xml
to Data Center 2, Node 1.
h. Change to the ../Oracle_IDM1/common/bin directory and run WLST to
import on Data Center 2, Node 1.
i.
./wlst.sh
j.
connect()
k.
importPolicy(pathTempOAMPolicyFile=“<oampolicy.xml>”)
l.
importPartners(pathTempOAMPartnerFile=“<oampartner.xml>”)
m.
exit()
20.3 Enabling Automated Policy Synchronization
The sequence in this section will enable the Automated Policy Synchronization (APS)
feature for automated data synchronization among the servers. The procedure
includes commands for testing the REST services as well as details on adding custom
transformation rules to the synchronization. See Chapter 19, "Synchronizing Data In A
Multi-Data Center" for details on APS and transformation rules.
1. Stop all the Administration and Managed Servers.
2. Add the following line to
$WL_DOMAIN_HOME/bin/setDomainEnv.sh
on both Data
Center 1, Node 1 and Data Center 2, Node 1 and save the file.
EXTRA_JAVA_PROPERTIES="
-Doracle.oam.EnableMDCReplication=true -DCONFIG_DS=jdbc/oamds …
3. Start the Administration Servers only.
4. Test the REST services using the following commands:
Enabling Automated Policy Synchronization
20-10 Administrator's Guide for Oracle Access Management
curl -u weblogic 'http://oam1-dc1.customerpoc.com:7001/oam/services/rest/_
replication/hello'
RESPONSE: {"ok":"true”}
curl -u weblogic 'http://oam1-dc2.poc.com:7001/oam/services/rest/_
replication/hello'
RESPONSE: {"ok":"true”}
curl -u weblogic:Oracle123 -H 'Content-Type: application/json' -X POST
'http://oam1-dc1.poc.com:7001/oam/services/rest/_replication/setup' -d
'{"name”:"DC1toDC2",
"source”:"FINALDC1","target”:"FINALDC2","documentType":"ENTITY”}'
RESPONSE:
{"enabled":"true","identifier":"201409040157218184","ok":"true","pollInterval":"900","
startingSequenceNumber":"101","state":"READY"}
#The random long number will be unique to every replication agreement, so don’t
use that number as is, though use the number which comes as an output from the
3rd curl command below
curl -u weblogic:Oracle123 -H 'Content-Type: application/json’
'http://oam1-dc1.poc.com:7001/oam/services/rest/_
replication/201409040157218184'
RESPONSE:
{"enabled":"true","identifier":"201409040157218184","ok":"true","pollInterval":"3600"
,"startingSequenceNumber":"101","state":"ACTIVE"}
curl -u weblogic:Oracle123 -H 'Content-Type: application/json’
'http://oam1-dc1.poc.com:7001/oam/services/rest/_
replication/201409040157218184?type=consumer'
RESPONSE:
{"enabled":"true","identifier":"201409040157218184","ok":"true","pollInterval":"900","
startingSequenceNumber":"101","state":"READY"}
curl -u weblogic:Oracle123 -H 'Content-Type: application/json' -X PUT
'http://oam1-dc1.poc.com:7001/oam/services/rest/_
replication/201409040157218184' -d '{"pollInterval":"60","replicaType":"consumer"}'
RESPONSE:
{"enabled":"true","identifier":"201409040157218184","ok":"true","pollInterval":"3600"
,"startingSequenceNumber":"101","state":"ACTIVE”}
#Run this command on NODE1DC2 ONLY IF you want to disable Policy Writes to
DC2 (or Clones) and just accept policy writes via the Master Policy Server using
APS Synch: setMultiDataCenterWrite(WriteEnabledFlag="false”)
5. Create a transformation rules file using vi as
$T2P_
HOME/transformationrules.xml
.
transformationrules.xml
should contain the following content.
<?xml version="1.0" encoding="UTF-8"?>
<mdc-transform-rule>
<changes-to-include
entity-path="/DeployedComponent/Agent/WebGate/Instance">
<replace attribute-match="/IAMSuiteAgent/PrimaryServerList/*/host”
value-match="(.*)">
<replace-with
n="1">${DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/
Troubleshooting the Multi-Data Center Setup
Setting Up the Multi-Data Center: A Sequence 20-11
serverhost}</replace-with>
</replace>
</changes-to-include>
<changes-to-include
entity-path="/DeployedComponent/Server/NGAMServer/Profile/AuthenticationModules
"/>
</mdc-transform-rule>
6. Add the following line to
$WL_DOMAIN_HOME/bin/setDomainEnv.sh
on Data Center
2, Node 1 only and save the file.
EXTRA_JAVA_PROPERTIES="
-Doracle.oam.MDCRuleFile=/u01/bits/customer/MDC/transformationrules.xml
-Doracle.oam.EnableMDCReplication=true -DCONFIG_DS=jdbc/oamds …
7. Start the Administration and Managed Servers.
This completes the Multi-Data Center setup with T2P data replication and APS
configuration! You can test the APS function by creating an agent and a policy on data
Center 1 and verifying that it auto migrates to Data Center 2.
20.4 Troubleshooting the Multi-Data Center Setup
Follow this procedure if you have identified inconsistencies or errors in your setup
and want to revert the APS.
1. Disable replication on the Master (Supplier).
curl -u weblogic:welcome1 -H 'Content-Type: application/json'
-X PUT 'http://supplier.example.com:7001/oam/services/
rest/_replication/201311271226476658'
-d '{"enabled":"false","replicaType":"SUPPLIER"}'
2. Disable replication on the Clone (Consumer).
curl -u weblogic:welcome1 -H 'Content-Type: application/json'
-X PUT 'http://supplier.example.com:7001/oam/services/
rest/_replication/201311271226476658'
-d '{"enabled":"false","replicaType":"CONSUMER"}'
3. Delete the replication agreements on the Master and Clone using this command.
curl -u weblogic:welcome1 -H 'Content-Type: application/json'
-X DELETE 'http://supplier.example.com:7001/oam/services/
rest/_replication/201311271226476658'
4. commit;
Note: The AM_REPLICATION_SETTINGS table in the OAM
Schema defines the replication agreements so you can also delete the
agreements by manual deletion using the following SQL statement.
■Select * from FINALDC1_OAM.AM_REPLICATION_SETTINGS;
■Select * from FINALDC2_OAM.AM_REPLICATION_SETTINGS;
Alternately:
■Delete from FINALDC1_OAM.AM_REPLICATION_SETTINGS;
■Delete from FINALDC2_OAM.AM_REPLICATION_SETTINGS;
Troubleshooting the Multi-Data Center Setup
20-12 Administrator's Guide for Oracle Access Management
Part VI
Part VI
Managing Access Manager SSO, Policies,
and Testing
This part, Part V, provides information to help you understand single-sign on (SSO)
with Access Manager, and help you to configure Access Manager policies and logout.
Testing your single sign-on connection and policies is also described.
Part V contains the following chapters:
■Chapter 21, "Understanding Single Sign-On with Access Manager"
■Chapter 22, "Managing Authentication and Shared Policy Components"
■Chapter 23, "Understanding Credential Collection and Login"
■Chapter 24, "Using Password Policy"
■Chapter 25, "Managing Policies to Protect Resources and Enable SSO"
■Chapter 26, "Validating Connectivity and Policies Using the Access Tester"
■Chapter 27, "Configuring Centralized Logout for Sessions Involving 11g
WebGates"
21
Understanding Single Sign-On with Access Manager 21-1
21
Understanding Single Sign-On with Access
Manager
[19]
This chapter introduces the elements that comprise Access Manager single sign-on. It
provides an administrator with the foundation to begin developing policies.
This chapter includes the following topics:
■Introducing Access Manager Single Sign-On
■Understanding the Access Manager Policy Model
■Anatomy of an Application Domain and Policies
■Introduction to Policy Conditions and Rules
■Understanding SSO Cookies
■Introduction to Configuration Tasks for Single Sign-On
21.1 Introducing Access Manager Single Sign-On
Login is the action a user takes to authenticate and gain access to a protected
application. Single sign-on (SSO) is the process that gives users the ability to access
multiple protected resources (Web pages and applications) with a single
authentication. SSO is enabled by Access Manager to eliminate the need for additional
or different logins to access other applications at the same (or lower) authentication
level during the same session.
Access Manager converges several SSO architectures (including Identity Federation for
Partner Networks, and Service Oriented Architecture) and provides SSO through a
common SSO Engine for consistent service across multiple protocols. The Oracle
Identity Management Infrastructure stores user identities in the identity store
referenced in the policy.
Note: Unless explicitly stated, information in this chapter is the same
for all agent types and Access Manager credential collectors.
For details about single log-out, see Chapter 27, "Configuring
Centralized Logout for Sessions Involving 11g WebGates".
Introducing Access Manager Single Sign-On
21-2 Administrator's Guide for Oracle Access Management
Table 21–1 summarizes the components that support or enforce Access Manager
policies, and where to find more information about these, if needed.
Note: Contextual data is the information that is presented to or
collected by Access Manager at various stages of user interaction.
These stages include authentication, authorization, enterprise SSO,
federation, adaptive authentication, token validation, session creation,
and so on. The information itself might comprise a user's device
fingerprints, IP address, antivirus and firewall protection, assertion
and so on. Components that play the role of contextual data providers
and asserters when integrated with Access Manager include
Enterprise Single Sign-on, Identity Federation, Oracle Adaptive
Access Manager.
Note: Default Access Manager behavior is to deny access when a
resource is not protected by a policy that explicitly allows access. To
delegate authentication tasks to Access Manager, agents must reside
with the relying parties and must be registered with Access Manager.
Registering an agent sets up the required trust mechanism between
the agent and Access Manager SSO.
Table 21–1 Summary: SSO Components
Component Description
Applications Applications can delegate authentication and authorization to Access Manager and accepts
headers from a registered Agent.
Note: External applications do not delegate authentication. Instead, these display HTML
login forms that ask for application user names and passwords. For example, Yahoo! Mail
is an external application that uses HTML login forms.
■OAM Server
■Oracle Access Management
Console (installed on
WebLogic AdminServer)
Non-administrative users first gain access by entering the URL of a protected resource,
which returns the SSO login page.
See Also: "Understanding Credential Collection and Login".
Administrative users access the console to author policies by typing the URL:
https://host:port/oamconsole. Although, default policies can be generated automatically
during Agent registration, as described in Chapter 15.
See Also: Chapter 25, "Managing Policies to Protect Resources and Enable SSO".
Policy Enforcement Agents ■OAM Agents (Webgate or Access Client)
■Legacy OSSO Agents
■Legacy OpenSSO Agents
See Also: Chapter 14, "Introduction to Agents and Registration".
Credential Collectors and
Communication Channels
■Authentication with the default embedded credential collector (ECC) occurs across
the HTTP (HTTPS) channel
■Authentication with the optional detached credential collector (DCC) occurs across
the Oracle Access Protocol (OAP) channel
■Authorization occurs across the Oracle Access Protocol (OAP) channel
See Also: Table 22–5, " Comparing the DCC and ECC"
SSO Engine Manages the session lifecycle, facilitates global logout across all relying parties in the valid
session, and provides consistent service across multiple protocols.
See Also: Chapter 16, "Maintaining Access Manager Sessions" and Chapter 27,
"Configuring Centralized Logout for Sessions Involving 11g WebGates"
Introducing Access Manager Single Sign-On
Understanding Single Sign-On with Access Manager 21-3
Single sign-on can be implemented as introduced in Table 21–2, which includes
pointers to additional information.
Proxy support for legacy systems ■OAM Proxy supports legacy Access Manager implementations by acting as a legacy
Access Server. See:
"Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security"
"Introduction to OAM Proxy Metrics and Tuning" on page 11-10
■OSSO Proxy supports OSSO Agents by acting as the legacy OSSO Server. See:
Chapter 29
■Oracle-provided OpenSSO Proxy handles requests for resources protected by
OpenSSO Agents. See: Chapter 28
See Also: About the Embedded Proxy Server and Backward Compatibility
Access Policies Registered agents rely on Access Manager authentication, authorization, and token
issuance policies to determine who gets access to protected applications (defined
resources).
Note: Default Access Manager behavior is to deny access when a resource is not protected
by a policy that explicitly allows access.
See Also: Chapter 25, "Managing Policies to Protect Resources and Enable SSO"
Policy Store Database in production environments (otherwise, oam-config.xml).
See Also: Chapter 5
Cryptographic keys and Key
Storage
One key is generated and used per registered mod_osso or 11g Webgate. However, one
single key is generated for all 10g Webgates.
See Also: Table 1–2, " Features in Access Manager 11.1.2".
Cookies See: "Understanding SSO Cookies" on page 21-14.
Note: Single Sign-on for the Oracle Access Management Console,
and other Oracle Identity Management consoles deployed in a
WebLogic container, is enabled using the pre-registered
IAMSuiteAgent and companion policies. No further configuration is
needed to protect the consoles.
Table 21–2 Introduction to SSO Implementations
SSO Type Description
Single Network Domain SSO You can set up Access Manager single sign-on for resources within a
single network domain (example.com, for example). This includes
protecting resources belonging to multiple WebLogic administration
domains within a single network domain.
Single Network Domain SSO is the subject of this book.
Multiple Network Domain SSO Access Manager 11g supports cross-network-domain single sign-on
out of the box.
See Also:"About Multiple Network Domain SSO" on page 21-4.
Application SSO Application single sign-on allows users who have been authenticated
by Access Manager to access applications without being
re-authenticated.
See Also: "About Application SSO and Access Manager" on page 21-4
Table 21–1 (Cont.) Summary: SSO Components
Component Description
Introducing Access Manager Single Sign-On
21-4 Administrator's Guide for Oracle Access Management
21.1.1 About Multiple Network Domain SSO
With Access Manager, this is a standard feature. When 11g WebGates are used
exclusively all cookies in the system are host-based. However, you must have control
over all the domains. If some domains are controlled by external entities (not part of
the Access Manager deployment), Oracle recommends that you use Identity
Federation.
Access Manager supports cross-network-domain single sign-on out of the box. During
single sign-off with Access Manager:
■The SSO cookie set by OAM Server is a host cookie that works across the network
domains. The WebGate clears its standalone Agent cookie and then redirects to the
OAM Server for session clearing.
■10g WebGates do not have a standalone Agent cookie; logout occurs only on the
server side with no redirection required.
■With 11g WebGates and OSSO agents that support a standalone agent cookie, the
agent Logout Callback URL is called in parallel. The agents accessed in a session
and agents from multiple domains are all called in parallel, depending on the
number of concurrent connections supported in the browser.
21.1.2 About Application SSO and Access Manager
Access Manager enables Administrators to create a web of trust in which a user's
credentials are verified once and are provided to each application the user runs. Using
Multiple WebLogic Server
Domain SSO
The basic administration unit for WebLogic Server instances is known
as a domain. You can define multiple WebLogic administration
domains based on different system Administrators' responsibilities,
application boundaries, or the geographical locations of WebLogic
servers. However, all Managed Servers in a cluster must reside in the
same WebLogic Server domain.
See Also: "About Multiple WebLogic Server Domain SSO" on
page 21-5
Reverse-Proxy SSO This SSO implementation type is supported with a few configuration
differences.
See Also: "About Reverse-Proxy SSO" on page 21-5
SSO with Mixed Release Agents Access Manager seamlessly supports registered 11g and 10g OAM
gents (Webgates and programmatic access clients), as well as legacy
OSSO Agents (mod_osso 10g), and legacy OpenSSO agents). These can
be used in any combination.
Note: Access Manager provides a proprietary multiple network
domain SSO capability that predates Identity Federation 11.1.1. If this
is implemented in your Oracle Access Manager 10g deployment, you
can register 10g Agents with Access Manager 11g to continue this
support.
See Also:
■"Configuring Centralized Logout for 11g WebGates" on page 27-4
■Oracle Fusion Middleware Administrator's Guide for Oracle Identity
Federation, 11.1.1
Table 21–2 (Cont.) Introduction to SSO Implementations
SSO Type Description
Introducing Access Manager Single Sign-On
Understanding Single Sign-On with Access Manager 21-5
these credentials, the application does not need to re-authenticate the user with its
own mechanism.
Application single sign-on allows users who have been authenticated by Access
Manager to access applications without being re-authenticated.
There are two ways to send a user's credentials:
■Using Cookies: A specific value is set on the browser's cookie that the application
must extract to identify a user.
■Using Header Variables: An HTTP header set on the request by the agent and
visible to the application.
Header response values are inserted into a request by an OAM Agent, and can only be
applied on Web servers that are protected by an agent. registered with Access Manager
11g If the policy includes a redirect URL that is hosted by a Web server not protected
by Access Manager, header responses are not applied.
For example, when a user authenticates, she might be redirected to a portal index
page:
http://example.com/authnsuccess.htm
For authentication failure, an authentication action might redirect the user to an error
page or a self-registration script:
http://example.com/authnfail.htm
21.1.3 About Multiple WebLogic Server Domain SSO
Access Manager supports SSO in multiple WebLogic administration domains.
You can define multiple WebLogic administration domains based on different system
Administrators' responsibilities, application boundaries, or the geographical locations
of WebLogic servers. Conversely, you can use a single domain to centralize all
WebLogic Server administration activities.
There are two basic types of WebLogic administration domains:
■Domain with Managed Servers: A simple production environment can consist of
a domain with several Managed Servers that host applications, and an
Administration Server to perform management operations. In this configuration,
applications and resources are deployed to individual Managed Servers; similarly,
clients that access the application connect to an individual Managed Server.
Note: Both forms require Administrators to enter the appropriate
responses within the policy. For more information, see "Introduction
to Policy Responses for SSO" on page 25-68.
Note: All Managed Servers in a cluster must reside in the same
domain; you cannot split a cluster over multiple domains. All
Managed Servers in a domain must run the same version of the Oracle
WebLogic Server software. The Administration Server can run either
the same version as the Managed Servers in the domain, or a later
service pack.
Introducing Access Manager Single Sign-On
21-6 Administrator's Guide for Oracle Access Management
Production environments that require increased application performance,
throughput, or availability may configure two or more of Managed Servers as a
cluster. Clustering allows multiple Managed Servers to operate as a single unit to
host applications and resources. For more information about the difference
between a standalone and clustered Managed Servers, see Managed Servers and
Clustered Managed Servers.
■Standalone WebLogic Server Domain: For development or test environments,
you may want to deploy a single application and server independently from
servers in a production domain. In this case, you can deploy a simple domain
consisting of a single server instance that acts as an Administration Server and
also hosts the applications you are developing. The examples domain that you can
install with WebLogic Server is an example of a standalone WebLogic Server
domain.
All Managed Servers in a cluster must reside in the same domain; you cannot split a
cluster over multiple domains. All Managed Servers in a domain must run the same
version of the Oracle WebLogic Server software. The Administration Server can run
either the same version as the Managed Servers in the domain, or a later service pack.
Each domain's configuration is stored in a separate configuration file (config.xml),
which is stored on the Administration Server along with other files such as logs and
security files. When you use the Administration Server to perform a configuration
task, the changes you make apply only to the domain managed by that Administration
Server. To manage another domain, use the Administration Server for that domain. For
this reason, the servers instances, applications, and resources in one domain should be
treated as being independent of servers, applications, and resources in a different
domain.You cannot perform configuration or deployment tasks in multiple domains at
the same time.
Each domain requires its own Administration Server for performing management
activities. When you use the Oracle Access Management Console to perform
management and monitoring tasks, you can switch back and forth between domains,
but in doing so, you are connecting to different Administration Servers.
If you have created multiple domains, each domain must reference its own database
schema. You cannot share a configured resource or subsystem between domains. For
example, if you create a JDBC data source in one domain, you cannot use it with a
Managed Server or cluster in another domain. Instead, you must create a similar data
source in the second domain. Furthermore, two or more system resources cannot have
the same name.
21.1.4 About Reverse-Proxy SSO
This is a supported configuration with the following caveats.
Caveats
If you are going to use a reverse proxy in a single sign-on configuration, be sure to
perform one of the following tasks. Otherwise, the reverse proxy hides the client's IP
address:
■Either to set the
IPvalidation
parameter to
false
■Or add the proxy IP address to the
IPValidationExceptions
list in the Webgate
registration
In some situations the Reverse Proxy does not pass the 10g Webgate ObSSOCookie to
Oracle WebLogic after a successful authentication. To avoid this issue:
Understanding the Access Manager Policy Model
Understanding Single Sign-On with Access Manager 21-7
■Use Form authentication instead of Basic Over LDAP when using Reverse Proxy
with Oracle WebLogic
■For 11g Webgate, a user-defined parameter (
filterOAMAuthnCookie
(default
true
))
can be used to prevent the OAMAuthnCookie from being passed to downstream
applications for security consideration. If you do want to pass the cookie on, then
set the
filterOAMAuthnCookie
parameter to
false
.
21.2 Understanding the Access Manager Policy Model
Access Manager distills the policy models of Oracle Access Manager and OSSO into a
single Access Manager policy model. Figure 21–1 illustrates the main elements of the
Access Manager 11g policy model including the shared policy components, an
individual Application Domain, and external dependencies.
Figure 21–1 Access Manager 11g Policy Model
Shared Policy Components
Shared policy components are global and can be used in one or more Application
Domains. Figure 21–2 illustrates the shared components for Access Manager policies.
Figure 21–2 Access Manager Shared Policy Components
Table 21–3 describes the global, shared components in an Access Manager policy.
Access Manager
Authentication
Schemes
Authentication
Modules
Application
Domains
Resource
Types
Host
Identifiers
PoliciesResources
Token Issuance
Policies
Authorization
Policies
Authentication
Policies
IdentitiesContextual Data
Legend
External Dependencies
Relationship: Containment
Relationship: One-to-Many
Relationship: Many-to-Many
Access Manager
Resource
Types
Host
Identifiers
Authentication
Schemes
Authentication
Modules
Understanding the Access Manager Policy Model
21-8 Administrator's Guide for Oracle Access Management
Table 21–3 Access Manager Global, Shared Policy Components
Component Description
Resource Types Defines the type of resource to be protected and the associated
operations. The default resource type is HTTP. However,
Administrators can define non-HTTP resource types that can be
applied to specific resources in an Application Domain.
Any number of resources can belong to a specific resource type.
However, each resource that is added to a policy must be defined as a
single type:
■HTTP
■wl_authen
■TokenServiceRP
See Also:
■Chapter 22: Managing Resource Types
■Chapter 45: Managing TokenServiceRP Type Resources
Host Identifiers A host can be known by multiple names. To ensure that OAM
recognizes the URL for a resource, OAM must know the various ways
used to refer to that resource's host computer.
With Access Manager, all possible host variations are stored together.
Administrators enter the canonical name for the host and every other
name by which the host can be addressed by users. A request sent to
any address on the list is mapped to the official host name.
Authentication and authorization policies in an Application Domain
protect resources based on host identifiers. Host identifiers are used to
identify resources or an application at run time and can be used to
formulate policies for application resources at design time.
Host identifiers can be generated automatically during Agent
registration and are used to seed the Resource definition and default
authentication and authorization policies in the new Application
Domain.
Alternatively: Administrators can create a host identifier definition for
use in one or more Application Domains.
Virtual Web Hosting: Enables support of multiple domain names and
IP addresses that each resolve to their unique subdirectories on a
single server. The same host can have multiple sites being served
either based on multiple NIC cards (IP based) or multiple names (for
example, abc.com and def.com) resolving to same IP.
See Also: "About Host Identifiers" on page 22-8.
Authentication Scheme A named component that defines the challenge mechanism, level of
trust, and the underlying authentication module or plug-in required to
authenticate a user. Several default schemes provided with Access
Manager and Administrators can define their own schemes.
Authenticating a user's identity with Access Manager refers to running
a pre-defined set of processes to verify the digital identity of the user.
One authentication scheme can be assigned to multiple authentication
policies. However, each authentication policy can have only one
authentication scheme assigned to it.
Note: Authentication schemes are defined globally to ensure that a
small number of Administrators define them in a consistent, secure
way.
See Also: "Managing Authentication Schemes" on page 22-64
Understanding the Access Manager Policy Model
Understanding Single Sign-On with Access Manager 21-9
Access Manager Policy Components
Access Manager default behavior denies access when a resource is not protected by a
policy that explicitly allows access. Table 21–4 describes policy components you
configure to allow access and where you can find the details.
Authentication Modules and
Plug-ins
The smallest executable unit of an authentication scheme. The
authentication module determines the exact procedure to be followed
and the method for challenging the user for credentials.
Authentication involves determining which credentials a user must
supply when requesting access to a resource, gathering credentials,
and returning a response that is based on the results of credential
validation.
All authentication processing relies on an authentication module to
define the rules governing requirements and transmission of
information to the backend authentication scheme. All information
collected by the plug-in and saved in the context is available to the
plug-in through the authentication process. Context data can also be
used to set cookies or headers in the user's login page
A number of plug-ins and several pre-defined modules are provided.
Oracle strongly recommends using plug-ins, which you can configure
and orchestrate as needed to provide multi-step authentication.
See Also:
■"Managing Native Authentication Modules" on page 22-23
■"Orchestrating Multi-Step Authentication with Plug-in Based
Modules" on page 22-29
See Also: "Anatomy of an Application Domain and Policies" on
page 21-10
Table 21–4 Access Manager Policy Components
Component Description
Application Domain Each Application Domain provides a logical container for resources, and the associated
policies that dictate who can access these resources. An application domain can be
created automatically during Agent registration or manually using the console.
See Also: "Anatomy of an Application Domain and Policies" on page 21-10
Resource Definitions Based on a defined host identifier, Administrators can add specific resources to an
Application Domain and apply policies to protect those resources.
See Also: "Adding and Managing Policy Resource Definitions" on page 25-13.
Authentication Policy Each resource defined in an Application Domain can be protected by only one
authentication policy. Each authentication policy requires one authentication scheme.
One authentication policy can protect many resources. However, each resource can be
protected by only one authentication policy.
See Also: "Defining Authentication Policies for Specific Resources" on page 25-31
Authorization Policies Each resource assigned to an Application Domain can be protected by only one
authorization policy. Each policy can include one or more conditions and a rule.
Authorization policies can also contain success responses.
One authorization policy can protect many resources. However, each resource can be
protected by only one authorization policy.
See Also: "Defining Authorization Policies for Specific Resources" on page 25-35.
Token Issuance Policy By default, only a container for Token Issuance Policies is provided in a generated
Application Domain. No Conditions or Rules are generated automatically. You must add
these manually.
See Also: "Displaying Token Issuance Policy Pages" on page 25-10.
Table 21–3 (Cont.) Access Manager Global, Shared Policy Components
Component Description
Anatomy of an Application Domain and Policies
21-10 Administrator's Guide for Oracle Access Management
21.3 Anatomy of an Application Domain and Policies
Access Manager enables you to control who can access resources based on policies
defined within an Application Domain. Users attempt to access a protected resource
by entering a URL in a browser, by running an application, or by calling some other
external business logic. When a user requests access to a protected resource, the
request is evaluated according to policies that discriminate between authenticated
users who are authorized and those who are not authorized for access to a particular
resource.
Application domains do not have any hierarchical relationship to one another. Each
Application domain can be made to contain policy elements related to an entire
application deployment, a particular tier of the deployment, or a single host.
Within each Application Domain, specific resources are identified for protection by
specific policies that govern access. Authentication and authorization policies include
Administrator-configured responses that are applied upon successful evaluation.
Authorization policies include Administrator-configured conditions and rules that
define how evaluation is performed, and responses to be applied upon successful
evaluation.
The size and number of Application Domains is up to the Administrator. The decision
can be based on individual application resources or any other logical grouping as
needed. An Application Domain is automatically created during Agent registration.
Also, Administrators can protect multiple Application Domains using the same agent
by manually creating the Application Domain and adding the resources and policies.
Figure 21–3 shows an expanded view of policies within an Application Domain, as
well as how the shared elements are used in an Application Domain.
Policy Responses Available for all policy types, Authentication and Authorization success Responses can
be defined within respective policies to be applied after policy evaluation.
See Also: "Introduction to Policy Responses for SSO" on page 25-68.
Rule Available for only Authorization and Token Issuance Policies.
Each Authorization policy includes a rule that defines whether the policy allows or
denies access to resources protected by the policy.
The rule references Authorization conditions, described next.
See Also: "Introduction to Authorization Policy Rules and Conditions" on page 25-40.
Condition Available for only Authorization and Token Issuance Policies.
Each Authorization policy rule references conditions that define to whom the rule
applies, if there is a time Condition, and how evaluation outcomes are to be applied.
Conditions are declared outside of rules and are referenced within a rule.
See Also: "Introduction to Authorization Policy Rules and Conditions" on page 25-40.
Table 21–4 (Cont.) Access Manager Policy Components
Component Description
Anatomy of an Application Domain and Policies
Understanding Single Sign-On with Access Manager 21-11
Figure 21–3 Anatomy of Access Manager Policies
For more information, see the following topics:
■About Resource Definitions for Policies
■About Authentication Policies
■About Authorization Policies
■About Token Issuance Policies
21.3.1 About Resource Definitions for Policies
The term resource represents a document, or entity, or pieces of content stored on an
OAM Server and available for access by a large audience.
Clients communicate with the OAM Server to request a resource using a particular
protocol (HTTP or HTTPS, for example), which corresponds to an existing Resource
Type. Every HTTP Resource Type must be associated with a host identifier. However,
non-HTTP Resource Types are associated with a specific name (not a host identifier).
With Access Manager, each resource must be defined as within the Resources
container in an Application Domain before it can be associated with a specific policy.
For more information, see "Adding and Managing Policy Resource Definitions" on
page 25-13.
21.3.2 About Authentication Policies
Administrators can create an authentication policy to apply to specific resources
within an Application Domain. Each authentication policy:
■Identifies the specific resources covered by this policy, which must be defined on
the Resources tab of this policy and in the Resources container for the Application
Domain
■Specifies the authentication scheme that provides the challenge method to be used
to authenticate the user
■Specifies the Success URL (and the failure URL) that redirects the user based on
the results of this policy evaluation
Note: Only resources defined in the Resources container can be
associated with policies in the Application Domain.
Note: To protect pieces of content on a page, Oracle recommends
using Oracle Entitlements Server.
Anatomy of an Application Domain and Policies
21-12 Administrator's Guide for Oracle Access Management
■Defines optional Responses that identify post-authentication actions to be carried
out by the Agent.
Policy responses provide the ability to insert information into a session and pull it
back out at any later point. This is more robust and flexible than Oracle Access
Manager 10g, which provided data passage to (and between) applications by
redirecting to URLs in a specific sequence.
Policy responses are optional. These must be configured by an Administrator and
are applied to specific resources defined within the Application Domain. For more
information, see "Introduction to Policy Responses for SSO" on page 25-68.
Authentication Policy Evaluation Results
To authenticate a user, Access Manager presents the user's browser with a request for
authentication credentials based on the challenge method defined by the
authentication scheme for this policy.
After policy evaluation, the result is returned and the user is redirected based on that
result:
■Success (allow access) redirects to the requested URL
■Failure, (deny access) redirects to a generic error page
21.3.3 About Authorization Policies
Authorization is the process of determining if a user has a right to access a requested
resource. A user might want to see data or run an application program protected by a
policy, for example.
Administrators can create an authorization policy to specify the conditions under
which a subject or identity has access to a particular resource. The requested resource
must belong to an Application Domain and must be included within a specific
authorization policy.
Each authorization policy:
■Identifies the specific resources covered by this policy, which must be defined on
the Resources tab of this policy and in the Resources container for the Application
Domain
■Specifies the Success URL (and the failure URL) that redirects the user based on
the results of this policy evaluation
■Identifies specific Allow or Deny Rules based on defined conditions for this policy
and resources. See Table 21–5 for an overview of Condition types.
Note: Policy evaluation results can be overridden policy by policy.
See Also:
■"Displaying Authentication Policy Pages" on page 25-7
■"Managing Run Time Policy Evaluation Caches" on page 13-9
Note: OracleAS SSO 10g does not provide authorization; OSSO
Agents do not use Access Manager 11g Authorization Policies.
Introduction to Policy Conditions and Rules
Understanding Single Sign-On with Access Manager 21-13
■Defines optional Responses that identify post-authorization actions to be carried
out by the Agent, as described in "Introduction to Policy Responses for SSO" on
page 25-68.
21.3.4 About Token Issuance Policies
A Token Issuance Policy defines the rules under which a token can be issued for a
resource (Relying Party Partner) based on the client's identity. The client can be either a
Requester Partner or an end user.
Unless explicitly stated, information on Application Domains and authorization
policies applies equally to Token Issuance policies.
For specific information about Token Issuance Policies, see:
■"Managing TokenServiceRP Type Resources" on page 45-30
■"Managing Token Issuance Policies, Conditions, and Rules" on page 45-27
21.4 Introduction to Policy Conditions and Rules
Unless explicitly stated, information on policy Conditions and Rules applies equally
to:
■Authorization policies
■Token Issuance policies
Conditions
Conditions can be specified only within Authorization and Token Issuance policies.
Conditions are used in conjunction with Rules that specify Allow or Deny access,
based on defined Conditions. Table 21–5 identifies available condition types.
Each Authorization and Token Issuance policy can contain one or more condition
objects. There can be more than one instance of a type of condition in a policy (the
previous policy model allowed only one instance of a class in a policy).
See Also: "Introduction to Policy Conditions and Rules"
Note: During automatic policy generation, no Token Issuance
Policies are created; only the container for Token Issuance Policies is
generated automatically.
Table 21–5 Condition Types
Type For more information, see ...
Identity "Introduction to Authorization Policy Rules and Conditions" on page 25-40.
IP4 Range "Defining IP4 Range Conditions" on page 25-51.
Temporal "Defining Temporal Conditions" on page 25-54.
Attribute "Defining Attribute Conditions" on page 25-55.
True Effectively "Allow All". Oracle recommends this be used as the default option in
cases where you need to let in any authenticated use. In this case, you do not
need any particular conditions to be satisfied at authorization time.
This replaces the Use Implied Constraints flag the previous release of Access
Manager, which similarly lets policy evaluation complete with an Allow result
when no specifically-defined constraints were present.
Understanding SSO Cookies
21-14 Administrator's Guide for Oracle Access Management
Conditions are similar to earlier Access Manager 11g authorization constraints.
However, constraints included Allow or Deny specifications and conditions do not.
Rules
Rules are new constructs in the policy model. Each Rule defines the Allow or Deny
specification that determines the overall effect of the policy. Rules also define how the
outcomes of each Condition evaluation is to be combined. Conditions are referenced in
rules and declared outside of rules.
Within a Rule, evaluation outcomes can be combined as follows:
■Simple Mode: Accepts a list of condition names that are combined based on the
value of a combiner that allows either All conditions to be met or Any one
condition to be met to return "true" for the evaluation. [Previously, ALL allowed
constraints while ANY denied them.]
■Expression mode: Allows the user to specify a Boolean expression to combine
conditions using condition names and special characters (comma, vertical bar,
ampersand and exclamation point: , |& and !.
For more information about Conditions and Rule, see Chapter 25.
21.5 Understanding SSO Cookies
This section provides a brief overview of single sign-on with Access Manager 11g. It
includes the following topics:
■About Single Sign-On Cookies During User Login
■About Single Sign-On Server and Agent Cookies
21.5.1 About Single Sign-On Cookies During User Login
Table 21–6 describes the cookies that can be set or cleared during user login.
Note: A policy in which there are one or more conditions that are not
part of either an Allow or Deny Rule is treated as a valid policy.
Table 21–6 SSO Cookies
SSO Cookie Set at
User Login Set By Description
OAM_ID cookie OAM Server
Embedded
Credential
Collector
When a user attempts to access a protected application, the request
comes to the SSO Engine and the controller checks for the existence
of the cookie.
See Also: "OAM_ID cookie" on page 21-16.
OAMAuthnCookie 11g Webgate Set by each 11g Webgate that is contacted. Protected by the key
known to the respective 11g Webgate and the OAM Server. A valid
OAMAuthnCookie is required for a session.
Note: If the user accesses applications protected by different 11g
Webgates, you will have multiple OAMAuthnCookies.
See "OAMAuthnCookie for 11g OAM Webgates" on page 21-16.
Understanding SSO Cookies
Understanding Single Sign-On with Access Manager 21-15
For details about configuring authentication and authorization policies, see
Chapter 25, "Managing Policies to Protect Resources and Enable SSO".
21.5.2 About Single Sign-On Server and Agent Cookies
■OAM_ID cookie
■OAMAuthnCookie for 11g OAM Webgates
■ObSSOCookie for 10g Webgates
ObSSOCookie 10g Webgate A domain-based cookie for 10g Webgates is set only when a 10g
Webgate is contacted. Protected with keys known to the OAM
Server only. One global shared secret key for all Webgates.
Note: This cookie enables backward compatibility and
inter-operability between Access Manager 11g and older agents.
See "ObSSOCookie for 10g Webgates" on page 21-17
OAM_REQ OAM Server
Embedded
Credential
Collector
A transient cookie that is set or cleared by the OAM Server if the
Authentication request context cookie is enabled. Protected with
keys known to the OAM Server only.
Note: This cookie is configured as a high availability option to store
the state about user's original request to a protected resource while
his credentials are collected and authentication performed.
See "OAM_REQ Cookie" on page 21-17.
OAMRequestContext 11g Webgate Set or cleared by the 11g Webgate and protected by the key known
to the respective 11g Webgate and the OAM Server.
With Internet Explorer browser:
--When RequestContextCookieExpTime is not set,
OAMRequestContext is a transient cookie.
--When RequestContextCookieExpTime is set, the
OAMRequestContext cookie expires by the time set using the
"
Expires
" directive. This requires a time sync between the client
host and Web server host.
With all other (non-IE) browsers, when
RequestContextCookieExpTime is not set OAMRequestContext
expires in 5 minutes by default or by the time set using the
"
Max-Age
" directive.
See Also: "OAMRequestContext" on page 21-17
Table 15–2, " User-Defined WebGate Parameters"
DCCCtxCookie Detached
Credential
Collector
For detached credential collector (DCC)--similar to OAM_REQ
created by embedded credential collector (ECC).
See "DCCCtxCookie" on page 21-18
OHS-host-port Oracle HTTP
Server
Set only when OSSO Agents (mod_osso) are contacted on Oracle
HTTP Server (OHS). Protected with the key known to the
respective mod_osso agent and the OAM Server.
Note: This cookie enables backward compatibility and
inter-operability between Access Manager 11g and older agents.
See "mod_osso Cookies" on page 21-18.
OAM_GITO cookie OAM Server Provides backward compatibility and inter-operability between
OSSO 10g and Access Manager 11g. The cookie is created by the
OAM Server and accessed or modified by the OAM Server or mod_
osso agent.
See "mod_osso Cookies" on page 21-18.
OpenSSO cookie OpenSSO
Proxy
See "OpenSSO Cookie (iPlanetDirectoryPro)" on page 21-19.
Table 21–6 (Cont.) SSO Cookies
SSO Cookie Set at
User Login Set By Description
Understanding SSO Cookies
21-16 Administrator's Guide for Oracle Access Management
■OAM_REQ Cookie
■OAMRequestContext
■DCCCtxCookie
■mod_osso Cookies
■OpenSSO Cookie (iPlanetDirectoryPro)
21.5.2.1 OAM_ID cookie
This cookie is scoped to the OAM Server. OAM_ID is generated by the OAM Server
when the user is challenged for credentials, and submitted to the server on every
redirect to the server.
OAM_ID is protected by keys known to the OAM Server only.
When a user attempts to access a protected application, the request comes to the SSO
Engine and the controller checks for the existence of the cookie:
■If the cookie does not exist, user authentication begins. After successful
authentication, the user context and token are set by the SSO Engine. The cookie is
set with the global user ID (GUID), creation time, and idle timeout details.
Information in the cookie is encrypted with the SSO Server key and can be
decrypted only by the SSO Engine.
■If the cookie exists, then the cookie is decrypted and the sign in flow completes
with the authenticated user.
21.5.2.2 OAMAuthnCookie for 11g OAM Webgates
There is one OAMAuthnCookie_<host:port>_<random number> set by each 11g
Webgate using the authentication token received from the OAM Server after successful
authentication. A valid OAMAuthnCookie is required for a session.
SSL Connections: Administrators can ensure the ObSSOCookie is only sent over an
SSL connection and prevents the cookie from being sent back to a non-secure Web
server by configuring SSL and then specifying Simple or Cert mode for Agents and
Servers. For details, see "About Communication Between OAM Servers and
WebGates" on page 6-4.
Cookie Expiration: For 11g Webgate and OAMAuthnCookie, expiration is controlled
by the "tokenValidityPeriod" parameter, which controls the valid token (or cookie)
time.
This key is known to both the 11g Webgate and SSO Engine and is used for encrypting
OAMAuthnCookie. The SSO engine key (only known to the SSO Engine) is used for
encrypting the OAM_ID OAM Server cookie.
Similar to ObSSOCookie for 10g Webgates.
21.5.2.3 ObSSOCookie for 10g Webgates
Access Manager 11g sets a key-based cookie ObSSOCookie for each user or application
that accesses a resource protected by a 10g Webgate. The key is set up during agent
registration and is known to both the agent and SSO Engine (shared between them).
This key is different from the OAM Server (or SSO Engine) key.
Removing the ObSSOcookie causes the 10g Webgate to log the user out and requires
the user to re-authenticate the next time he or she requests a resource that is protected
by the Access System.
Understanding SSO Cookies
Understanding Single Sign-On with Access Manager 21-17
The WebGate sends the ObSSOCookie to the user's browser upon successful
authentication. This cookie can then act as an authentication mechanism for other
protected resources that require the same or a lower level of authentication. When the
user requests access to a browser or another resource, the request flows to the OAM
Server. The user is logged in, and the ObSSOCookie is set. The OAM Server generates
a session token with a URL that contains the ObSSOCookie. Single sign-on works
when the cookie is used for subsequent authorizations in lieu of prompting the user to
supply authorization credentials.
When the cookie is generated, part of the cookie is used as an encrypted session token.
The single sign-on cookie does not contain user credentials such as user name and
password.
SSL Connections: Administrators can ensure the ObSSOCookie is only sent over an
SSL connection and prevents the cookie from being sent back to a non-secure Web
server by configuring SSL and then specifying Simple or Cert mode for Agents and
Servers. For details, see "About Communication Between OAM Servers and
WebGates" on page 6-4.
Cookie Expiration: Administrators can specify the desired Cookie Session Time in the
OAM Agent registration. For more information, see "Registering an OAM Agent Using
the Console" on page 15-13.
21.5.2.4 OAM_REQ Cookie
A transient cookie that is set or cleared by the OAM Server if the Authentication
request context cookie is enabled. Protected with keys known to the OAM Server only.
This cookie is configured as a high availability option to store the state about user's
original request to a protected resource while his credentials are collected and
authentication performed.
In high availability configurations, the Request Cache type must be changed from
BASIC to COOKIE using Infrastructure Security custom WLST commands.
21.5.2.5 OAMRequestContext
This cookie is set or cleared by the 11g Resource WebGate and protected by the key
known to the respective 11g WebGate and the OAM Server.
This cookie is configured to store the state about the user's original request to a
protected resource while his credentials are collected and authentication performed.
■With Internet Explorer browser:
–When RequestContextCookieExpTime is not set, OAMRequestContext is a
transient cookie.
Note: You must invoke the WLST script from the Oracle Common
home. See "Using Custom WLST Commands" in the Oracle Fusion
Middleware Administrator's Guide.
See Also:
■Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference
■Table 21–6, " SSO Cookies"
Understanding SSO Cookies
21-18 Administrator's Guide for Oracle Access Management
–When RequestContextCookieExpTime is set, the OAMRequestContext cookie
expires by the time set using the "
Expires
" directive. This requires a time sync
between the client host and Web server host.
■With all other (non-IE) browsers, when RequestContextCookieExpTime is not set
OAMRequestContext expires in 5 minutes by default or by the time set using the
"
Max-Age
" directive.
21.5.2.6 DCCCtxCookie
This comes into play only with the Detached Credential Collector (DCC).
The DCCCtxCookie is used by DCC to save various context information required
during authentication. It includes information necessary to reconstruct the original
request upon completion of authentication, to maintain server affinity, and to perform
iterative multi-step authentication.
By default, DCCCtxCookie is set when the DCC is first redirected away to collect
credentials based on the authentication scheme (when the browser is first redirected to
the login form with a form-based authentication scheme).
With the DCC, once authenticated the OAM server issues a DCC master session token
to the DCC in the authenticate response. DCC then sets a host- based DCC cookie
using the token and:
■If DCC cookie Presented During Authentication: DCC decrypts the token using
a DCC key, and performs partial token validation locally (integrity check, token
validity period check). If it passes, DCC performs complete token validation for
timeout aspects over the OAP channel against the OAM Server.
■If no DCC Cookie: This indicates a first time authentication which initiates
credential collection, performs sanity and syntactic checks on the credential and
submits to OAM Server for validation.
21.5.2.7 mod_osso Cookies
The mod_osso module is the Oracle HTTP Server module that provides authentication
to OracleAS applications. This module resides on the Oracle HTTP Server that enables
applications protected by OracleAS Single Sign-On to accept HTTP headers in lieu of a
user name and password once the user has logged into the OracleAS Single Sign-On
server. The values for these headers are stored in a mod_osso cookie.
Located on the application server, mod_osso simplifies the authentication process by
serving as the sole application to the single sign-on server. In this way, mod_osso
renders authentication transparent to OracleAS applications. The Administrator for
these applications is spared the burden of integrating them with an SDK. After
authenticating a user, mod_osso transmits the simple header values that applications
may use to authorize the user.
OAM_GITO Cookie
Needed in special cases to support timeout when multiple types of agents (mod_osso
and WebGate) are working with Access Manager 11g. Server side session managers
can check the validity of the cookie for expiry and timeout during session validation.
See Also: RequestContextCookieExpTime in Table 15–2,
" User-Defined WebGate Parameters"
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"
Understanding SSO Cookies
Understanding Single Sign-On with Access Manager 21-19
Global logout is required for OSSO Agents (mod_osso) to ensure that logging out of a
session on any entity propagates the logout to all entities.
When a user is authenticated by OSSO 10g, the OSSO Server sets the OAM_GITO
cookie. Once the partner cookie (OHS cookie) is set, OHS does not route the request to
the server. Instead, on every access, OHS decrypts the OAM_GITO cookie and updates
the last activity timestamp. During request processing, if any partner detects that
current time has surpassed GITO timeout (last activity time + GITO timeout), the
request is sent to OSSO 10g in forced authentication mode. When a request reaches
OSSO server in forced authentication mode, server chooses to ignore SSO_ID cookie
and challenges user for credentials, considering it as a fresh request. After successful
authentication, SSO_ID and OAM_GITO cookie are updated.
This is enabled (using the
editGITOValues
WLST command), as described in the
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
OssoSecureCookies Directive
Add the OssoSecureCookies directive to set the Secure flag on all cookies. This tells the
browser to only transmit those cookies on connections secured by HTTPS. An example
of this directive in a mod_osso configuration (mod_osso.conf), is as follows:
<IfModule mod_osso.c>
OssoIpCheck off
OssoIdleTimeout off
OssoSecureCookies on
OssoConfigFile osso/osso.conf
<Location /j2ee/webapp>
require valid-user
AuthType Basic
</Location>
</IfModule>
For more information, see Oracle Application Server Single Sign-On Administrator's
Guide.
21.5.2.8 OpenSSO Cookie (iPlanetDirectoryPro)
The agent finds this cookie after the OpenSSO Proxy triggers session validation. The
default name of the OpenSSO cookie is:
iPlanetDirectoryPro
After the OpenSSO agent is authenticated and logged in, the agent verifies whether
the user has an OpenSSO cookie. If not, the user authentication request is initiated
from the OpenSSO Agent. During SSO User Login and Authentication flow OpenSSO
cookie is created, which contains the OpenSSO session identifier, and this cookie is set
in the user's browser.
During End User Session Validation, OpenSSO agent intercepts the request to the
protected application and finds an OpenSSO cookie.
During User Single Logout, the OpenSSO Proxy receives a User logout request and
forwards the user to the OAM Logout URL OpenSSO Proxy decrypts the OpenSSO
cookie, fetches the OpenSSO session identifier and, from that, fetches the OAM session
ID. OpenSSO proxy sends the logout request to controller through the OpenSSO
logout event with the OAM session ID.
■SSO User Login and Authentication flow
■End User Session Validation flow
Introduction to Configuration Tasks for Single Sign-On
21-20 Administrator's Guide for Oracle Access Management
■User Single Logout flow
21.6 Introduction to Configuration Tasks for Single Sign-On
The following overview outlines the tasks that Administrators must perform to
configure single sign-on with Access Manager 11g,. For each task, a link to additional
information is included.
Task overview: Configuring single sign-on
1. Review all topics in this chapter to get familiar with the Access Manager 11g SSO
policy model.
2. Configure a single sign-on logout URL for each application you want to protect,
using documentation for your specific application.
3. Install and register an Agent on each Web server that is hosting an application to
protect using either method. See:
■Chapter 14, "Introduction to Agents and Registration"
■Chapter 15, "Registering and Managing OAM 11g Agents"
4. Proceed to manage resource types, host identifiers, authentication schemes, and
modules:
■Chapter 22, "Managing Authentication and Shared Policy Components"
5. Locate an existing Application Domain (or start a fresh one) and add resources
and policies, as described in:
■Chapter 25, "Managing Policies to Protect Resources and Enable SSO"
22
Managing Authentication and Shared Policy Components 22-1
22
Managing Authentication and Shared Policy
Components
This chapter describes how Administrators can manage shared policy components in
the following topics:
■Prerequisites
■Understanding Authentication and Shared Policy Component Tasks
■Managing Resource Types
■Managing Host Identifiers
■Understanding Authentication Methods and Credential Collectors
■Managing Native Authentication Modules
■Orchestrating Multi-Step Authentication with Plug-in Based Modules
■Deploying and Managing Individual Plug-ins for Authentication
■Managing Authentication Schemes
■Extending Authentication Schemes with Advanced Rules
■Configuring Challenge Parameters for Encrypted Cookies
■Configuring Authentication POST Data Handling
■Long URL Handling During Authentication
■Using Application Initiated Authentication
22.1 Prerequisites
Oracle recommends that you review information in Chapter 21, "Understanding Single
Sign-On with Access Manager" before performing activities in this chapter.
Additionally, the Oracle Access Management Console and at least one OAM Server
must be installed and running within a WebLogic Server domain, and Access Manager
must be running with at least two registered Agents.
22.2 Understanding Authentication and Shared Policy Component Tasks
This section introduces the tasks that must be performed to configure shared policy
components required for use in Access Manager authentication policies that protect
resources and enable single sign-on.
Managing Resource Types
22-2 Administrator's Guide for Oracle Access Management
Task overview: Configuring shared policy components
1. Confirm that the desired resource type is defined, as described in this chapter:
■Managing Resource Types
2. Confirm that a host identifier definition named for the agent was created during
agent registration, (or create one yourself), as described in:
■Managing Host Identifiers
3. Gain comprehension about credential collection with Access Manager:
■Understanding Authentication Methods and Credential Collectors
4. Learn about and use the authentication plug-ins that enable multi-step
authentication:
■Orchestrating Multi-Step Authentication with Plug-in Based Modules
■Deploying and Managing Individual Plug-ins for Authentication
5. Create and manage authentication schemes that you can add to authentication
policies, as described in:
■Managing Authentication Schemes
■Configuring Challenge Parameters for Encrypted Cookies
6. Set up your own global password policy for either the default embedded or
optional detached credential collector (unless specified, tasks apply to both ECC
and DCC, with minor changes noted in the discussion):
■Configuring Password Policy
■Managing Global Password Policy
■Configuring Password Policy Authentication
■DCC: Configuring 11g WebGates and Authentication Policy for DCC
■Completing Password Policy Configuration
7. Proceed to Chapter 25 to set up authentication policies.
22.3 Managing Resource Types
This section includes the following topics:
■About Resource Types and Their Use
■About the Resource Type Page
■Searching for a Specific Resource Type
■Creating a Custom Resource Type
22.3.1 About Resource Types and Their Use
When adding a resource to an Application Domain, Administrators must choose from
a list of defined Resource Types. Oracle-provided resource types include:
■HTTP
See Also: Chapter 21, "Understanding Single Sign-On with Access
Manager"
Managing Resource Types
Managing Authentication and Shared Policy Components 22-3
■wl_authen
■TokenServiceRP
Administrators can configure additional resource types, and define operations on both
Oracle-provided and custom resource types. A particular resource can be defined to
use a subset of the declared operations, or all of them (which includes any new
operators defined on the resource's type subsequently.
Administrators cannot remove custom resource types or operations for which
resources have been created. Oracle-provided resource types and operations are
marked as read-only within the policy store and cannot be removed.
Table 22–1 compares resource types and operations.
Note: Changes to the operation list of a resource type is not allowed
if a resource of that type exists.
Table 22–1 Comparison: Resource Types for Access Manager versus 10g
Access Manager 11g Oracle Access Manager 10g
HTTP: The default resource type used with HTTP and HTTPS protocols.
When adding an HTTP type resource to an Application Domain, Administrators
must choose from a list of existing host identifiers and add the resource URL.
This resource type is read-only. Default operations associated with the HTTP
resource type need not be defined by an Administrator. Instead, policies
developed and applied to the resource apply to all operations:
Operations: Oracle-provided resource types are read-only; associated operations
are pre-defined. Policies developed and applied to HTTP type resources apply to
all operations.
■Get
■Post
■Put
■Head
■Delete
■Trace
■Options
■Connect
■Other
See Also: "About the Resource Type Page" on page 22-4.
HTTP: The HTTP resource type is read-only.
Operations: Oracle-provided resource types
are read-only; associated operations are
pre-defined. Policies developed and applied
to the resource apply to all operations.
■Get
■Post
■Put
■Head
■Delete
■Trace
■Options
■Connect
■Other
wl_authen: Resources for representing WebLogic Authentication schemes is also
read-only (default operations cannot be modified or deleted.)
This non-HTTP resource type is available to use with resources deployed in a
WebLogic container in a domain that does not include Access Manager. The
protected resource is accessed through its URL on the Oracle WebLogic Server.
Type wl_authen resources, require a custom Access Client.
N/A
Managing Resource Types
22-4 Administrator's Guide for Oracle Access Management
22.3.2 About the Resource Type Page
In the Oracle Access Management Console, resource types are organized with other
Components under the Policy Configuration tab. The navigation tree shows
Oracle-provided resource types: HTTP, wl_authen, and TokenServiceRP.
The
HTTP
resource type, shown in Figure 22–1, is used for Web applications protected
by Access Manager and accessed using internet protocols (HTTP or HTTPS).
Figure 22–1 Default HTTP Resource Type Definition
TokenServiceRP: Resources for representing Token Service Relying Party. The
Operation for this resource type is Issue.
N/A
Custom Resource Types: Have no associated host identifier.
A custom "EJB" resource type can be created on demand for use in SSO
integrations.
EJB: A custom resource type used in SSO
integrations with WebLogic and WebSphere
for authenticating the user. During
authentication, the user's groups were
fetched and populated in the Subject
Principal as roles. Subsequent authorization
was executed inside the application server
based on user roles.
No authorization calls were made using
resource operations.
Non-HTTP resource types have no associated host identifier.
When adding non-HTTP resources to an Application Domain, Administrators
must enter the Type name into the Resource URL field as a pointer. The name
cannot match any host Identifier (and vice versa). This is not a relative HTTP
URL.
Note: Pre-defined resource types cannot be deleted. Pre-defined
operations are shown with a lock icon and cannot be deleted.
Additional operations can be created, edited, or deleted as needed.
Table 22–1 (Cont.) Comparison: Resource Types for Access Manager versus 10g
Access Manager 11g Oracle Access Manager 10g
Managing Resource Types
Managing Authentication and Shared Policy Components 22-5
The
wl_authen
resource type is shown in Figure 22–2. It is used for Fusion Middleware
applications that use one of the following Access Manager Identity Assertion Provider
configurations described in the Oracle Fusion Middleware Application Security Guide:
■Identity Asserter
■Identity Asserter with Oracle Web Services Manager
■Authenticator function
Figure 22–2 Default Resource Type wl_authen
The
TokenServiceRP
resource type represents the Token Service Relying Party, as
shown in Figure 22–3. The operation for this resource type is Issue. For more
information, see "Managing TokenServiceRP Type Resources" on page 45-30.
Figure 22–3 Default Resource Type TokenServiceRP Resource Type
Table 22–2 describes the elements in each resource type definition.
Table 22–2 Resource Type Definition
Element Description
Name Required. A unique name of up to 30 alpha or numeric characters.
Note: A non-HTTP Resource Type name cannot match a Host Identifier (and vice
versa).
Description Optional. Use this field to describe the purpose of this resource type using up to 200
alpha or numeric characters.
For example: Resources representing WebLogic Authentication schemes.
Managing Resource Types
22-6 Administrator's Guide for Oracle Access Management
Following topics describe how to create, modify, and delete a resource type.
22.3.3 Searching for a Specific Resource Type
Users with valid Administrator credentials can use the following procedure to locate a
defined resource type.
To search for a resource type
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Resource Types in the Access Manager
section.
3. In the Name field, enter the name of the Resource Type you want to find (with or
without a wild card (*)), and click Search. For example:
h*
Alternatively: Go to the desired Application Domain, open the Resources node to
display controls for that domain, choose a Resource Type from the list, and click
Search.
4. In the results table, you can:
■Edit or View: Click the Edit button in the tool bar to display the configuration
page.
Operations Optional. Policies that govern a particular resource apply to all specified operations
defined for the resource. Add (or remove) operations for this resource type as a
string and the operations will be available when you define a resource of this type
within an Application Domain. There is no limit to the number of operations that
can be added to the resource type.
■Get
■Post
■Put
■Head
■Issue (
TokenServiceRP
)
■Login (
wl_authen
)
■Delete
■Trace
■Options
■Connect
■Other (available with Oracle Access Manager 10 is not supported in 11g).
Remote Registration: During automatic policy creation, specified operations are
supported. During automatic policy creation with no operations specified, then All
operations defined for that type are supported.
Migration: During an upgrade to Access Manager 11.1.2 (from 10g or from 11.1.1.3
or from 11.1.1.5), resource definitions and HTTP default operations are handled
automatically. However, you must create any custom resource types to replace
10g-provided EJB custom resource types which are no longer provided by Oracle.
See
See Also: "About Resource Types and Their Use" on page 22-2 and "Defining
Resources in an Application Domain" on page 25-14.
See Also: "Conducting A Search"
Table 22–2 (Cont.) Resource Type Definition
Element Description
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-7
■Delete: Click the Delete button in the tool bar to remove the instance; confirm
removal in the Confirmation window.
■Detach: Click Detach in the tool bar to expand the table to a full page.
■Reorder Columns: Select a View menu item to alter the appearance of the
results table.
22.3.4 Creating a Custom Resource Type
Users with valid Administrator credentials can use the following procedure to create a
defined resource type. For instance, you can define a custom resource type that applies
to as few as one or two (or more) operations. Any defined custom resource type is
listed with default resource types when adding resources to an authentication or
authorization policy.
To create a custom resource type
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Resource Types in the Access Manager
section.
3. Click Create Resource type.
4. In the page that appears, enter the following information:
■Name: A unique name that identifies this resource type.
■Description: Optional.
■Operations: Click + in the Operations table, type the operation name into the
field provided. Repeat as needed to define all operations for this resource type.
■Reconfigure Table: Select a View menu item to alter the appearance of the
results table.
5. Click Apply to submit this custom resource definition.
6. Add this resource definition to an Application Domain as described in "Adding
and Managing Policy Resource Definitions" on page 25-13.
22.4 Managing Host Identifiers
This section describes host identifiers and their use as well as how to create, modify, or
remove a host identifier. Topics here include:
■About Host Identifiers
■About Virtual Web Hosting
■About the Host Identifier Page
■Creating a Host Identifier
■Searching for a Host Identifier Definition
■Viewing or Editing a Host Identifier Definition
See Also:
■"About Resource Types and Their Use" on page 22-2
■"Defining Resources in an Application Domain" on page 25-27
Managing Host Identifiers
22-8 Administrator's Guide for Oracle Access Management
■Deleting a Host Identifier Definition
22.4.1 About Host Identifiers
Access Manager policies protect resources on computer hosts. Within Access Manager,
the computer host is specified independently using a host identifier.
Table 22–3 illustrates the different host names under which a Web server might be
accessible to employees. Creating a single Host Identifier using all of these names
allows you to define a single set of policies to appropriately protect the application,
regardless of how the user accesses it.
Based on a defined host identifier, Administrators can add specific resources to an
Application Domain and apply policies to protect those resources.
Registered Agents protect all requests that match the addressing methods defined for
the host identifier used in a policy. A request sent to any address on the list is mapped
to the official host name and Access Manager can apply the policies that protect the
resource and OAM can apply the policies that protect the resource.
A host identifier is automatically created when an Agent (and application) are
registered using either the Oracle Access Management Console or the remote
registration tool. Administrators can manually add a host identifier if an application
and resources exist on a host that does not have a mapped host identifier. Also, Oracle
Access Management Administrators can modify an existing host identifier to add in
the new host name variations. For instance, adding another proxy Web server with a
different host name requires a new host name variation.
For more information, see:
■Host Identifier Usage
■Host Identifier Guidelines
■Host Identifier Variations
22.4.1.1 Host Identifier Usage
At design time, the host identifier can be used while defining which resources belong
to a specific Application Domain. Resources are scoped using their host identifier
(HTTP) or type (non-HTTP). This combination uniquely identifies them across Access
Manager.
Table 22–3 Host Identifiers Examples
Sample Host Identifier Description
hrportal.intranet.company.com A friendly name employees can remember. This is a load-balanced
proxy, and requests to this could actually utilize one of several servers
hosting the HR application.
hr-sf-02.intranet.company.com A single machine hosting the application, which can be accessed
directly.
hrportal.company.com The same application is also accessible externally to the corporate
firewall, primarily for use by ex-employees to check benefits, 401k
info, and so on. This is also a load-balanced reverse proxy.
Note: Each resource should be unique across all Application
Domains; each resource and host identifier combination must be
unique across all Application Domains.
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-9
Runtime Usage
At run time, Web server host information in the access query from an OAM Agent is
mapped to a host identifier and associated with the resource that is being accessed by
a user. The OAM Agent obtains the Web server host information in one of two ways:
■If the Preferred Host parameter is configured for virtual Web hosting support
(see"About Virtual Web Hosting" on page 22-10), Web server host information for
the given request is obtained from the Web server.
■If the Preferred Host parameter directly specifies the Web server host information,
it is always used irrespective of the Web server's own host information.
This allows for the Resources to be specified in terms of logical host names in their
Host Identifiers, instead of the host names matching the present deployment of the
Web server.
For instance, a user accessing
aseng-wiki
, would enter:
http://example-wiki.uk.example.com/wikiexample
Here, wikiexample is the resource URL and example-wiki.uk.example.com is the host.
Matching this host and port (port is 80) provides the host identifier.
Preferred Host
Web server host information is generally acquired by setting the Preferred Host string
of the OAM Agent. If the Agent is actively protecting multiple virtual hosts, this string
can be set to
server_name
to ensure that the actual request hostname is correctly
picked up from the Web server's request object. For more information, see "About
Virtual Web Hosting" on page 22-10
Authenticating Hosts and Challenge Redirect in Authentication Schemes
When a user attempts to access a protected resource URL, she is redirected to the
server specified in the Challenge Redirect field of the authentication scheme. If the
authentication challenge is to be processed by another host, the name of that host must
be defined to be available in the Host Identifiers list. For example, if a user is
redirected to an SSL-enabled server for authentication, that server must be defined as a
host identifier.
22.4.1.2 Host Identifier Guidelines
Each host identifier can be defined to represent one or more Web server hosts.
Following are several important guidelines for host identifiers:
■Each host name must be unique.
■Each host name:port pair must be unique.
■Each host name:port pair must belong to only one host identifier.
■Each host name:port pair must match the end user's entry exactly.
■A Host Identifier name cannot match a non-HTTP Resource Type name (and vice
versa).
■Each resource and host identifier combination must be unique across all
Application Domains.
Note: If you enter a host name in the Challenge Redirect field of an
authentication scheme, it must be defined as a Host Identifier.
Managing Host Identifiers
22-10 Administrator's Guide for Oracle Access Management
For more information, see "Host Identifier Variations".
22.4.1.3 Host Identifier Variations
Host identifiers are used to simplify the identification of a Web server host by defining
all possible hostname variations. Host identifiers consist of a list of all URL addressing
methods. A host identifier must be configured for each Web site or virtual Web site
that you want to protect with Access Manager.
You can identify Web server hosts to Access Manager in various ways, for example, by
providing a computer name or an IP address. The following are examples of how the
same host can be addressed:
■example.com
■example.com:80
■www.example.com
■www.example.com:80
■216.200.159.58
■216.200.159.58:80
22.4.2 About Virtual Web Hosting
You can install a Webgate on a Web server that contains multiple Web site and domain
names. The Webgate must reside in a location that enables it to protect all of the Web
sites on that server.
The virtual Web hosting feature of many Web servers enables you to support multiple
domain names and IP addresses that each resolve to their unique subdirectories on a
single virtual server. For example, you can host abc.com and def.com on the same
virtual server, each with its own domain name and unique site content. You can have
name-based or IP-based virtual hosting.
A virtual host referees the situation where the same host has multiple sites being
served either based on multiple NIC cards (IP based) or multiple names (for example,
abc.com and def.com resolving to same IP).
Consider a case where you have two virtual hosts configured on an OHS Server acting
as reverse proxy to OAM Server, as follows:
■One virtual host is configured in two-way SSL mode
■One virtual host configured in non-SSL mode
Suppose there are two resources protected with different authentication schemes and
Application Domains:
■/resource1 is protected by a X509Scheme with a Challenge URL (to define the
credential collection URL) of https://sslvhost:port/
When the user accesses /resource1 he is redirected to the OHS Server on the SSL
port for authentication and is asked for the X.509 Certificate.
■/resource2 is protected by a LDAPScheme on the second virtual host with a
Challenge Redirect of http://host:port/
Note: The information here is the same for both 11g and 10g
Webgates.
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-11
When user accesses /resource2 he is redirected to second virtual host which is in
non-SSL mode (or in one way SSL mode if required). The Login form for LDAP
authentication is displayed.
22.4.2.1 Placing a Webgate Behind a Reverse Proxy
You can use 10g Webgates with reverse proxies for Access Manager. This topic
discusses benefits and pitfalls of this strategy.
Benefits:
■All Web content can be protected from a single logical component as long as all
requests go through the proxy.
This is true even for platforms that are not supported by Access Manager. If you
have different types of Web servers (for example, iPlanet, Apache, and so on) on
different platforms (for example, Windows XP, Linux, and so on), all content on
these servers can be protected. A reverse proxy can be a workaround for
unsupported Web servers, eliminating the need to write custom Access Clients for
unsupported Web servers and on platforms that do not have Webgate support, for
example, MacOS.
■A reverse proxy offers architecture flexibility.
Reverse proxies can allow deployments to expose an application that is available
on the intranet to the extranet. Or applications that are available on the extranet
can be exposed to the intranet. This can be done without any changes to the
application that is already deployed.
■You only need to install a separate Webgate on the reverse proxy, rather than on
every Web server.
This allows for a single management point and can help with manageability of the
system. You can manage the security of all of the Web servers through the reverse
proxy without establishing a footprint on the other Web Servers.
Pitfalls: The main pitfall of using a proxy is the extra work involved in setup. If you
deploy the Webgate on a Web server that is behind a reverse proxy, the following are
configuration requirements:
■Ensure that any Web server that uses the reverse proxy for authentication only
accepts requests from the reverse proxies.
This will also require that Webgates deployed on this Web server be configured to
not enforce IP validation for requests from the reverse proxy server that front-ends
the Webgate. This is done by configuring the known IP addresses of the reverse
proxy server or servers in the IP Validation list. Note that while you can achieve
the same effect by turning IP validation off for the Webgate, this is not a
recommended approach due to security risks.
Ensuring that the Web server only accepts requests from reverse proxies is
typically done by adding an ACL statement in the server. This prevents users from
bypassing the reverse proxy and directly accessing restricted content.
Note: Your deployment can support X.509 and Form authentication
with 10g mod_osso. However, mod_osso can be configured for only
one SSO Server. In this case, the Agent redirects to Access Manager on
the non-SSL virtual host. The credential collector checks the
Authentication Scheme's Challenge URL parameter for the resource
and redirects back to the HTTPS virtual host for X509 authentication.
Managing Host Identifiers
22-12 Administrator's Guide for Oracle Access Management
■Update the virtual hosts that are configured in the Policy Manager so that the
Access System intercepts requests that are sent to the reverse proxy.
■Prevent people from circumventing the proxy by entering URLs that point directly
to the back-end system.
You can prevent this problem through the use of Web Server Access Control Lists
or firewall filters.
■Since all user requests are processed by the proxy, you must deploy enough proxy
servers to enable the system to handle the load.
■Redirect all existing URLs to the host name and port number of the reverse proxy
server.
This often requires configuring the reverse proxy to perform content inspection
and rewriting to prevent any absolute HTML links, for instance, to prevent broken
link. This is achievable with most reverse proxies, and this is something you can
configure independently of the Access System,.
■It is a best practice that URL links exposed to the front-ended applications rely on
only relative URLs (../../sub-path/resource) rather than absolute URLs
(http://example.com:[port]/path/resource).
Absolute URLs can break links on the end user's browser when deployed behind a
reverse proxy.
22.4.2.2 Configuring Virtual Hosting for Non-Apache Web Servers
Ensure that the Virtual Host box is checked on the 10g Webgate registration page.
On most Web servers, other than Apache-based servers, you must set the Preferred
Host value to HOST_HTTP_HEADER. This ensures that, when user's browser sends a
request, the Webgate sets the value of the Preferred Host to the host value in the
request. For example, suppose a user enters the string example2 in a URL:
http://example2
On the Web server, if one of the Web sites has a host named
example2
, the request is
served by the matching virtual site.
In the Preferred Host field of the expanded 10g Webgate registration page, enter the
following:
HOST_HTTP_HEADER.
IIS Virtual Hosting: From the IIS console, you must configure each virtual Web site to
contain the following fields:
■Host Header Name
■IP address
■Port
22.4.2.3 Associating a Webgate for Apache with Virtual Hosts, Directories, or Files
Ensure that the Virtual Host box is checked on the 10g Webgate registration page.
See Also:
■
http://www.simpledns.com/kb.aspx?kbid=1149
■
http://support.microsoft.com/kb/q190008/
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-13
On Apache-based Web servers (Apache, Apache 2, IBM HTTP Server, Oracle HTTP
Server, and so on), the Preferred Host value must be set to SERVER_NAME.
When using an Apache-based reverse proxy for single sign-on, in the Web server
configuration file (httpd.config, for example) file you specify the Web sites to run on
the Apache server. The settings can be global across all Web sites or local to a Web site.
You can restrict the Access Manager loading references in the httpd.config file to be
associated with a specified site, with virtual hosts, specific directories or even files.
To associate the Webgate with specific targets, you move the following directives the
the http.conf file:
AuthType Oblix
require valid-user
You can put these directives in a block that tells Apache to use Webgate for every
request. You can also move the directives to a block that limits when the Webgate is
called. The following is an example of putting the
LocationMatch
directive after a
VirtualHost
directive:
DocumentRoot /usr/local/apache/htdocs/myserver
ServerName myserver.example.net
AuthType Oblix
require valid-user
After you move the
LocationMatch
block to the
VirtualHost
directive, the Webgate
will only work for that virtual host. You can add the
LocationMatch
block to as many
virtual hosts as you want. The following examples shows how you could protect one
virtual server:
ServerAdmin webmaster@example.net
DocumentRoot "Z:/Apps/Apache/htdocs/MYsrv"
ServerName apps.example.com
ProxyRequests On
SSLEngine on
SSLCACertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/intermediateca.cer
SSLCertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_
ptcweb32.cer
SSLCertificateKeyFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_
ptcweb32.key
ErrorLog logs/proxysite1_log
CustomLog logs/proxysite1_log common
ProxyPass /https://apps.example.com/
ProxyPassReverse /https://apps.example.com/
ProxyPass /bkcentral https://apps.example.com/bkcentral
ProxyPassReverse /bkcentral https://apps.example.com/bkcentral
ProxyPass /NR https://apps.example.com/NR
ProxyPassReverse /NR https://apps.example.com/NR
Note: The SERVER_NAME value is not supported for any host other
than an Apache-based server. If you set this value for a
non-Apache-based server, users will be unable to access any resources
that are protected by Webgate on that Web server. Users will, instead,
receive an error that the Webgate configuration is incorrect.
The
ServerName
directive must be explicitly set with 7777 along with
the hostName. This is irrespective of the
Listen
directive is set
correctly. The Server sometimes requires this value explicitly to
identify itself, most often it can identify itself automatically.
Managing Host Identifiers
22-14 Administrator's Guide for Oracle Access Management
AuthType Oblix
require valid-user
#*** BEGIN Oracle Access Manager Webgate Specific ****
LoadModule obWebgateModule
Z:/apps/Oracle/WebComponent/access/oblix/apps/webgate/bin/webgate.dll
WebgateInstalldir Z:/apps/Oracle/WebComponent/access
WebgateMode PEER
SetHandler obwebgateerr
SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none
SSLLog logs/SSL.log
SSLLogLevel info
# You can later change "info" to "warn" if everything is OK
22.4.3 About the Host Identifier Page
A host identifier is automatically created when an Agent (and application) are
registered using either the Oracle Access Management Console or the remote
registration tool. In the Application Domain that is registered with the Agent, the host
identifier is used automatically.
Administrators can use the console to create and manage host identifiers. Within the
Oracle Access Management Console, host identifiers are organized under Shared
Components, on the Policy Configuration tab navigation tree. Administrators can
manually create a new host identifier definition, modify a definition, delete a
definition, or copy an existing definition to use as a template. The name of the copy is
based on the original definition name. For example, if you copy a definition named
host3, the copy is named copy of host3.
Figure 22–4 illustrates the Create Host Identifier configuration page in the console,
where you enter the canonical name for the host, and every other name by which the
same host can be addressed by users.
Figure 22–4 Create Host Identifier Page
Note: Each host identifier must be unique. You cannot use the same
host name and port in any other host identifier definition.
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-15
Table 22–4 describes the host identifier definitions.
22.4.4 Creating a Host Identifier
Users with valid Administrator credentials can use the following procedure to create a
host identifier definition manually. This is needed if an application and resources were
manually added to a host that has no mapped host identifier. When you choose Auto
Create Policies when registering an Agent, this is done automatically.
To manually create a Host Identifier
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Host Identifiers in the Access Manager
section.
3. Click Create Host Identifier.
4. On the Create Host Identifier page, fill in the:
a. Name
b. Description
c. Host Name Variations: Add (or remove) host name and port variations in the
Operations list.
Add: Click the Add (+) button, then enter a new host name and port
combination to identify variables that map to the Host Identifier Name.
Remove: Click a host name, then click the Delete button to remove it.
5. Repeat step 3c as needed to identify all variations of this host that users can access.
6. Click Apply to submit the new definition (or close the page without applying
changes).
Table 22–4 Host Identifier Definitions
Property Description
Name A unique name for this definition. Use only upper- and lower-case alpha characters.
No punctuation or special characters are allowed.
Description The optional description, up to 200 characters, that explains the use of this
configuration.
Host Name
Variations
■Host Name: A list of the various host names or permutations that users might
use when accessing the application.
See also: "Host Identifier Variations" on page 22-10 and "Host Identifier
Guidelines" on page 22-9.
■Port: The Web server port used by each host or permutation
Note: If you copy an existing definition to use as a template, you
must modify all unique identifiers in the copy.
See Also:
■"About Host Identifiers" on page 22-8
■"About Virtual Web Hosting" on page 22-10
Managing Host Identifiers
22-16 Administrator's Guide for Oracle Access Management
7. Close the Confirmation window, and confirm the new definition is listed in the
results table.
22.4.5 Searching for a Host Identifier Definition
Users with valid Administrator credentials can perform the following task to search
for a specific host identifier.
To find for a host identifier
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Host Identifiers in the Access Manager
section.
3. In the Search Host Identifiers page Name field, enter a name (or a partial name
with wild card (*)), or leave the Name field blank to show all Host Identifiers. For
example:
my_h*
4. Click the Search button to initiate the search and display results in a table, then:
■View or Edit: Double-click the name in the Search Results table to display the
configuration page, then add or edit as usual.
■Delete: Click the Delete button in the tool bar to remove the selected item in
the results table; confirm removal in the Confirmation window.
■Detach: Click Detach in the tool bar to expand the Search Results table to a full
page (or from the View menu, click Detach).
■Reorder Columns: From the View menu, select reorder Columns and use the
arrows provided to reorder the columns.
22.4.6 Viewing or Editing a Host Identifier Definition
Users with valid Administrator credentials can use the following procedure to modify
a host identifier definition. This can include adding, changing, or removing individual
host identifiers from the definition. For instance, when adding another proxy Web
server with a different host name, you might need to modify an existing host identifier
definition to add the new host name variation.
Prerequisite: Inventory Application Domains that refer to the host identifier and
Note: During Delete, if the Host Identifier is associated with a
resource, you are prompted with an alert. Without any association, the
Host Identifier is deleted successfully.
See Also: "Conducting A Search"
Note: After viewing settings, you can either close the page or modify
settings as needed.
See Also: "About the Host Identifier Page" on page 22-14
Managing Host Identifiers
Managing Authentication and Shared Policy Components 22-17
To view or modify a Host Identifier
1. Locate the desired host identifier and view it as described in "Searching for a Host
Identifier Definition" on page 22-16.
2. On the Host Identifier page, modify information as needed (Table 22–4):
a. Name
b. Description
c. Host Name Variations: In the table provided:
Add (+) Host Name Variations: Click the Add (+) button, then enter a new
host name and port combination to identify variables that map to the Host
Identifier Name.
Delete (X) Host Name Variations: Click a host name, then click the Delete
button to remove it.
3. Repeat step 3c as needed to add or remove variations.
4. Click Apply to submit the changes (or close the page without applying changes).
5. Dismiss the Confirmation window, and close the page when you finish.
22.4.7 Deleting a Host Identifier Definition
Users with valid Administrator credentials can use the following procedure to delete
an entire host identifier definition. A validation error occurs if you attempt to delete
the host identifier that is being used in a resource.
Prerequisites
Each resource in an Application Domain is associated with a specific host identifier. If
you intend to delete a host identifier you must first modify any resource definitions in
an Application Domain that uses this host identifier.
To delete a Host Identifier
1. Locate and modify related resource definitions in any application domains that
uses this host identifier. See "Searching for a Resource Definition" on page 25-28.
2. Locate the desired host identifier as described in "Searching for a Host Identifier
Definition" on page 22-16.
3. View: Double-click the name in the results table to display the configuration page,
and confirm this can be removed.
4. Delete: Click the Delete button in the tool bar to remove the selected item in the
results table; confirm removal in the Confirmation window.
Note: If the Host Identifier is associated with a resource, you are
alerted. Without any association, the Host Identifier is deleted.
See Also: "Viewing or Editing a Host Identifier Definition" on
page 22-16 if you want to remove a single host identifier from an
existing definition.
Understanding Authentication Methods and Credential Collectors
22-18 Administrator's Guide for Oracle Access Management
22.5 Understanding Authentication Methods and Credential Collectors
With Access Manager, authentication involves redirecting the requester (user) to a
centralized component that performs authentication (known as the Credential
Collector).
This section provides the following topics:
■About Different Authentication Methods
■Comparing Embedded Credential Collector with Detached Credential Collector
■Authentication Event Logging and Auditing
22.5.1 About Different Authentication Methods
Authentication is the process of proving that a user is who he or she claims to be.
Authenticating a user's identity with Access Manager refers to running a pre-defined
set of processes to verify the digital identity of the user.
Using Access Manager, a resource or group of resources can be protected by a single
authentication process known as an authentication scheme. Authentication schemes
rely on pre-defined authentication modules or plug-ins.
This section describes multi-level authentication and other authentication methods
supported by Access Manager.
Multi-level Authentication
Access Manager enables Administrators to assign different authentication levels to
different authentication schemes, and then choose which scheme protects which
application. Every authentication scheme requires a strength level. The lower this
number, the less stringent the scheme. A higher level number indicates a more secure
authentication mechanism.
SSO capability enables users to access more than one protected resource or application
with a single sign in. A user who is authenticated to access resources at level 2, is
eligible to access resources protected at levels less than or equal to 2. However, if the
user is authenticated to access resources at level 2 and then attempts to access
resources protected by level 3, the user is asked to re-authenticate (this is known as
step-up authentication).
For more information, see "About Multi-Level and Step-Up Authentication" on
page 22-80.
Multi-Step Authentication
Multi-step authentication requires a custom authentication module composed of two
or more authentication plug-ins that transmit information to the backend
authentication scheme several times during the login process. All information
collected by the plug-in and saved in the context will be available to the plug-in
through the authentication process. Context data can also be used to set cookies or
headers in the user's login page.
See "Comparing Simple Form and Multi-Factor (Multi-Step) Authentication" on
page 22-30.
See Also: "Multi-Step Authentication"
Understanding Authentication Methods and Credential Collectors
Managing Authentication and Shared Policy Components 22-19
Windows Native Authentication
Integrated Windows Native Authentication is supported for both OSSO and Webgate
protected applications. This form of authentication relies on the Kerberos
authentication module. For more information, see Chapter 57, "Configuring Access
Manager for Windows Native Authentication".
Other Authentication Types
Authentication features required by Oracle Fusion Middleware applications are
supported, including:
■Weak authentication, typically a user name and password, no certificates
■Auto-login with third-party self-service user provisioning
■HTTP header support for user context information. For instance, host identifiers
are used to create a host context for the resource. This is useful when adding
resources that have the same URL paths on different computers.
If you use different authentication schemes for two WebGates, users can go from a
higher authentication scheme to a lower one without re-authentication, but not from a
lower level to a higher level.
For details about configuring and using authentication schemes with Access Manager,
see "Managing Authentication Schemes" on page 22-64.
22.5.2 Comparing Embedded Credential Collector with Detached Credential Collector
Access Manager 11.1.2 supports the embedded credential collector (ECC) by default
but also enables you to configure the latest WebGate to use as a detached credential
collector (DCC, also known as an Authenticating WebGate). The DCC is considered
more secure than the default ECC. The centralized DCC presents the login page,
collects the user credentials (userID and password, for example), and sends these to
the OAM Server using the back channel Oracle Access Protocol (OAP). Additional
credentials can be requested using the DCC.
When OAM Server is configured to use the DCC, the ECC and its HTTP endpoints are
disabled. The only HTTP communication is to the Oracle Access Management Console
hosted by the WebLogic AdminServer in the domain where the OAM Server is
deployed. Connectivity to the AdminServer can be controlled at the network level, for
example, to disallow administration requests from outside the internal network.
■Allowing both the ECC and DCC to co-exist enables you to use authentication
schemes and policies configured for use with either the ECC or the DCC. This
enables a fallback mechanism for resources that rely on the ECC, which includes
the Oracle Access Management Console.
Note: During single sign-on, users might pass the authentication
tests but might fail authorization tests when attempting to access a
second or third resource. Each resource in the domain might have a
unique authorization policy.
Note: The DCC is the recommended approach for credential
collection. See Chapter 23, "Understanding Credential Collection and
Login" for more details.
Understanding Authentication Methods and Credential Collectors
22-20 Administrator's Guide for Oracle Access Management
■Disabling (turning off) the ECC entirely prohibits access to resources that rely on
the ECC mechanism, including the Oracle Access Management Console.
While the embedded and detached credential collectors (ECC and DCC, respectively)
are essentially the same, compare the two in Table 22–5.
See Also: "Understanding Credential Collection and Login"
Table 22–5 Comparing the DCC and ECC
DCC ECC
Deployment The Detached Credential Collector remains a
logical part of the server and acts as a front
channel communication endpoint of the OAM
Server. However, the DCC also:
■Stands alone (detached from the OAM
Server and does not require an application
server).
■Supports RSA SecurID passcode verification,
get next token, create new pin workflows.
■Is similar to the earlier 10g Authenticating
Webgate with greater flexibility for server
scale-out and attack resilience as well as
credential collection UI construction, flow,
and lifecycle management.
The Embedded Credential Collector is deployed
with, and integral to, the OAM Server and part of
the protocol binding layer.
The ECC supports RSA SecurID passcode
verification, get next token, create new pin
workflows.
DMZ Deployment Yes.
The main benefit of a deployment using DCC in
the DMZ is the termination of the end-user
network connections within the public network,
and the use of Oracle Access Protocol (Oracle's
proprietary application network protocol) over
mutually authenticated connections reaching the
OAM Server. This offers a complete isolation of
the OAM Server from the establishment of any
unauthenticated network connection.
Unauthenticated users cannot send malformed
requests to the OAM Server.
No.
Communication channel DCC consumes HTTP/HTTPS requests from the
user, then communicates with the OAM Server
across the Oracle Access Protocol (back channel),
which can be SSL-enabled.
ECC communicates with both the user and the
OAM Server across HTTP/HTTPS.
Understanding Authentication Methods and Credential Collectors
Managing Authentication and Shared Policy Components 22-21
DCC login, error, and
password pages
Dynamic pages general login/logout and
password policy with the DCC are excluded
automatically through the OHS
httpd.conf/webgate.conf file--you do not need to
configure a policy to exclude these. See the
Webgate host in $
WEBGATE_
HOME/webgate/ohs/oamsso/*,
$
WEBGATE_
HOME/webgate/ohs/oamsso-bin/*pl
, and
$WEBGATE_
HOME/webgate/ohs
/
oamsso-bin/templates
/*
directory:
■Login page:
/oamsso-bin/login.pl
■Logout:
/oamsso-bin/logout.pl
■RSA SecurID login pages:
/oamsso-bin/
securid.pl
Note: Update the Perl location in the first line of
the login, logout, and securid scripts in
/oamsso-bin
.
See Also: Table 24–4, " Credential Collector
Password Pages".
Chapter 56, "Integrating RSA SecurID
Authentication with Access Manager" for details
about login pages for this implementation.
For details about customizing pages and
messages, see the Oracle Fusion Middleware
Developer's Guide for Oracle Access
Management.
Pages where the user enters her credentials arrive
out of the box on the OAM Server and require no
additional settings or changes.
■Login page: /pages/login.jsp
■Logout page: /pages/logout.jsp
■Error page: /pages/servererror.jsp
■Multi-step: /pages/mfa_login.jsp
Perl Scripts for
DCC-based Login and
Logout
Perl Scripts for DCC-based Login and Logout
The path name of the Perl executable must be
updated in Oracle-provided Perl scripts on the
Webgate host
$WEBGATE_
HOME/webgate/ohs/oamsso-bin/*pl
to be
consistent with the actual location.
Unix: The
which
command finds Perl on the
OAM Server. For example:
which perl
/usr/bin/perl
However, Perl scripts themselves point to:
/usr/local/bin/perl
Windows: The default Perl Interpreter specified
in Oracle-provided Perl scripts will not be
available. You must update the Perl Interpreter
path in these scripts to actual path to Perl on your
system.
N/A
Password policy
enforcement
Yes.
See Configuring 11g WebGates and
Authentication Policy for DCC
Yes
See: Managing Global Password Policy
Authentication scheme
collection methods
DCC supports only Form Based Authentication. ECC supports all challenge methods.
The ECC collects user credentials based on the
challenge method of the Authentication Scheme
and sends it back to OAM Server for validation.
Custom Authentication
Plug-ins and Challenge
Methods
Yes; same as ECC. All challenge methods and multi-step
authentication (Password Policy and other
custom authentication plugins) are supported.
Table 22–5 (Cont.) Comparing the DCC and ECC
DCC ECC
Understanding Authentication Methods and Credential Collectors
22-22 Administrator's Guide for Oracle Access Management
Single Step (Simple
Form) Authentication
Yes; same as ECC. Yes. Both the DCC and ECC handle this, where:
■All credentials are supplied in one simple
form
■Upon credential validation and
authentication, either success or failure
status is returned
■This can be retried upon failure
Multi-Step
Authentication
Yes. Both the DCC and ECC handle complex
multi-factor (multi-step, iterative, and variable)
Authentication processing.
In this case:
■Not all required credentials are supplied at
once
■Depending on the authentication status,
PENDING state, expected credentials and
context data are returned, expecting those
credentials to be supplied in the next round
■Each intermediate step, submit required
credentials and context data to feed
authentication engine, until a success or
failure status returned
■The Authentication plug-in can have
multiple steps configured
See "Understanding Multi-Level and Step-Up
Authentication" on page 22-79
Yes. Both the DCC and ECC handle complex
multi-factor (multi-step, iterative, and variable)
Authentication processing.
Authentication
Processing
The DCC does not restrict authentication
functionality of the OAM Server in any way as
compared to the ECC.
The DCC:
1. Handles authentication redirects from both
10g and 11g Webgates.
2. Handles Form-based authentication, which
consists of a challenge to the user for their
credentials (simple form or multi-factor).
3. Decrypts the authentication request message
from the agent using the agent key; performs
basic integrity checks; validates request time;
and extracts all parameters from the request
including request context.
4. Constructs the authentication response
message, including request context
originally retrieved, encrypts obrar using the
agent key.
5. Decrypts the logout redirect request using
the agent key to trigger logout processing.
During authentication:
1. The ECC handles the request coming to the
protocol binding layer (PBL), which converts
it and sends it to the SSO Engine.
2. The SSO Engine checks for a valid session
and, if none, transfers control to the
Authentication Engine.
3. The Authentication Engine checks for
resource protection and fetches the
authentication scheme associated with the
resource.
4. The ECC interacts with the client, accepts the
data, and submits this to the PBL.
Table 22–5 (Cont.) Comparing the DCC and ECC
DCC ECC
Managing Native Authentication Modules
Managing Authentication and Shared Policy Components 22-23
22.5.3 Authentication Event Logging and Auditing
Authentication Success and Failure events are audited, in addition to administration
events. Auditing covers creating, modifying, viewing, and deleting authentication
schemes, modules, and policies. Information that is collected about the user who is
authenticating includes:
■IP address
■User Login ID
■Time of Access
During logging (or auditing), user information, user sensitive attributes are not
recorded. Secure data (user passwords, for example) are removed to avoid misuse.
22.6 Managing Native Authentication Modules
In Access Manager, each authentication scheme requires an authentication module.
Overriding the ECC To deploy the DCC and override the ECC, an
Administrator must perform the following tasks
to specify the relevant DCC URLs and forms.
■OAM Agent registration: Allow Credential
Collector Operations (enable for DCC)
■Authentication Module, Step Orchestration:
Error (if Failure)
■Authentication Scheme: Challenge Redirect
URL (DCC host and port)
■Authentication Scheme: Challenge URL
/
oamsso-bin/login.pl
(DCC login pages)
■Authentication Scheme: Challenge Method
■Password Policy: Password Service URL for
DCC (Default:
/oamsso-bin/login.pl
)
See Configuring 11g WebGates and
Authentication Policy for DCC
N/A
Logout Configuration See "Configuring Logout When Using Detached
Credential Collector-Enabled WebGate" on
page 27-6
See "Configuring Centralized Logout for 11g
WebGates" on page 27-4
Cookie/Token ■DCCCtxCookie
■11g WebGate: OAMAuthnCookie
■11g WebGate: OAMRequestContext
■10g Resource WebGate: ObSSOCookie
See: "About Single Sign-On Cookies During User
Login" on page 21-14
■11g Webgate: OAMAuthnCookie
■11g Webgate: OAM_REQ
■11g Webgate: OAM_ID
■11g Webgate: OAMRequestContext
■10g Webgate: ObSSOCookie
See: "About Single Sign-On Cookies During User
Login" on page 21-14
See Also:
■Chapter 7, "Logging Component Event Messages"
■Chapter 8, "Auditing Administrative and Run-time Events."
■Chapter 11, "Monitoring Performance and Health"
Table 22–5 (Cont.) Comparing the DCC and ECC
DCC ECC
Managing Native Authentication Modules
22-24 Administrator's Guide for Oracle Access Management
This section provides the following information:
■About Native Access Manager Authentication Modules
■Viewing or Editing Native Authentication Modules
■Deleting a Native Authentication Module
22.6.1 About Native Access Manager Authentication Modules
Table 22–6 lists the Native Access Manager Authentication Modules.
Note: Native authentication modules lack the flexibility to
orchestrate two or more plug-ins to meet specialized authentication
needs. Therefore, native authentication modules are targeted for
deprecation in future releases. Oracle strongly recommends using
plug-in based authentication modules as described "Orchestrating
Multi-Step Authentication with Plug-in Based Modules" on
page 22-29.
Table 22–6 Native Authentication Modules
Module Name Description
LDAP Matches the credentials (username and password) of the user who
requests a resource to a user definition stored in an LDAP directory
server. An LDAP module is required for Basic and Form challenge
methods.
See Also: "Native LDAP Authentication Modules" on page 22-25.
LDAPNoPasswordAuthModule Matches the credentials (username and password) of the user who
requests a resource to a user definition stored in an LDAP directory
server. An LDAP module is required for Basic and Form challenge
methods.
See Also: "Native LDAP Authentication Modules" on page 22-25.
Kerberos Identifies the key tab file and krb5.configuration file names and
Principal.
Use this plug-in when configuring Access Manager for Windows
Native Authentication, as described in Chapter 57.
See Also: "Native Kerberos Authentication Module" on page 22-25.
X509 Similar to the LDAPPlugin with additional properties that indicate
which attribute of the client's X.509 certificate should be validated
against the user attribute in LDAP.
See Also: "Native X.509 Authentication Module" on page 22-26.
Custom Authentication Modules This type of module relies on bundled plug-ins (or those that are
developed using the Access Manager Authentication Extensibility
Java API). This type of module generally uses more than one plug-in
that you can orchestrate to ensure that each one performs a specific
authentication function. Depending on the success or failure action
defined for each plug-in, another authentication plug-in is called.
See Also: "About Plug-in Based Modules for Multi-Step
Authentication" on page 22-39, and Oracle Fusion Middleware
Developer's Guide for Oracle Access Management for details about
developing and deploying plug-ins, custom authentication modules,
and schemes that use custom modules.
Managing Native Authentication Modules
Managing Authentication and Shared Policy Components 22-25
22.6.1.1 Native Kerberos Authentication Module
The pre-configured Kerberos authentication module is illustrated in Figure 22–5.
Additional details follow the figure.
Figure 22–5 Native Kerberos Authentication Module
Table 22–7 describes the definition of the native Kerberos authentication module. You
can use the existing, pre-configured Kerberos authentication module or create one of
your own.
22.6.1.2 Native LDAP Authentication Modules
Oracle provides two LDAP authentication modules:
■LDAP
■LDAPNoPasswordAuthModule
See Also:
■"About Challenge Methods" on page 22-71
■Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about creating custom authentication
plug-ins
Table 22–7 Native Kerberos Authentication Module Definition
Element Description
Name The unique ID of this module, which can include upper and lower case alpha
characters as well as numbers and spaces.
Key Tab File The path to the encrypted, local, on-disk copy of the host's key, required to authenticate
to the key distribution center (KDC). For example: /etc/krb5.keytab.
The KDC authenticates the requesting user and confirms that the user is authorized for
access to the requested service. If the authenticated user meets all prescribed
conditions, the KDC issues a ticket permitting access based on a server key. The client
receives the ticket and submits it to the appropriate server. The server can verify the
submitted ticket and grant access to the user submitting it.
The key tab file should be readable only by root, and should exist only on the
machine's local disk. It should not be part of any backup, unless access to the backup
data is secured as tightly as access to the machine's root password itself.
Principal Identifies the HTTP host for the principal in the Kerberos database, which enables
generation of a keytab for a host.
KRB Config File Identifies the path to the configuration file that controls certain aspects of the Kerberos
installation. A krb5.conf file must exist in the /etc directory on each UNIX node that is
running Kerberos.
krb5.conf contains configuration information required by the Kerberos V5 library (the
default Kerberos realm and the location of the Kerberos key distribution centers for
known realms).
Managing Native Authentication Modules
22-26 Administrator's Guide for Oracle Access Management
Both modules have the same requirements (Name and User Identity Store), as
illustrated in Figure 22–6. Additional details follow the figure.
Figure 22–6 Native LDAP Authentication Module
Table 22–8 describes the elements in an LDAP authentication module. The same
elements and values are also used in LDAPNoPasswordAuthnModule.
22.6.1.3 Native X.509 Authentication Module
Access Manager provides a pre-configured X.509 authentication module as a default.
Administrators can also create new X.509 authentication modules. In cryptographic
terms, X.509 is a standard for digital public key certificates used for single sign-on
(SSO). X.509 specifies standard formats for public key certificates, certificate revocation
lists, and attribute certificates among other things.
With X.509 digital certificates you can assume a strict hierarchical system of certificate
authorities (CAs) issuing the certificates. In the X.509 system, a CA issues a certificate
that binds a public key to a particular Distinguished Name, or to an Alternative Name
such as an e-mail address or a DNS-entry.
The trusted root certificates of an enterprise can be distributed to all employees so that
they can use the company PKI system. Certain Web browsers provide pre-installed
root certificates to ensure that SSL certificates work immediately.
Access Manager uses the Online Certificate Status Protocol (OCSP) Internet protocol to
maintain the security of a server and other network resources. OCSP is used for
obtaining the revocation status of an X.509 digital certificate. OCSP specifies the
Note: These standard LDAP Authentication Modules are targeted
for deprecation. Future enhancements will not be available in
standard modules. Oracle strongly recommends using plug-in based
modules.
Table 22–8 Native LDAP Authentication Modules Definition
Element Description
Name A unique name for this module.
User Identity Store The designated LDAP user identity store must contain any user credentials
required for authentication by this module. The LDAP store must be registered
with Access Manager.
See Also: "Registering and Managing User Identity Stores" on page 5-4.
Multiple identity store vendors are supported. Upon installation, there is only
one User Identity Store, which is also the designated System Store. If you add
more identity stores and designate a different store as the System Store, be sure
to change the LDAP module to point to the System Store. The authentication
scheme
OAMAdminConsoleScheme
relies on the LDAP module for Administrator
Roles and credentials.
See Also: "Using the System Store for User Identities" on page 5-5 and
"Administrator Lockout" on page E-6.
Managing Native Authentication Modules
Managing Authentication and Shared Policy Components 22-27
communication syntax used between the server containing the certificate status and
the client application that is informed of that status.
When a user attempts to access a server, OCSP sends a request for certificate status
information. OCSP discloses to the requester that a particular network host used a
particular certificate at a particular time. The server returns a response of "
current
",
"
expired
," or "
unknown
." OCSP allows users with expired certificates a configurable
grace period, during which they can access servers for the specified period before
renewing.
OCSP messages are encoded in ASN.1 and are usually transmitted over HTTP. The
request and response characteristic of OCSP has led to the term "OCSP responders"
when referring to OCSP servers. With Access Manager, the computer hosting the
Oracle Access Management Console is the OCSP responder.
An OCSP responder can return a signed response signifying that the certificate
specified in the request is 'good', 'revoked' or 'unknown'. If OCSP cannot process the
request, it can return an error code.
Figure 22–7 Native X.509 Authentication Module
Table 22–9 describes the requirements of the native X.509 authentication module.
Note: This standard Authentication Module is targeted for
deprecation. Future enhancements will not be available in standard
modules. Oracle strongly recommends using plug-in based modules.
Table 22–9 X509 Authentication Module Definition
Element Description
Name Identifies this module definition with a unique name.
Match LDAP Attribute Defines the LDAP distinguished name attribute to be searched against given
the X509 Cert Attribute value.
For example, if the certificate subject EMAIL is me@example.com and it
must be matched against the "mail" LDAP Attribute, an LDAP query must
search LDAP against the "mail" attribute with a value "me@example.com
(cn).
Default: cn
Managing Native Authentication Modules
22-28 Administrator's Guide for Oracle Access Management
22.6.2 Viewing or Editing Native Authentication Modules
Users with valid Administrator credentials can use the following procedure to modify
an existing authentication module. This includes changing the name of an existing
module as well as changing other attributes.
Prerequisites
Modify each authentication scheme that references the module you will change, to use
another authentication module if needed.
To find, view, or edit an authentication module
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Modules in the Plug-ins
section.
3. In the Search Results list, select the desired module to open its properties page.
4. On the properties page, modify information as needed:
■Kerberos Module: See Table 22–7
X509 Cert Attribute Defines the certificate attribute to be used to bind the public key (attributes
within subject, issuer scope to be extracted from the certificate: subject.DN,
issuer.DN, subject.EMAIL, for example).
See Also. Match LDAP Attribute earlier in this table.
Cert Validation Enabled Enables (or disables if not checked) X.509 Certificate validation.
When enabled, the OAM Server performs the certificate validation (rather
than having the WebLogic server intercept and validate the certificate before
passing it to the OAM Server). Access Manager performs the entire
certificate path validation.
OCSP Enabled Enables (or disables when not checked) the Online Certificate Status
Protocol. Values are either
true
or
false
. For example:
OCSP Enabled: true
Note: OCSP Server Alias, OCSP Responder URL and OCSP Responder
Timeout are required only when OCSP Enabled is selected.
OCSP Server Alias An aliased name for the OSCSP Responder pointing to CA certificates in
.oamkeystore file--a mapping between the aliased name and the actual
instance name or the IP address of the OSCSP Responder instance.
OCSP Responder URL Provides the URL of the Online Certificate Status Protocol responder. For
example, OpenSSL Responder URL:
http://localhost:6060
OCSP Responder Timeout Specifies the grace period for users with expired certificates, which enables
them to access OAM Servers for a limited time before renewing the
certificate.
Note: By default, the
LDAP
module is used in the authentication
scheme that protects the Oracle Access Management Console. To
ensure Administrator access, the
LDAP
module must point to the User
Identity Store that is designated as the System Store. If you change the
designated System Store, be sure to change the LDAP Module to
reference the newly designated System Store.
Table 22–9 (Cont.) X509 Authentication Module Definition
Element Description
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-29
■LDAP Module: See Table 22–8
■X.509 Module: See Table 22–9 and Table 22–15
5. Click Apply to submit the changes and close the Confirmation window (or close
the page without applying changes).
6. Add the updated authentication module to authentication schemes (or change to
another authentication module in each authentication scheme that references this
module), as described in "Managing Authentication Schemes" on page 22-64.
22.6.3 Deleting a Native Authentication Module
Users with valid Administrator credentials can use the following procedure to delete
an authentication module.
The following procedure is the same whether you are deleting a custom authentication
module or a native module.
Prerequisites
In each authentication scheme that references the module to be deleted, specify
another authentication module.
To delete an authentication module
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Modules in the Plug-ins
section.
3. Optional: Open the module to verify this is the module to remove, then close the
page.
4. In the Search Results list, click the desired module name, then click the Delete
button.
5. Confirm removal (or dismiss the confirmation window to retain the module).
22.7 Orchestrating Multi-Step Authentication with Plug-in Based Modules
Authentication involves determining which credentials a user must supply when
requesting access to a resource, gathering credentials, and returning a response that is
based on the results of credential validation. All authentication processing relies on an
authentication module to define the rules governing requirements and transmission of
information to the backend authentication scheme. All information collected by the
plug-in and saved in the context is available to the plug-in through the authentication
process. Context data can also be used to set cookies or headers in the user's login
page.
This section provides the following topics:
■Comparing Simple Form and Multi-Factor (Multi-Step) Authentication
■About Plug-ins for Multi-Step Authentication Modules
Note: Oracle strongly recommends using authentication plug-ins to
create custom authentication modules.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-30 Administrator's Guide for Oracle Access Management
■About Plug-in Based Modules for Multi-Step Authentication
■Example: Leveraging SubjectAltName Extension Data and Integrating with
Multiple OCSP Endpoints
■Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules
■Creating and Managing Step-Up Authentication
■Configuring an HTTPToken Extractor Plug-in
■Configuring a JSON Web Token Plug-in
22.7.1 Comparing Simple Form and Multi-Factor (Multi-Step) Authentication
Simple form-based authentication relies on the default embedded or optional detached
credential collector and Web forms that process user logins with Access Manager
authentication mechanisms. Simple form-based authentication is the default and does
not require additional configuration unless you want to customize forms. With simple
form-based authentication:
■All credentials are supplied in one simple form.
■Upon credential validation and authentication, either success or failure status is
returned.
■Authentication can be retried upon failure.
For dynamic, multi-step authentication, Access Manager provides a number of
plug-ins with which you can design and orchestrate your own customized
authentication modules. Authentication plug-ins provide processing that meets your
specific needs. Both the ECC and DCC handle complex multi-factor (multi-step,
iterative, and variable) Authentication processing, where:
■Not all required credentials are supplied at once
■Depending on the authentication status, PENDING state, expected credentials and
context data are returned, expecting those credentials to be supplied in the next
round
■Each intermediate step, submit required credentials and context data for the
authentication engine, until a success or failure status is returned.
■The Authentication plug-in can have multiple steps configured.
Table 22–10 provides more information about these two forms of authentication.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management if you want to create custom authentication
plug-ins.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about customizing login pages and forms
Note: Administrators can install multiple user identity stores for
Access Manager. Each identity store can rely on a different LDAP
provider. Each authentication plug-in can be configured to use a
different user identity store.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-31
22.7.2 About Plug-ins for Multi-Step Authentication Modules
You can create custom plug-in based authentication modules using existing Access
Manager as described in this chapter. You can also create your own plug-ins, as
described in the Oracle Fusion Middleware Developer's Guide for Oracle Access
Management.
Plug-ins operate with either the default embedded credential collector (ECC) or the
optional detached credential collector (DCC-enabled WebGate). Each authentication
plug-in provides an individual piece of functionality that you can use alone or string
together into a series of steps. The lifecycle of a plug-in centers around the ability to
add and use the plug-ins to build features and work flows that act as extensions to the
OAM Server. Each plug-in is deployed as a JAR file and each plug-in's configuration
requirements must be given in XML format.
Figure 22–8 shows plug-ins available out of the box. These plug-ins, and any that you
create using the SDK and import, appear in a list when you add steps to build a
custom authentication module.
Table 22–10 Simple Form versus Multi-Step Authentication
Authentication Method Description
Simple form-based
authentication
Simple form-based authentication relies on Credential Collectors (both ECC
and DCC) and Web forms that process user logins using Access Manager
authentication mechanisms. This is the default and does not require
additional configuration unless you want to customize forms.
See Also:
Oracle Fusion Middleware Developer's Guide for Oracle Access Management
for details about customizing login pages and forms
Multi-Step Authentication Multi-step authentication requires a custom authentication module composed
of two or more authentication plug-ins that transmit information to the
backend authentication scheme several times during the login process. All
information collected by the plug-in and saved in the context will be available
to the plug-in through the authentication process. Context data can also be
used to set cookies or headers in the user's login page.
Multi-Step authentication relies on:
■Authentication Chaining: You can chain multiple authentication plug-ins
in a new authentication module, and add the module to an
authentication scheme.
■Challenge Mechanism: Controls the way in which the required
credentials are collected. Currently, this is tied to the authentication
scheme. Both the ECC and DCC use the same challenge mechanisms.
■Credential Collection: Either the ECC or DCC can be used for multi-step
authentication. (DCC provides greater flexibility for interactions with
users or programmatic entities when collecting authentication-related
information that involves several methods to establish the user's
identity).
See Also:
Configuring 11g WebGates and Authentication Policy for DCC
"Creating and Managing Step-Up Authentication" on page 22-50
Oracle Fusion Middleware Developer's Guide for Oracle Access Management
for details about custom authentication plug-ins
Note: Standard (native) Authentication Modules are targeted for
deprecation; future enhancements will not be available in the standard
modules. Oracle strongly recommends using plug-in based modules
as described in "Orchestrating Multi-Step Authentication with Plug-in
Based Modules" on page 22-29.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-32 Administrator's Guide for Oracle Access Management
Figure 22–8 Access Manager Plug-ins for Customized Authentication Modules
The Name generally defines the component that relies on the plug-in. The Description
is optional. The Type column indicates the purpose of the plug-in. Activation Status
lets you know if this is active and ready to use.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about building your own custom plug-ins. You
can import new plug-ins, distribute, activate, deactivate, and remove
custom plug-ins.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-33
Whether you use an Oracle-provided plug-in or create one of your own, adding a
plug-in when you create a custom authentication module is the same. Each custom
module requires the following types of information:
■General identifies the unique name and optional description for the individual
plug-in.
■Steps identify the specific plug-ins to use, and their execution order, based on the
configuration details of each plug-in (including the user identity store to use).
■Step Orchestration specifies the action to be taken on success or on failure or on
error.
Figure 22–9 shows the Custom Authentication Module within the Access Manager
section of the System Configuration tree. Each module has three configuration tabs.
Figure 22–9 Creating Custom Authentication Modules: General
Table 22–11 describes the content of the General tab.
Clicking the Steps tab opens a fresh page where you can add a new step. When you
add a new Step, the following dialog box appears. Information that you enter is used
to populate the table and Details sections of the page.
Note: When multi-factor authentication is used, the
UserIdentificationPlugin should be invoked in the last pass during the
authentication process.
Table 22–11 General tab
Element Description
Name A unique name up to 60 characters.
Description Optional; up to 250 characters.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-34 Administrator's Guide for Oracle Access Management
Figure 22–10 Adding a Step and Associating a Plug-in
Table 22–12 describes the information required when adding a new step. Each step
requires a plug-in and each plug-in requires specific details for proper operation.
Table 22–13 describes the Plug-in Parameter Details required by Oracle-provided
plug-ins. Absent from this table are the plug-in exceptions (those plug-ins with no
initial parameters):
KerberosTokenIdentifier
,
FedAuthnRequestPlugin
, and
FedUserAuthenticationPlugin
.
Table 22–12 Add New Step Entries, Steps Results Table, and Details Section
Element Description
Step Name The unique name you enter to identify this step, up to 60 characters.
Description The optional description for this step, as entered when adding the step (up to 250
characters).
Plugin Name The plug-in that you select for a particular step from the list of imported and activated
plug-ins.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access Management
for details about creating custom plug-ins.
Step Details Plug-in configuration details must be specified to ensure proper operation. Details might
differ depending the chosen plug-in and its requirements.
See Also: Table 22–13.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-35
Table 22–13 Parameter Details for Various Plug-ins
Plug-in Parameter Display Name Description
KEY_IDENTITY_STORE_REF Identity Store Name Most plug-ins require this attribute to ensure that the
appropriate user identity store is called during
authentication.
The following plug-in uses only this property:
■TAPAssertionPlugIn
For additional Details required by plug-ins that employ
this property, see:
■UserIdentificationPlugIn
■UserAuthenticationPlugIn
■UserPasswordPolicyPlugin
■TAPUserAuthenticationPlugin
■TenantDisambiguationPlugin
CredentialCollectorPlugIn CredentialCollectorPlugIn This plugin allows the administrator to configure which
credentials will be collected for authentication.
Credentials to be collected are configured as step
parameters. The plugin validates these parameters and
renders the UI to collect the credentials. After user
input, the plugin parses the credential parameters and
builds the user context with credential objects.
NOTE: Plugin error responses are set to the context if
the credentials are invalid and the plugin returns failure.
The plugin supports the collection of 4 credentials as
step level parameters.
1. CRED_PARAM_1
2. CRED_PARAM_2
3. CRED_PARAM_3
4. CRED_PARAM_4
The following example illustrates how to collect a
username and password.
CRED_PARAM_1=
{ID=KEY_USERNAME},{DISPLAY_NAME=KEY_
USERNAME},{TYPE=text}
{ID=KEY_PASSWORD},{DISPLAY_NAME=KEY_
PASSWORD},{TYPE=password}
Where ID, DISPLAY_NAME and TYPE are constants.
Actiontype Action Type Indicates if the plugin wants to REDIRECT or
FORWARD to the login page to collect credentials.
loginPageURL Login Page URL The URL to which the user will be forwarded or
redirected for credential collection.
NO_OF_CREDENTIALS The number of credentials provided for the plugin
instance. If the number of instances is more than 4, the
user must update the oam-config file to add additional
CRED_PARAMS as plugin parameters.
UserIdentificationPlugIn UserIdentificationPlugIn This native plug-in maps the user to a specific LDAP
user record.
KEY_LDAP_FILTER LDAP Filter The search filter required to identify the user. LDAP
attributes are used when defining an LDAP search filter.
KEY_SEARCHBASE_URL LDAP Searchbase The search base required for the query. The node in the
directory information tree (DIT)) under which user data
is stored; the highest possible base for all user data
searches.
UserAuthenticationPlugIn UserAuthenticationPlugIn This native plug-in authenticates the supplied
username/password credentials against an LDAP
directory.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-36 Administrator's Guide for Oracle Access Management
KEY_PROP_AUTHN_
EXCEPTION
Propagate LDAP errors Enables (or disables) propagation of LDAP errors.
UserAuthenticationPlugIn employs this attribute.
UserAuthnLevelCheckPlugin UserAuthnLevelCheckPlugin This native plug-in shall determine if the user has been
authenticated to the authentication level X - where the
value of X is provided by the plugin parameter
AUTHN_LEVEL_FOR_PLUGIN. For example, it checks
the current Authentication Level of the user with the
value specified. In addition, the plug-in specifies a list of
parameters to collect depending on whether the
Authentication Level check succeeded or failed.
AUTHN_LEVEL_FOR_PLUGIN AUTHN_LEVEL_FOR_PLUGIN Specify the authentication level as an integer.
Multiple steps can use UserAuthnLevelCheckPlugin.
However, each Step must have a unique name and
AUTHN_LEVEL_FOR_PLUGIN.
See Also: "Creating and Managing Step-Up
Authentication" on page 22-50
UserPasswordPolicyPlugin UserPasswordPolicyPlugin
PLUGIN_EXECUTION_MODE Mode of Operation The execution mode of UserPasswordPolicyPlugin.
UserPasswordPolicyPlugin is supported only when
using LDAP based authentication modules. It does not
work with non LDAP authentication modules.
Depending upon the configuration, can operate either
alone or with other default plug-ins. Values are one of
the following:
■PSWDONLY: Default. The most preferred
configuration where only the password status is
determined. The ID and authentication must be
performed using the UserIdentification and
UserAuthentication Plugins.
■AUTHWITHPSWD: Both authentication and
password are performed using this plug-in.
■AUTHONLY: Only the user identification and
authentication is performed using this plug-in
POLICY_SCHEMA Policy Schema To Use Specifies the schema for the password service (used
with UserPasswordPolicyPlugin). Only OAM10G is
supported.
Default: OAM10G
NEW_USERPSWD_BEHAVIOR Force Password Change on First
Login
Configures retroactive behavior of the new-user
password-policy. Used with
UserPasswordPolicyPlugin.Values are either:
■FORCECHANGEPASSWORD: Forces a password
change.
■NOFORCEPASSWORDCHANGE: The password
policy change does not affect user passwords that
are already set.
Default: FORCECHANGEPASSWORD
DISABLED_STATUS_SUPPORT Disabled Account Status Support Specifies whether the disabled status is to be supported
and acted upon in this password service. Valid values
are either True or False.
Default: TRUE
URL_ACTION Password Management Action
URL
Specifies the URL to which the user is sent for password
management. The type of servlet action needed for
redirecting the user to the specific password page for
expiry and warning pages. Values can be either:
■REDIRECT_POST
■REDIRECT_GET
■FORWARD
Default: REDIRECT_POST
Table 22–13 (Cont.) Parameter Details for Various Plug-ins
Plug-in Parameter Display Name Description
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-37
FedUserProvisioningPlugin
KEY_USER_RECORD_
ATTRIBUTE_LIST
List of User Attributes For Federation. Comma-separated list of assertion
attributes required to create the user record.
KEY_PROVIDERID_ATTRIBUTE_
NAME
Partner Attribute Name For Federation. The attribute name of the LDAP user
record whose value will be set to the Partner's Identity
Provider ID when provisioning the user. This field is
optional and if empty, the Partner's Identity Provider ID
will not be set in the LDAP user record.
KEY_USERID_ATTRIBUTE_
NAME
User UserID Attribute For Federation. Name of the attribute in the assertion
attributes that is used as the LDAP UserID.
TAPIdentifyPlugIn
KEY_TAP_RETURN_ATTRIBUTE Username Mapping Attribute Name of the attribute used for account linking by
TAPIdentifyPlugIn.
SequentialPlugInExecutionStrate
gy
StrategyName Orchestration Strategy Name of the plugin orchestration strategy required by
SequentialPlugInExecutionStrategy.
KerberosTokenAuthenticator
KEY_KEYTAB_FILE Location of Keytab file Name of the file containing Kerberos principals and
encrypted keys required by
KerberosTokenAuthenticator
KEY_PRINCIPAL OAM Service Principal Your OAM Account SPN, required by
KerberosTokenAuthenticator.
KEY_KRB_CONFIG_FILE Location of Kerberos
Configuration file
Location of the Kerberos configuration properties file,
required by KerberosTokenAuthenticator.
KEY_DOMAIN_DNS2DN_MAP AD Domain DNS Names to DN
Mapping
Comma-separated list of Active Directory DNS
Domains to DN mappings required by
KerberosTokenAuthenticator.
X509CredentialExtractor
KEY_CERTIFICATE_ATTRIBUTE_
TO_EXTRACT
User Mapping Attribute X509 certificate Attribute to be used for user mapping
required by X509CredentialExtractor.
KEY_IS_CERT_VALIDATION_
ENABLED
Certificate Validation Enable or disable X.509 certificate validation, required
by X509CredentialExtractor.
TAPRequestPlugin
TAPS2PVersion Integration Protocol Version Token version for Integration.
TAPPartnerId Integration PartnerId Integration Partner Identifier.
TAPChallengeURL Partner Integration Endpoint
URL
Remote Partner End Point URL.
TAPUserAuthenticationPlugin
KEY_USERNAME_ATTRIBUTE Username Mapping Attribute Name of the attribute used for account linking required
by TAPUserAuthenticationPlugin
KEY_CHECK_TOKEN_EXPIRY Enable Token Expiration
Checking
Enable or disable Integration token expiration.
TenantDisambiguationPlugin
KEY_FEDERATED_TENANTS FederatedTenantNames Optional names of tenants (comma separated) for whom
federated authentication is enabled. Plugin will check
with Federation engine if tenant names are not
mentioned.
RSA SecurID Plugin
username Username Parameter Name of the username plugin parameter required by
RSA SecurID Plugin.
Table 22–13 (Cont.) Parameter Details for Various Plug-ins
Plug-in Parameter Display Name Description
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-38 Administrator's Guide for Oracle Access Management
Figure 22–11 illustrates the Steps tab and Details section for a custom authentication
module. When adding Steps, there is no data to display in the table. However, when
you add one or more Steps to the table, the Details sections are populated.
Figure 22–11 Plug-in Based Authentication Module Steps and Details
Figure 22–12 illustrates the Steps Orchestration tab of a custom authentication module,
which is populated by information for each defined step (and the action you choose
for each operational condition).
passcode Passcode Parameter Name of the passcode plugin parameter required by
RSA SecurID Plugin.
nexttoken Next Token Parameter Name of the next token plugin parameter required by
RSA SecurID Plugin.
newpin New PIN Parameter Name of the new pin plugin parameter required by RSA
SecurID Plugin.
confirmnewpin Confirm New PIN Parameter Name of the confirm new pin plugin parameter
required by RSA SecurID Plugin.
HTTPTokenExtractor
KEY_HEADER_PROPERTY HTTP Header Names Comma separated list of HTTP Headers. See
Section 22.7.7, "Configuring an HTTPToken Extractor
Plug-in."
KEY_COOKIE_PROPERTY HTTP Cookie Names Comma separated list of Cookies. See Section 22.7.7,
"Configuring an HTTPToken Extractor Plug-in."
Table 22–13 (Cont.) Parameter Details for Various Plug-ins
Plug-in Parameter Display Name Description
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-39
Figure 22–12 Steps Orchestration for Plug-in Based Authentication Modules
Table 22–14 describes the elements on the Steps Orchestration tab. The lists available
for
OnSuccess
,
OnFailure
, and
OnError
include the following choices:
■success
■failure
■StepName (any step in the module can be selected as the action for an operational
condition)
22.7.3 About Plug-in Based Modules for Multi-Step Authentication
The following topics describe several of the native Custom modules provided with
pre-populated plug-ins. You can use these to orchestrate your own custom
authentication modules:
Table 22–14 Steps Orchestration Tab
Element Description
Initial Step Choose the starting step from those listed. The list includes only those
steps defined for this module.
Name Each step added to this module is listed by the name that was entered
when the step was added.
Description The optional description for this step, entered when this step was
added.
OnSuccess The action selected for successful operation. A list provides actions
you can choose:
■Success
■Failure
■StepName (activates the next step)
OnFailure The action selected for failure of this step. A list provides actions you
can choose:
■Success
■Failure
■StepName (activates the next step)
OnError The action selected for an error when executing this step. A list
provides actions you can choose:
■Success
■Failure
■StepName (activates the next step)
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-40 Administrator's Guide for Oracle Access Management
■KerberosPlugin
■LDAPPlugin
■X509Plugin
■Password Policy Validation Module and Plug-ins
KerberosPlugin
Use this plug-in when configuring Access Manager for Windows Native
Authentication, as described in Chapter 57.
Figure 22–13 shows the KerberosPlugin module that is bundled with Access Manager
11g. This is a credential mapping module that matches the credentials (username and
password) of the user who requests a resource to the encrypted "kerberos ticket".
Figure 22–13 KerberosPlugin
Figure 22–14 shows the default steps and details. Figure 22–15 shows the orchestration
of the steps and conditions.
See Also:
■Table 22–13, " Parameter Details for Various Plug-ins"
■Example: How to leverage the SubjectAltName extension data
and integrate with multiple OCSP Endpoints on page 22-46
■"Creating and Managing Step-Up Authentication" on page 22-50
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-41
Figure 22–14 Default KerberosPlugin Steps and Details
Figure 22–15 Default KerberosPlugin Steps and Orchestration
LDAPPlugin
Figure 22–16 shows the LDAPPlugin module that is bundled with Access Manager. By
default, LDAPPlugin has 2 steps, shown in Figure 22–17. Figure 22–18 shows the
default orchestration of steps for LDAPplugin.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-42 Administrator's Guide for Oracle Access Management
Figure 22–16 LDAPPlugin
Figure 22–17 Default LDAPPlugin Steps and Details
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-43
Figure 22–18 Default Orchestration of Steps for LDAPplugin
X509Plugin
Figure 22–19 shows the X509Plugin module that is bundled with Access Manager 11g.
The X509Plugin is similar to the LDAPPlugin with additional properties that indicate
which attribute of the client's X.509 certificate should be validated against the user
attribute in LDAP. Figure 22–20 shows default steps and details for this plug-in.
Figure 22–21 shows the default orchestration of steps for the X509Plugin.
Figure 22–19 X509Plugin
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-44 Administrator's Guide for Oracle Access Management
Figure 22–20 X509Plugin Default Steps and Details
With this plug-in, the root and sub CA certificates must be added to the $DOMAIN_
HOME/config/fmwconfig/amtruststore because the X509CredentialExtractor plug-in
loads certificates from this location.
Table 22–15 lists the stepX509 values for Subject and Subject Alternative Names. Such
processing is only supported when the X509Plugin is used.
See Also:
■Table 22–13, " Parameter Details for Various Plug-ins"
■Example: How to leverage the SubjectAltName extension data
and integrate with multiple OCSP Endpoints on page 22-46
Table 22–15 X509 Step Details (KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT)
issuer.D Subject
subject. EDIPI
Note: EDIPI refers to the Electronic Data Interchange Personal
Identifier.
subjectAltName. OTHER_NAME (FASC-N)
Note: FASC-N refers to the Federal Agency Smart Credential Number.
subjectAltName. RFC822_NAME
subjectAltName. UNIFORM_RESOURCE_IDENTIFIER
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-45
Figure 22–21 Default Orchestration for X509Plugin Steps
Password Policy Validation Module and Plug-ins
Oracle provides a Password Policy Validation Module that employs the following
plug-ins as individual steps in the authentication process:
■User Identification Step
■User Authentication Step
■User Password Status Step
Figure 22–22 shows the Steps tab. Additional details follow the figure.
Figure 22–22 Password Policy Validation Module Plug-ins
Figure 22–23 shows the Steps Orchestration page for the Password Policy Validation
Module plug-ins, which is self explanatory.
See Also: "Example: Leveraging SubjectAltName Extension Data
and Integrating with Multiple OCSP Endpoints"
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-46 Administrator's Guide for Oracle Access Management
Figure 22–23 Steps Orchestration: Password Policy Validation Plug-ins
22.7.4 Example: Leveraging SubjectAltName Extension Data and Integrating with
Multiple OCSP Endpoints
Access Manager 11g support for personal identity verification (PIV) cards (a United
States Federal smart card), is to use FASC-N and EDIPI attributes from the
SubjectaltName extension to map the user during X.509 authentication. While multiple
OCSP providers are not supported, you can use an OCSP Gateway or write a custom
authentication plug-in that uses the OSDT OCSP APIs to validate against multiple
OCSP providers.
The following functionality is available only with the X.509 Plug-in (not the X.509
Authentication module). The Plug-in configuration specifies the LDAP attribute to
which the extracted attribute from the X.509 client certificate will be mapped.
Example: How to leverage the SubjectAltName extension data and integrate with
multiple OCSP Endpoints
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Plug-ins section, click Authentication Modules.
3. In the list of modules, select the X509Plugin module.
4. In the page that opens, click Duplicate and fill out the fields as follows:
General Tab:
a. Name: CustomX509Plugin.
b. Description: Custom Plug-in for X509.
Steps Tab:
See Also:
■Table 22–13, " Parameter Details for Various Plug-ins"
■Configuring Password Policy
See Also: "Creating and Orchestrating Plug-in Based Multi-Step
Authentication Modules" on page 22-48
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-47
a. Click + to add a step to the plug-in.
b. Enter a Name and Description, then select the X509CredentialExtractor plug-in.
Step Details:
a. KEY_IS_CERT_VALIDATION_ENABLED
true
.
b. KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT (Table 22–15):
subject.EDIPI, subjectAltName.OTHER_NAME (FASC-N),
subjectAltName.RFC822_NAME, subjectAltName.UNIFORM_RESOURCE_
IDENTIFIER
c. Click the Save button.
Add Another Plug-in:
a. Click + to add a different plug-in.
b. Enter the Name, Description, and select UserIdentificationPlugin
Step Details for Second Plug-in:
a. Set KEY_IDENTITY_STORE_REF to the required identity store.
b. Add the LDAP filter to the KEY_LDAP_FILTER attribute. For example:
(&(uid=
Unknown macro: {subject.CN}
)(mail=
Unknown macro: {subject.E}
))
c. Add the user search base, if required, to the KEY_SEARCH_BASE_URL
attribute.
d. Click the Save button.
e. Proceed to Step Orchestration tab (Step2).
5. Orchestrate Steps:
a. Initial Step: Select the X509CredentialPlugin Step from the drop down.
b. On Success: X509CredentialPlugin step, select the UserIdentificationPlugin Step
from the drop down list.
c. On Success: UserIdentificationPlugin step, select
Success
from the drop down
list.
d. On Failure: Select
Failure
for both X509CredentialPlugin and
UserIdentificationPlugin steps.
e. On Error: Select
Failure
for both X509CredentialPlugin and
UserIdentificationPlugin steps.
f. Click the Apply button and review the confirmation window stating that the
plug-in has been created successfully.
6. Set up the Certificate Validation Module for Certificate Validation and Revocation
using OCSP.
a. In the Oracle Access Management Console, click Configuration at the top of
the window.
See Also: "Managing Certificate Validation and Revocation" on
page 3-7
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-48 Administrator's Guide for Oracle Access Management
b. In the Configuration console, click Certificate Validation.
c. In the Certificate Revocation list, confirm that Enabled is checked, then click
Save.
d. In the OCSP/CDP section, enable OCSP, enter the OCSP URL and the Subject
of the OCSP Server's certificate, then click Save.
e. On the command line, use the Java keytool application to import the trusted
certificates into the $DOMAIN_HOME/config/fmwconfig/amtruststore
keystore, as trusted certificate entries.
22.7.5 Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules
Users with valid Administrator credentials can use the following procedure to create
custom authentication module that uses one or more authentication plug-ins. This
procedure outlines general steps for any authentication module (with sample
information to configure an authentication X509 module for use with the Online
Certificate Status Protocol (OCSP) to maintain the security of a server and other
network resources).
Prerequisites
Ensure that any user identity store associated with the module is running and includes
the required user population.
To create a custom authentication module using bundled plug-ins
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, select Create Custom Authentication Module
from the Create (+) drop-down list in the Plug-ins section.
3. In the page that appears, enter the Name and optional Description. For example:
CustomX509Plugin and Plugin for X509, respectively.
Click Apply to save general information.
4. Add Steps:
a. Click the Steps subtab.
b. Click the Add (+) button above the Steps table.
c. In the Add New Step dialog box, enter a unique Step Name and optional
Description.
d. Browse for and select the desired plug-in name (X509CredentialExtractor, for
instance) and click OK.
e. Confirm information in the results table.
Note: Initially the keystore is empty; its password is set the first time
the Java keytool application is used.
See Also:
■"Example: How to leverage the SubjectAltName extension data
and integrate with multiple OCSP Endpoints" on page 22-46
■"Creating and Managing Step-Up Authentication" on page 22-50
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-49
f. Repeat b through e to add other steps until you have listed all required
plug-ins for your module.
5. Define Step Details: Use appropriate values for requested parameters
(Table 22–12, Table 22–13, Table 22–17, " Managing Custom Plug-ins Actions" and
"Example: How to leverage the SubjectAltName extension data and integrate with
multiple OCSP Endpoints"):
a. Click a StepName in the table to reveal required details, enter appropriate
values for the requested details.
b. Validate User Cert using OCSP:
Confirm that KEY_IS_CERT_VALIDATION_ENABLED is set to
true
.
Add the certificate attributes to be extracted with KEY_CERTIFICATE_
ATTRIBUTE_TO_EXTRACT (Table 22–15):
subject.EDIPI
subjectAltName.OTHER_NAME (FASC-N)
subjectAltName.RFC822_NAME
subjectAltName.UNIFORM_RESOURCE_IDENTIFIER
c. Click the Save button.
d. Repeat to configure each step appropriately.
e. Ensure that users are provisioned in any user identity stores assigned in the
steps.
6. Orchestrate Steps: See Table 22–14 as you perform following steps.
a. Click the Steps Orchestration subtab.
b. From the InitialStep list, choose the name of the first step to be used.
c. Select a StepName in the table.
d. From the OnSuccess List, choose a condition (success or failure) or a step
name.
e. From the OnFailure List, choose the desired condition or a StepName.
f. From the OnError List, choose the desired condition or a StepName.
g. Repeat Steps c through f to orchestrate operations for each plug-in this
module.
h. Review your orchestration.
7. Initiate Strategy Validation: Click Apply to initiate validation of your
orchestration strategy:
■Successful Strategy: The orchestration strategy is applied and the module is
ready to include in an authentication scheme. Continue with Steps 9 and 10.
■Invalid Strategy: Click OK in the Error box, then edit your OnSuccess,
OnFailure, OnError strategies (or add or remove plug-ins) to correct the
problem. Repeat this step until your strategy is successful.
8. In the navigation tree, confirm the new Custom Authentication Module is listed,
and then close the page when you finish.
9. Use your custom module in an authentication scheme, as described in "Managing
Authentication Schemes" on page 22-64.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-50 Administrator's Guide for Oracle Access Management
22.7.6 Creating and Managing Step-Up Authentication
This section describes how to define step-up authentication using plug-ins within a
customized module. In this example, there are users who need standard level access to
pages on the corporate portal and those who need access to sensitive information. For
standard applications, authentication credentials include username and password. For
sensitive applications, credentials include username, password, and a security code
(the later obtained with a custom plugin that validates the code).
The processing that occurs with a customized step-up authentication module is driven
by the steps and plug-ins described in Table 22–16. For more information, see
Table 22–13.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-51
Table 22–16 Steps and Plug-ins in a Customized Step-up Authentication Module
Step
# Step Name Plug-in Name Description
1 StandardLevelCheck-2 UserAuthnLevelCheckPlu
gin
Configurable with the LevelCheck Rule and credentials
parameters associated with the SUCCESS or FAILURE
outcome resulting from the check.
This plugin communicates with the authentication engine to
determine the current authentication level of the user and
compares it with the plugin level parameter AUTHN_LEVEL_
FOR_PLUGIN. It interacts with a custom credential collector
and checks the current Authentication Level of the user against
the value specified. For example, if 2 is specified for X:
■Authentication Level >= X returns
ExecutionStatus.SUCCESS and proceeds to the next step;
for example it will check for higer level authentication.
■Authentication Level < X returns
ExecutionStatus.FAILURE and proceeds to the next step
in the plugin; for example it will collect the standard
credentials for level 2 (username and password).
Specifies parameters to collect depending on whether the
Authentication Level check succeeded or failed:
■ON SUCCESS, go to SensitiveLevelCheck-6
■ON FAILURE, go to CollectUserNamePassword
■ON ERROR, Failure
2 CollectUserNamePassword CredentialCollectorPlugin
Flow must start with the
Plug-in communicating
the credential parameters
to collect. The Action must
support allowing the
Server to mark parameters
as immutable.
This plugin interacts with the credential collector
(CustomReadServlet) to allow the administrator to configure
the credentials collected for authentication. Credentials to be
collected are configured as step parameters. The plugin
validates these parameters and renders the UI to collect them.
The user provides the credentials that need to be collected in
the step parameter. In this example, since in previous step user
was not authenticated to level 2, he will be prompted to enter a
user name and password.
■loginPageURL: /CustomRead/Servlet (generic credential
collector for UserAuthnLevelCheckPlugin to render the
interface to acquire plug-in specified credentials.
■No_OF_CREDENTIALS: 4
■CRED_PARAM_4
■CRED_PARAM_3
■CRED_PARAM_2: {ID=KEY_PASSWORD},{DISPLAY_
NAME=KEY_PASSWORD},{TYPE=password}
■CRED_PARAM_1: {ID=KEY_USERNAME},{DISPLAY_
NAME=KEY_USERNAME },{TYPE=text}
■actiontype: FORWARD
Credentials to be collected should be specified in this format
only for the credential collector to render the UI interface.
Also specifies action on:
■ON SUCCESS, go to UserIdentificationProcess
■ON FAILURE, Failure
■ON ERROR, Failure
3 UserIdentificationProcess UserIdentificationPlugIn Out of the box plug-in that maps the user to a specific LDAP
user record:
■ON SUCCESS, go to UserAuthenticationStep
■ON FAILURE, Failure
■ON ERROR, Failure
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-52 Administrator's Guide for Oracle Access Management
After defining and orchestrating plug-ins in an authentication module, you can use the
module in an authentication scheme and use the scheme in a policy.
Task overview: Configuring Step-up Authentication
1. Create or edit a custom authentication module for step up authentication:
2. Define your custom authentication module based on the Steps shown here.
4 UserAuthenticationStep UserAuthenticationPlugin Out of the box plug-in that authenticates the supplied
username and password credentials against an LDAP
directory.
■ON SUCCESS, go to SensitiveLevelCheck-6
■ON FAILURE go to CollectSensitiveLevelCreds
■ON ERROR, Failure
5 SensitiveLevelCheck-6 UserAuthnLevelCheckPlu
gin
This plugin communicates with the authentication engine to
determine the current authentication level of the user and
compares it with the plugin level parameter AUTHN_LEVEL_
FOR_PLUGIN. It interacts with a custom credential collector
and checks the current Authentication Level of the user against
the value specified. Specifies parameters to collect depending
on whether the check succeeded or failed:
■ON SUCCESS, Success
■ON FAILURE, go to CollectSensitiveLevelCreds
■ON ERROR, Failure
6 CollectSensitiveLevelCreds CredentialCollectorPlugin This plugin renders the UI for collecting credentials for level 6
authentication. This is similar to CollectUserNamePwd.
■ON SUCCESS, go to ValidateSensitiveLevelCreds
■ON FAILURE, Failure
■ON ERROR, Failure
■CRED_PARAM_1: {ID=securitycode},{DISPLAY_
NAME=form_securecode},{TYPE=text}
7 ValidateSensitiveLevelCred
s
SubjectSetPlugin This custom developed plug-in validates the security code
against the server.
■ON SUCCESS, Success
■ON FAILURE, Failure
■ON ERROR, Failure
See Also: "Creating and Orchestrating Plug-in Based Multi-Step
Authentication Modules"
Table 22–16 (Cont.) Steps and Plug-ins in a Customized Step-up Authentication Module
Step
# Step Name Plug-in Name Description
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-53
3. Orchestrate your Steps and Plug-ins as shown here and described in Table 22–16.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-54 Administrator's Guide for Oracle Access Management
4. Sensitive Scheme: Create or edit an Authentication Scheme for sensitive
applications that uses your customized step-up authentication module. For
example:
5. Lower-Level Scheme: Create or edit an Authentication Scheme for the lowest level
applications using your customized step-up authentication module F.or example:
See Also: "Managing Authentication Schemes" on page 22-64
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-55
6. Sensitive Policy: Create or edit an Authentication Policy for sensitive-level
resources using your customized step-up Authentication Scheme. For example:
7. Lower-Level Policy: Create or edit an Authentication Policy for the lowest level
resources using your customized step-up Authentication Scheme. For example:
See Also: Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"
Orchestrating Multi-Step Authentication with Plug-in Based Modules
22-56 Administrator's Guide for Oracle Access Management
8. Veri fy : Verify your resources and the policies that protect them.
22.7.7 Configuring an HTTPToken Extractor Plug-in
The following process should be followed to configure an HTTPToken Extractor
plug-in.
1. Create a sample plug-in that will re-direct the user to the authenticating
application.
The authenticating application will authenticate the user and set the user name in
the HTTP header or cookie.
2. Create a custom authentication module that will access any applicable plug-ins.
For example, if you add the plug-in created in the previous step and the
HTTPToken Extractor and User identification plug-ins, successful authentication
occurs when the process for all three plug-ins has been successfully completed.
3. Add values for the header name and the user search filter properties.
The KEY_HEADER_PROPERTY is set in the HTTPToken Extractor plug-in while
KEY_LDAP_FILTER is set in the UI plug-in. For example:
■KEY_HEADER_PROPERTY =
cookieorheadername
■KEY_LDAP_FILTER = (uid={
cookieorheadername
})
22.7.8 Configuring a JSON Web Token Plug-in
Oracle Access Manager (OAM) provides complete but different access management
solutions for both users and applications. After OAM authentication, SSO tokens are
issued which can be used with WebGates or products like Oracle API Gateway. These
tokens are specific to OAM though and there are often business requirements where
Web services or REST services need to be protected. While OAM tokens can be used to
protect web services, they are usually protected by standard tokens. A JSON Web
Token (JWT) is one of the standard tokens that is widely used.
Note: The user should be present in the data store which is being
used.
Orchestrating Multi-Step Authentication with Plug-in Based Modules
Managing Authentication and Shared Policy Components 22-57
In the RSPS2 release, OAM introduced complete support for an OAuth authorization
service provided by the Oracle Access Manager Mobile and Social (OAMMS) service.
The OAuth Service issues a JSON Web Token (JWT) for accessing Web services
subsequent to the user’s authentication and/or authorization. Thus, a user can be
authenticated with an OAM authentication mechanism and subsequently have both an
OAM and a JWT for access to different resources. A typical scenario in which this can
be used is when a WebGate protected application is accessed. The user is authenticated
by an OAM authentication module and both an OAM token and a JWT are provided.
The OAM token is used for access through the WebGate and the JWT can be used to
access a Web service or a REST service when needed. (The Web service or REST service
is protected by a product like Oracle API Gateway or Oracle Web Services Manager.)
A JSON Web Token Plug-in is now available in OAM. Use this JSON Web Token
Plug-in when you need to protect REST or Web services with standard tokens. The
JSON Web Token Plug-in issues both an OAM token and a Mobile and Social JWT that
can be used for Web services access. Oracle API Gateway and Oracle Web Services
Manager can use this JWT for Web services protection as well. See the following
sections for additional details.
■Understanding the JSON Web Token Plug-in
■Configure the JSON Web Token Plug-In
22.7.8.1 Understanding the JSON Web Token Plug-in
The following flow describes how the JSON Web Token Plug-in can be used in
deployments:
■Configure the Oracle Access Management WebGate to use both OAM
authentication and the JSON Web Token Plug-in.
■When a user accesses a resource protected by the WebGate, the WebGate redirects
the user to authenticate with Access Manager.
■Upon authentication, the plug-in identifies which OAuth service end point should
generate the JWT. (OAuth service end points are unique and can be configured to
point to a specific OAuth service profile within a specific Identity Domain.) Oracle
Access Manager Mobile and Social creates the JWT and the plug-in returns it as a
cookie. (The cookie name can be configured in the plug-in configuration.)
■The Web application intercepts the response and accesses the cookie so that it can
be used later for Web service access. Depending on how the web application is
deployed, there may be other options to retrieve the JWT. The user can now access
the Web resource.
■When the Web resource needs to access a Web service, it extracts the OAM Mobile
and Social JWT and sends it to the Oracle API Gateway.
■The Oracle API Gateway uses the Oracle OAuth Service REST API to validate the
token. It then grants access to the Web service. The Oracle API Gateway can also
validate the JWT locally without making a remote call to the OAuth service.
Notes: Currently there is not a mechanism to pass scope to the
OAuth service while issuing a JWT with OAM authentication.
Consequently, the token should be considered to have global scope.
Both the OAM token timeout and the JWT timeout can be set to the
same value to have the same validity. The OAM tokens and JWT are
not linked, so they cannot be terminated using single logout.
Deploying and Managing Individual Plug-ins for Authentication
22-58 Administrator's Guide for Oracle Access Management
22.7.8.2 Configure the JSON Web Token Plug-In
Use these steps to configure the JSON Web Token Plug-in. You will be creating a
custom authentication module.
1. In the Oracle Access Management Console, click Application Security at the top of
the window.
The Search Authentication Modules screen is displayed.
2. Select Create Custom Authentication Module from the Create (+) drop-down
menu in the Plug-ins section.
The General tab is displayed.
3. Enter a name (and optional description) for the custom authentication module.
For this example, we name the module JWTToken AuthnModule.
4. Click the Steps tab and the + (plus sign) to add a new step.
The Add New Step dialog is displayed. Three new steps will be added.
5. Specify a step name (and optional description), select an activated plug-in from
the Plug-in name drop down list and click OK.
For this example, the values are StepUI and UserIdentificationPlugin. The flow
parameters for that plug-in can be edited after it is added to the step
6. Enter values for the UserIdentificationPlugin parameters and click Save.
7. Click the + (plus sign) to add a second step, enter the name StepUA, select
UserAuthenticationPlugin from the drop down list and click OK.
8. Enter values for the UserAuthenticationPlugin parameters and click Save.
9. Click the + (plus sign) to add a third step, enter the name StepOAuth, select
OAuthTokenResponsePlugin from the drop down list and click OK.
10. Enter values for the OAuthTokenResponsePlugin parameters and click Save.
11. Click the Steps Orchestration tab to configure the orchestration of the steps in the
following order.
a. StepUI
b. StepUA
c. StepOAuth
12. Click Apply and close the Custom Authentication Module tab.
13. Click Authentication Schemes from the Launch Pad.
14. Select LDAPScheme and click Duplicate.
A Copy of LDAPScheme screen displays.
15. Change the value of Name to JWTToken AuthnScheme and the value of
Authentication Module to JWTToken AuthnModule.
16. Click Save.
17. Configure an Authentication policy with the newly defined JWTToken
AuthnScheme Authentication Scheme.
22.8 Deploying and Managing Individual Plug-ins for Authentication
This section provides the following topics:
Deploying and Managing Individual Plug-ins for Authentication
Managing Authentication and Shared Policy Components 22-59
■About Managing Your Own Authentication Plug-ins
■Deploying and Managing Individual Plug-ins for Authentication
■Deleting Your Custom Authentication Plug-ins
22.8.1 About Managing Your Own Authentication Plug-ins
Using information in the Oracle Fusion Middleware Developer's Guide for Oracle
Access Management, custom authentication plug-ins can be created and used to define
customized multi-step authentication modules.
After development, the plug-in must be deployed on the AdminServer, as a JAR file,
which is validated automatically. After validation, an Administrator can configure and
distribute the plug-in using the Oracle Access Management Console.
The server processes the XML configuration file within the plug-in JAR file to extract
data about the plug-in. After the plug-in is imported, an Administrator can see and
modify the various plug-in states based on information available from the
AdminServer.
Figure 22–24 illustrates the Plug-ins Node under the Common Configuration section
of the System Configuration tab, and the Plugins page. This Plugins page includes a
tool bar with command buttons, most of which operate on the plug-in that is selected
in the table. The table provides information about the existing custom plug-ins and
their state. The Plugin Details section at the bottom of the page reflects configuration
details for the selected plug-in the table.
Figure 22–24 Plug-ins Page
Administrators control plug-in states using the command buttons across the table at
the top of the Plug-ins page, as described in Table 22–17.
Deploying and Managing Individual Plug-ins for Authentication
22-60 Administrator's Guide for Oracle Access Management
Table 22–17 Managing Custom Plug-ins Actions
Action Button Description
Import Plugin... Adds the plug-in JAR file to the AdminServer $DOMAIN_HOME/oam/plugins and begins
plug-in validation.
■Same JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins)
matches an existing plug-in JAR name (in $DOMAIN_
HOME/config/fmwconfig/oam/plugins), Oracle Access Manager extracts new
configuration metadata from the XML file in the JAR (in $DOMAIN_HOME/oam/plugins)
and checks the version of the new plug-in.
■XML Version: If the new plug-in XML version (in $DOMAIN_HOME/oam/plugins) is
greater than the existing XML version (in $DOMAIN_
HOME/config/fmwconfig/oam/plugins), validation is successful. Otherwise, "invalid
plugin name with invalid version" is returned and the new plug-in JAR is removed (from
$DOMAIN_HOME/oam/plugins).
■Different JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins) is
different then existing plug-in JAR names (in $DOMAIN_
HOME/config/fmwconfig/oam/plugins), the new plug-in JAR is uploaded and validation
is successful.
On Success: Status is reported as "Uploaded" (even if an OAM Server is down). If all registered
OAM Servers report "Uploaded", then the status on AdminServer is also "Uploaded".
On Failure: Status is reported as "Upload Failed"
See Also: "About the Custom Plug-in Life Cycle" in the Oracle Fusion Middleware Developer's
Guide for Oracle Access Management
Distribute Selected ■Propagates the plug-in to all registered OAM Servers.
■Sets the plug-in flag in oam-config.xml to "Distribute=true".
■Starts the distribution listener and notification mechanism between AdminServer and OAM
Servers
■Distributes the plug-in JAR from AdminServer node to each OAM Server node under
$DOMAIN_HOME/config/fmwconfig/oam/plugins
On Success: Status is reported as "Distributed" (even if an OAM Server is down). If all registered
OAM Servers report "Distributed", then the status on AdminServer is also "Distributed".
On Failure: Status is reported as "Distribution Failed"
Deploying and Managing Individual Plug-ins for Authentication
Managing Authentication and Shared Policy Components 22-61
Table 22–18 describes elements in the Plugins status table.
Activate Selected After successful distribution the plug-in can be activated on all registered OAM Servers.
Activation:
■Updates the plug-in flag in oam-config.xml to "Activate=true"
■Starts the Message listener and notification mechanism between AdminServer and OAM
Servers
■AdminServer sends message "Activate" to all registered OAM Servers
On Success: Status is reported as "Activated" (even if an OAM Server is down). If all registered
OAM Servers report "Activated", then the status on AdminServer is also "Activated".
On Failure: Status is reported as "Activation Failed"
Following activation on all OAM Servers, the plug-in can be used and executed in any
authentication module construction or orchestration.
Deactivate Selected Following plug-in activation, an Administrator can choose to deactivate the plug-in: if the plug-in
is not used in any authentication module or scheme, for example. The selected plug-in from all
registered OAM Servers.
Deactivate:
■Updates the plug-in flag in oam-config.xml to "De-activate=true"
■Starts the Distribution listener and notification mechanism between AdminServer and OAM
Servers
■Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_
HOME/config/fmwconfig/oam/plugins)
■AdminServer sends message "De-activation" to all registered OAM Servers
■OAM Servers send status message to AdminServer using the "Message" listeners on both
AdminServer and OAM Server
On Success: Status is reported as "De-activation" (even if an OAM Server is down). If all
registered OAM Servers report "De-activation", then the status on AdminServer is also
"De-activation". Plug-in configuration is removed from oam-config.xml.
Note: After deactivation, the plug-in cannot be used or executed in any authentication module or
orchestration.
On Failure: Status is reported as "De-activation Failed"
Remove Selected Following plug-in deactivation, an Administrator can delete the selected plug-in. During this
process, Access Manager:
Delete:
■Updates the plug-in flag in oam-config.xml to "Remove=true"
■Starts the Distribution listener and notification mechanism between AdminServer and OAM
Servers
■Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_
HOME/config/fmwconfig/oam/plugins)
■AdminServer sends message "Activate" to all registered OAM Servers
On Success: Status is reported as "Removed" (even if an OAM Server is down). If all registered
OAM Servers report "Removed", then the status on AdminServer is also "Removed". Plug-in
configuration is removed from oam-config.xml.
On Failure: Status is reported as "Removal Failed"
Table 22–18 Plugins Status Table
Element Description
Plugin Name Extracted from the Plugin name element of the XML metadata file.
Description Extracted from the description element of the XML metadata file.
Activation Status Reported activation status based on information from AdminServer.
Table 22–17 (Cont.) Managing Custom Plug-ins Actions
Action Button Description
Deploying and Managing Individual Plug-ins for Authentication
22-62 Administrator's Guide for Oracle Access Management
In the Plugin Details section of the page, the Activation Status is maintained by the
AdminServer, as shown in Table 22–18.
Figure 22–25 Plugin Details: Activation Status of Selected Plug-in
Depending on your plug-in, various configuration details are extracted from the
configuration element of the XML metadata file to populate Configuration Parameters
in the Plugin Details section. Examples are shown in Table 22–19; see also, Table 22–13.
22.8.2 Making Custom Authentication Plug-ins Available for Use
Users with valid Administrator credentials can perform the following task to add,
validate, distribute, and activate a custom plug-in.
Prerequisites
Developing a custom plug-in as described in the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management
Type Extracted from the type element of the XML metadata file.
Last Updated on Extracted from the creation date element of the XML metadata file.
Last Updated by Extracted from the author element of the XML metadata file.
Table 22–19 Example of Plugin Details Extracted from XML Metadata File
Configuration
Element Description
DataSource
- <configuration>
- <AttributeValuePair>
<Attribute type="string" length="20">DataSource</Attribute>
<mandatory>true</mandatory>
<instanceOverride>false</instanceOverride>
<globalUIOverride>true</globalUIOverride>
<value>jdbc/CISCO</value>
<AttributeValuePair>
<configuration>
Kerberos Details Defines the following Kerberos details:
KEY_KEYTAB_FILE, KEY_PRINCIPAL, KEY_KRB_CONFIG_FILE
User Identification
Details
Defines the User Identity Store and LDAP filter parameters. for this plug-in to use:
KEY_IDENTITY_STORE_REF, KEY_LDAP_FILTER
User Authentication
Details
Defines the User Identity Store for this plug-in to use:
KEY_IDENTITY_STORE_REF
X.509 Details Defines the X.509 certificate details for this plug-in to use:
KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT, KEY_IS_CERT_VALIDATION_ENABLED
Table 22–18 (Cont.) Plugins Status Table
Element Description
Deploying and Managing Individual Plug-ins for Authentication
Managing Authentication and Shared Policy Components 22-63
To make available for use a custom authentication plug-in
1. Import the Plug-in:
a. In the Oracle Access Management Console, click Application Security at the
top of the window
b. In the Application Security Console, click Authentication Plug-ins in the
Plug-ins section.
c. In the page that appears, click Import Plug-in.
d. In the Import Plugin dialog box, click Browse and select the name of your
plug-in JAR file.
e. Review the message in the dialog box, then click Import.
The JAR file is validated as described in Oracle Fusion Middleware
Administrator's Guide for Oracle Access Management.
2. Configure Parameters: Expand the Plugin Details section, click Configuration
Parameters, and enter appropriate information as needed.
3. Distribute the Plug-in to OAM Servers:
a. In the Plug-ins table, select the target plug-in.
b. Click Distribute Selected, then check the plug-in’s Activation Status tab.
4. Activate the Plug-in (and the custom plugin implementation class) so it is ready to
be used by OAM Server:
a. In the Plug-ins table, select the target plug-in.
b. Click Activate Selected, then check the plug-in’s Activation Status.
5. Perform the following tasks as needed:
■Checking an Authentication Plug-in's Activation Status
■Deleting Your Custom Authentication Plug-ins
■Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules
22.8.3 Checking an Authentication Plug-in's Activation Status
Users with valid Administrator credentials can perform the following task to add,
validate, distribute, and activate a custom plug-in.
Prerequisites
Making Custom Authentication Plug-ins Available for Use
To check the activation status of a custom authentication plug-i
1. In the Oracle Access Management Console, click Application Security at the top
of the window
2. In the Application Security console, click Authentication Plug-ins in the Plug-ins
section.
3. In the Plug-ins table, select the target plug-in.
4. Server Instance Name: Expand the Plug-in Details section and click Activation
Status to display the location and status of the plug-in.
5. Perform the following tasks as needed:
Managing Authentication Schemes
22-64 Administrator's Guide for Oracle Access Management
■Deleting Your Custom Authentication Plug-ins
■Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules
22.8.4 Deleting Your Custom Authentication Plug-ins
Users with valid Administrator credentials can use the following procedure to
deactivate and then delete a custom plug-in.
When an Administrator deletes a custom authentication plug-in, its name is not
removed from the list of plug-ins. To delete the plug-in (for the purpose of
re-importing the same plug-in later), the Administration must stop the WebLogic
Server and edit the oam-config.xml manually.
Prerequisites
The plug-in must have been added and available in the console
To delete a custom authentication plug-in
1. In the Oracle Access Management Console, click Application Security at the top
of the window
2. In the Application Security console, click Authentication Plug-ins in the Plug-ins
section.
3. Deactivate the Plug-in: You must perform this before removing a plug-in.
a. In the Plug-ins table, select the target plug-in.
b. Click Deactivate Selected, then check the plug-in’s Activation Status.
4. Delete the Deactivated Plug-in:
a. In the Plug-ins table, select the target plug-in.
b. Click Delete Selected.
c. Stop the WebLogic Administration Server, locate and edit oam-config.xml
manually to remove the deactivated plug-in, and then restart the WebLogic
Administration Server.
5. Perform the following tasks as needed:
■Making Custom Authentication Plug-ins Available for Use
■Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules
22.9 Managing Authentication Schemes
Access to a resource or group of resources can be governed by a single authentication
process known as an authentication scheme. An authentication scheme is a named
component that defines the challenge mechanism required to authenticate a user. Each
authentication scheme must also include a defined authentication module (standard or
custom, as described in "Deploying and Managing Individual Plug-ins for
Authentication" on page 22-58).
When you register a partner (either using the Administration Console or the remote
registration tool), the Application Domain that is created is seeded with a policy that
uses the authentication scheme that is set as the default scheme. You can choose any of
the existing authentication schemes as the default for use during policy creation.
You can also create a new authentication scheme, copy an existing definition to use as
a template, modify a definition, or delete the definition. The copy uses a default name
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-65
that is based on the original. For example, if you copy the scheme named
KerberosScheme, the copy is named Copy of KerberosScheme.
This section is divided into the following topics:
■About Authentication Schemes and Pages
■Understanding Multi-Level and Step-Up Authentication
■Creating an Authentication Scheme
■Viewing, Editing, or Deleting an Authentication Scheme
■Searching for an Authentication Scheme
22.9.1 About Authentication Schemes and Pages
All authentication schemes include the same elements with differing values.
Figure 22–26 shows the default LDAPScheme page as an example.
Figure 22–26 Default LDAPScheme Page
Table 22–20 provides information about each of the elements and values in any
authentication scheme. Use the Set as Default button to make this the default scheme.
Table 22–20 Authentication Scheme Definition
Element Description
Name The unique name for this scheme, which appears in the navigation tree.
See Also:"Pre-configured Authentication Schemes" on page 22-68
Description The optional description, up to 200 characters, that explains the use of this
scheme.
Managing Authentication Schemes
22-66 Administrator's Guide for Oracle Access Management
Authentication Level The trust level of the authentication scheme. This reflects the challenge method
and degree of trust used to protect transport of credentials from the user.
The trust level is expressed as an integer value between 0 (no trust) and 99
(highest level of trust).
Note: Level 0 is unprotected. Only unprotected resources can be added to an
Authentication Policy that uses an authentication scheme at protection level 0.
For more information, see Table 25–1, " Resource Definition Elements".
Note: After a user is authenticated for a resource at a specified level, the user is
automatically authenticated for other resources in the same Application Domain
or in different Application Domains, if the resources have the same or a lower
trust level as the original resource.
See Also: "About Multi-Level and Step-Up Authentication" on page 22-80.
Default A non-editable box that is checked when the Set as Default button is clicked.
Challenge Method One challenge method must be selected from those listed as available:
■Form
■Basic (LDAP)
■X509 (Certificate)
■WNA (Windows Native Authentication)
■None
■DAP
■OAM10g
See Also: "About Challenge Methods" on page 22-71
Challenge Redirect
URL
This URL declares the end point referencing the Credential Collector (ECC or
DCC). For example:
ECC:
/oam/server
DCC:
http://
<
dcc-host:port
>/
See Also:
■"About Host Identifiers" on page 22-8
■Configuring 11g WebGates and Authentication Policy for DCC
Authentication Module Identifies the pre-configured authentication module to be used to challenge the
user for credentials. The module or plug-in specified here identifies the exact
user identity store to be used.
■FederationMTPlugin
■FederationPlugin
■Kerberos Plugin (Authentication Modules and Custom Authentication
Module)
■MTLDAPBasic
■MTLDAPPlugin
■OIFMTLDAPPlugin
■Password Policy Validation Module
■TAPModule
■X509 Plugin (under the X509 Authentication Modules node)
See Also "Managing Native Authentication Modules" on page 22-23 and
"Orchestrating Multi-Step Authentication with Plug-in Based Modules" on
page 22-29.
Table 22–20 (Cont.) Authentication Scheme Definition
Element Description
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-67
About Custom Login Pages
Only Schemes with the Challenge Method of FORM, X509, or DAP include additional
elements described at the end of Table 22–20. All custom login pages must meet the
following requirements:
Challenge URL This URL is associated with the designated Challenge Method (FORM, for
instance).
FORM-based, out of the box authentication scheme (LDAPScheme and
LDAPNoPasswordValidationScheme), Challenge URL is "/pages/login.jsp". The
context type and context values are used to build the final URL.
X509-based Challenge URL takes the form:
https://managed_server_
host:managed_server_ssl_port/oam/CredCollectServlet/X509
Note: The default Challenge URL is based on the credential collector embedded
with the OAM Server (ECC). If you are using detached credential
collector-enabled Webgate and related DCC pages installed with WebGate, see
Configuring 11g WebGates and Authentication Policy for DCC.
Challenge Parameters Supported challenge parameters are discussed in "About Challenge Parameters
for Authentication Schemes" on page 22-75.
For schemes using
Challenge Method
FORM, X509, or DAP
Only Schemes with the Challenge Method of FORM, X509, or DAP include the
following additional elements. Other schemes use defaults that require no
change.
Context Type Used to build the final URL for the Embedded Credential Collector (ECC only,
DCC does not use this) based on the following possible values:
■default: The Context Value is used to construct the final URL to forward to
for credential collection. For example: with a challenge URL of
"/pages/login.jsp" and a context value of /oam, the server forwards to
"/oam/pages/login.jsp" for credential collection by the ECC.
■customWar: If a customized credential collector page "customlogin.jsp" is
deployed in a WAR file (with context root, "custom") within the same
domain, it should be used to collect credentials. Then set the following
values to have server forward to the WEB application page
"/custom/customlogin.jsp" to collect credentials:
challenge_url = "/customlogin.jsp"
contextType="customWar"
contextValue="/contextroot of custom application"
■customHtml: A custom html credential collector page. This file can be
placed in a location that is accessible to the application. Set the following
values to have the server forward to the custom servlet provided to read the
html file and render the page:
challenge_url = "/CustomReadServlet"
contextType="customHtml"
contextValue="html file location"
■external: If the login page is external, the file can be placed in a location that
is accessible to the application. Set the following values to have the server
redirect to the challenge URL (the fully-qualified URL of the external
credential collector page) for credential collection. The username and
password are collected by the external form (HTML or jsp) and submitted
to the OAM Server:
challenge_url = "http://host:port/externallogin.jsp"
contextType="external"
contextValue=Not applicable
See Also: "About Custom Login Pages" on page 22-67 and Managing Global
Password Policy
Context Value Used to build the final URL for the credential collector. The default value is
/oam.
Table 22–20 (Cont.) Authentication Scheme Definition
Element Description
Managing Authentication Schemes
22-68 Administrator's Guide for Oracle Access Management
■Custom login pages require two form fields (username and password). Access
Manager supports custom forms as described in Oracle Fusion Middleware
Developer's Guide for Oracle Access Management.
■CustomWar and external context types, require logic within the custom login page
to perform the following two tasks:
–Send back the request ID the page received from the Access Manager server.
For example:
String reqId = request.getParameter("request_id");
<input type="hidden" name="request_id" value="<%=reqId%>">
–Submit back to the OAM Server the end point, "/oam/server/auth_cred_
submit". For example:
<form action="/oam/server/auth_cred_submit"> or
"http://oamserverhost:port/oam/server/auth_cred_submit
".
For more information, see the following topics:
■Pre-configured Authentication Schemes
■About Challenge Methods
■About Challenge Parameters for Authentication Schemes
22.9.1.1 Pre-configured Authentication Schemes
Table 22–21 identifies the pre-configured authentication schemes available with Access
Manager and some specific details of each. For more information about challenge
parameters, see Table 22–21.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details about customizing login pages and
messages.
Table 22–21 Pre-configured Authentication Schemes
Scheme Name Specifications Purpose
AnonymousScheme Authentication Level: 0
Challenge Method: None
Authentication Module: AnonymousModule
Leaves unprotected specific Access Manager URLs
and allows users to access such URLs without a
challenge. Users are not challenged and do not need to
enter their credentials.
Note: Authentication Level 0 is for public pages.
Oracle recommends that you do not use Level: 0 in a
custom authentication scheme.
Also: When a resource is protected by
AnonymousScheme, it is not displayed in a session
search.
BasicFAScheme
Only for Oracle Fusion
Applications
For Fusion Applications For specific information about this authentication
scheme, refer to the Oracle Fusion Applications
Technology Library located on the Oracle Technology
Network (OTN) web site:
http://www.oracle.com/technetwork
BasicScheme Authentication Level: 1
Challenge Method: Basic
Authentication Module: LDAP
Protects Access Manager-related resources (URLs) for
most directory types.
Note: Authentication Level 1 is only one step higher
than 0 public pages. Oracle recommends that you do
not use Level: 1 in a custom authentication scheme.
BasicSessionlessScheme Authentication Level: 1
Challenge Method: Basic
Authentication Module: LDAP
Primarily used for clients that don't support URL
redirect or cookies.
Challenge Parameters: CookieLessMode=true
Note: Authentication Level 1 is only one step higher
than 0 public pages. Oracle recommends that you do
not use Level: 1 in a custom authentication scheme.
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-69
FAAuthScheme
Only for Oracle Fusion
Applications
Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context: customWar
Context Value: /fusion_apps
For specific information about this authentication
scheme, refer to the Oracle Fusion Applications
Technology Library located on the Oracle Technology
Network (OTN) web site:
http://www.oracle.com/technetwork
FederationMTScheme
Only for Oracle Fusion
Applications
Authentication Level: 2
Challenge Method: FORM
Authentication Module: FederationMTPlugin
Context Type: customWar
Context Value: /fusion_apps
Challenge Parameters: initial_
command=NONE
is_rsa=true
For specific information about this authentication
scheme, refer to the Oracle Fusion Applications
Technology Library located on the Oracle Technology
Network (OTN) web site:
http://www.oracle.com/technetwork
See Also: "About Challenge Parameters for
Authentication Schemes" on page 22-75.
FederationScheme
Only for Identity
Federation 11.1.2.
Authentication Level: 2
Challenge Method: FORM
Authentication Module: FederationPlugin
Context Type: customWar
Context Value: /oam
Challenge Parameters: initial_
command=NONE
is_rsa=true
See Also: Part IX, "Managing Oracle Access
Management Identity Federation".
Note: With Oracle Identity Federation 11.1.1, use
OIFScheme as described in the Oracle Fusion
Middleware Integration Guide for Oracle Access
Manager.
KerberosScheme Authentication Level: 2
Challenge Method: WNA
Authentication Module: Kerberos
Context Type: customWar
Context Value: /fusion_apps
Protects Access Manager-related resources (URLs) for
most directory types based on a Windows Native
Authentication challenge method and valid WNA
credentials in Active Directory.
LDAPNoPasswordValid
ationScheme
Authentication Level: 2
Challenge Method: FORM
Authentication Module:
LDAPNoPasswordAuthModule
Context Type: default
Context Value: /oam
Note: LDAPNoPasswordAuthModule is
similar to the DAP (asserter) mechanism.
See Also OAM10gScheme, later in this table.
Protects Access Manager-related resources (URLs) for
most directory types based on a form challenge
method.
Used with the Identity Asserter for SSO when you
have resources in a WebLogic Container. For details,
see the Oracle Fusion Middleware Application
Security Guide.
LDAPScheme Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: customWar
Context Value: /fusion_apps
Protects Access Manager-related resources (URLs) for
most directory types based on a form challenge
method.
OAAMAdvanced Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: external
Protects OAAM-related resources with an external
context type. This authentication scheme is used when
complete integration with OAAM is required. A
Webgate must front ending the partner.
OAAMBasic Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: default
Context Value: /oam
Challenge Parameters
oaamPostAuth=true
oaamPreAuth=true
Protects OAAM-related resources with a default
context type. This scheme should be used when basic
integration with OAAM is required. Here, advanced
features like OTP are not supported. This is more of an
integration when mod_osso is used as the agent.
Table 22–21 (Cont.) Pre-configured Authentication Schemes
Scheme Name Specifications Purpose
Managing Authentication Schemes
22-70 Administrator's Guide for Oracle Access Management
OAM10gScheme Authentication Level: 2
Challenge Method: OAM10G
Authentication Module:
LDAPNoPasswordAuthModule
See Also
LDAPNoPasswordValidationScheme, earlier
in this table.
enableCoexistMode and disableCoexistMode
in the Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
Facilitates integration and coexistence with Oracle
Access Manager 10g. In the coexistence mode, Oracle
Access Manager 10g is the authenticator and Access
Manager 11g is the asserter.
This scheme requires challenge mechanism OAM10G,
specifically for OAM10g coexistence with OSSO as
described in "OAM10G" on page 22-74.
OAMAdminConsoleSch
eme
Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: default
Context Value: /oam
Authentication scheme for Oracle Access Management
Console.
OICScheme Authentication Level: 2
Challenge Method: DAP
Authentication Module: TAPModule
Context Type: External
Challenge Parameters:
TAPPartnerId=RPPartner
MatchLDAPAttribute=mail
Access Manager uses this scheme to delegate
authentication to Mobile and Social services and
redirects the user to the Mobile and Social login page
for authentication.
See Also: Part XI, "Managing Oracle Access
Management Mobile and Social"
OIFScheme
Only for Oracle Identity
Federation 11.1.1.
For Identity Federation
11.1.2, use
FederationScheme.
Authentication Level: 2
Challenge Method: DAP
Authentication Module: DAP
Context Type: External
This scheme delegates authentication to OIF, after
which, Oracle Identity Federation sends back a token
that is asserted by the OAM Server as described in the
Oracle Fusion Middleware Integration Guide for
Oracle Access Manager.
The Delegated Authentication Protocol (DAP)
challenge method is used to delegate authentication to
a third-party (OIF in this case).
Challenge Parameters: TAPPartnerId=OIFDAPPartner
See Also: "About Challenge Parameters for
Authentication Schemes" on page 22-75.
OIMScheme Authentication Level: 1
Challenge Method: FORM
Authentication Module: LDAP
Context Type: default
Context Value: /oam
Protects Oracle Identity Manager-related resources
with a default context type.
Note: When integrating OAM and OIM, OAM
downgrades the user's authentication level when any
of the following is detected:
password expiry
forced password change
challenge setup not done
This enables the user to access the pages only after
performing necessary operations in the identity
management (OIM) page to which the user is
redirected.
At Level 1, only public and OIM pages for the required
operations can be accessed.
Note: Authentication Level 1 is only one step higher
than 0 public pages. Oracle recommends that you do
not use Level: 1 in a custom authentication scheme.
OSSOCoexistMigrateSc
heme
Set as the Default authentication scheme for
environments that have been migrated from OSSO 10g
to Access Manager 11g.
See Also: Oracle Fusion Middleware Upgrade Guide
for Oracle Identity and Access Management.
Table 22–21 (Cont.) Pre-configured Authentication Schemes
Scheme Name Specifications Purpose
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-71
22.9.1.2 About Challenge Methods
Authentication involves determining what credentials a user must supply when
requesting access to a resource, gathering credentials over HTTP, and returning an
HTTP response that is based on the results of credential validation. Access Manager
provides the following credential challenge methods for use in an authentication
scheme:
■FORM
■BASIC
■X509
■WNA
■NONE
■DAP
■OAM10G
FORM
This authentication challenge uses an HTML form with one or more text input fields
for user credentials. In a typical form-based challenge, users enter a user name and
password in two text boxes on the form. The most common credential choices are user
name and password; however, you can use any user attributes: for example, user
name, password, and domain.
PasswordPolicyValidati
onScheme
Authentication Level: 2
Challenge Method: FORM
Authentication Module: Password Policy
Validation Module
Context: External
Enables password policy evaluation.
TAPResponseOnlySche
me
Authentication Level: 2
Challenge Method: DAP
Authentication Module: DAP
TAPScheme Authentication Level: 2
Challenge Method: DAP
Authentication Module: DAP
Context Type: External
To use TAPScheme for IDM product resources in the
IAM Suite Application Domain, Protected
HigherLevel Policy, the following configuration must
be done in addition to changing the Authentication
Scheme.
1. From the IAM Suite Application Domain,
Protected Higher Level Policy, remove
IAMSuiteAgent:/oamTAPAuthenticate.
2. Create a new Authentication Policy in the IAM
Suite Application Domain, that uses
LDAPScheme.
3. Protect IAMSuiteAgent:/oamTAPAuthenticate
using the newly created policy.
Challenge Parameters:
TAPPartnerId=TAPPartnerName
X509Scheme Authentication Level: 5
Challenge Method: X509
Authentication Module: X509
This authentication scheme is a certificate-based user
identification method. To use this method, a certificate
must be installed on the user's browser and the Web
server must be SSL-enabled.
Note: This scheme relies on SSL to deliver the use's
X.509 certificate to the OAM Server.
Table 22–21 (Cont.) Pre-configured Authentication Schemes
Scheme Name Specifications Purpose
Managing Authentication Schemes
22-72 Administrator's Guide for Oracle Access Management
A Submit button posts the content of the form. When the user clicks the Submit
button, the form data is posted to the Web server. OAM and OSSO Agents intercept
and process the form data. Upon validation of the user credentials collected in the
form, the user is authenticated.
You might want to use form-based authentication challenge for reasons such as:
■A consistent user experience: Using form-based login and a standardized logout
means that the user experience for login and logout features will be consistent
across browsers.
■A Custom Form: You can apply your organization's look and feel in the
authentication process.
For example, a custom form can include a company logo and a welcome message
instead of the standard user name and password window used in Basic
authentication.
■Additional Information: You can gather additional information at the time of
login.
■Additional Functionality: You can provide additional functionality with the login
procedure, such as a link to a page for lost password management.
BASIC
This built-in Web server challenge mechanism requires a user to enter her login ID and
password. The credentials supplied are compared to the user's definition in the LDAP
directory server. Thus, a Basic challenge relies on the LDAP Authentication Module
and user identity store associated with that module.
X509
With the X509 certificate challenge method, a user's browser must supply an X.509
digital certificate over SSL to the OAM Server through the Agent to perform
authentication.
The X.509 client certificate must be verified against the trusted CAs in the keystore
used by OAM Proxy and OAM Servers to ensure the validity of X.509 Client certificate
for authentication.
Note: This challenge method relies on an LDAP Authentication
Module and the user identity store associated with that module.
Note: If a URL is protected by Access Manager using Basic
Authentication with OID configured as the identity store, OID defined
users can not log in. To resolve this, add the following line before the
closing
</security-configuration>
tag in the
config.xml
file.
<enforce-valid-basic-auth-credentials>false
</enforce-valid-basic-auth-credentials>
Note: X509 is the challenge method for the X509Scheme. The user's
organization can determine how to obtain a certificate.
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-73
The following attributes of the X.509 certificate can be validated against the user
identity store associated with Access Manager:
■SubjectDN
■SubjectUniqueID
■Mail
■CN
To acquire the user entry, the X509 Authentication Module takes the attribute name of
the X.509 certificate to be validated and the LDAP attribute against which the search
will be launched. The expected result is the single user entry matching the criteria. If
the search returns no user entry, or more than one entry, authentication fails.
Authentication scheme parameters are located in oam-policy.xml.
The online certificate status protocol (OCSP) capabilities are also provided. Any
certificate passed for X.509 certificate-based authentication is validated using an OCSP
request. Administrators can configure the system to communicate with one or more
OCSP servers to retrieve the certificate status.
The X509 Authentication Module configuration for the OCSP responder URL indicates
whether OCSP validation is to be done. The value, if specified, indicates the URL for
validation of the X.509 client certificate using OCSP. No value indicates no OCSP
validation.
WNA
Uses Windows Native Authentication with Active Directory, and the Kerberos
Authentication Module.
NONE
The challenge method of None means that users are not challenged and do not need to
enter their credentials. This is used in the AnonymousScheme authentication scheme,
which allows users to access Access Manager-specific URLs that you do not want to
protect.
DAP
The Delegated Authentication Protocol (DAP) challenge method is required for
OIFScheme (Oracle Identity Federation 11.1.1 integration) with the DAP
authentication module and external context type (Table 22–20). The DAP challenge
mechanism indicates that Access Manager does an assertion of the token that it
Note: For X509 authentication, Administrators must configure the
Oracle HTTP Server as a reverse proxy (or a server with the wl-proxy
plug-in). The Oracle HTTP Server must be configured in two way SSL
Mode to acquire X.509 certificate for authentication. Oracle HTTP
Server can also be configured for CRL verification.
Note: The KerbScheme relies on the WNA challenge method and
Kerberos Authentication Module.
See Also: Chapter 57 for details about integration with Windows
Native Authentication
Managing Authentication Schemes
22-74 Administrator's Guide for Oracle Access Management
receives, which differs from the standard challenge "FORM" mechanism with the
external option.
DAPModule is an assertion module, though it is specialized for this one application
and does not appear in the list of Authentication Modules in the Oracle Access
Management Console. This integration replaces OSSO 10g with Access Manager 11g,
with no changes from the Identity Federation side.
The DAP challenge mechanism delegates authentication to a third party (Identity
Federation in this case). The challenge_url points to the Identity Federation Server
URL. When a resource is protected by this scheme, the OAM Server redirects to the
Identity Federation Server URL for credential collection. OAM Server does not
perform the credential collection or validation in this case. Identity Federation collects
the credentials, authenticates the user against its identity store and returns an assertion
token to the OAM Server consisting of the username. Access Manager receives and
decrypts this token, checks whether the user is a valid user in the default identity store
for Oracle Access Management. If the user is valid, Access Manager gives access to the
resource.
The DAPToken is encrypted and decrypted with a key that is shared between Access
Manager and Identity Federation. The DAPToken is built from the Access Manager
side.
The Identity Federation Administration EM Console provides a way to generate the
keystore containing the encryption keys that will be used to secure communications
between the Access Manager and Identity Federation. Access Manager provides a
WLST command (
registerOIFDAPPartner
), that takes the keystore location generated
by the Identity Federation store and retrieves the keys and stores it on the Identity
Federation side.
OAM10G
This mechanism is created for Oracle Access Manager 10g coexistence with OSSO 10g.
The OAM10G method always acts as the authentication and authorization provider
and is required for OAM10gScheme with the LDAPNoPasswordAuthModule to
facilitate trust when you have Oracle Access Manager 10g protecting a domain that
also includes an OSSO 10g integrated classic application (Portal, Disco, and so on).
OSSO10g is protected with OAM10G challenge method through Webgate; OAM10G
always acts as the authentication and authorization provider.
Facilitating Integration: The OSSO 10g integrated classic applications can be
upgraded to Access Manager, which then acts only as an asserter. Access Manager
creates the tokens that mod_osso can consume so that access can be provided to these
applications. The mod_osso applications are protected by the new "OAM10gScheme".
There is a Webgate front ending the OAM Server and configured against the 10g
Access Server.
Setup: When the resource is accessed, Webgate intercepts the request and sends it to
the 10g Access Server for authentication. Oracle Access Manager 10g collects the
credentials, validates it against its identity store, and sets the username as a header
variable (OAM_REMOTE_USER). The request now goes to the OAM Server which
uses the OAM10gScheme to locate the username in the header variable. Access
Manager retrieves the header variable and asserts the presence of the user against the
primary identity store. If present, the required cookies (OAM_ID) are generated and
redirected to the resource.
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-75
22.9.1.3 About Challenge Parameters for Authentication Schemes
Challenge parameters are short text strings consumed and interpreted by Webgates
and Credential Collector modules to operate in the manner indicated by those values.
The syntax for specifying any challenge parameter is:
<parmatername>=<value>
This syntax is not specific to any Webgate release (10g versus 11g). Authentication
schemes are independent of Webgate release.
Table 22–22 identifies the pre-configured schemes with challenge parameters.
An authentication scheme can collect context-specific information before submitting
the request to the Access Server. Context-specific information can be in the form of an
external call for information. Table 22–23 lists user-defined challenge parameters you
can use in Authentication Schemes.
See Also:
■OAM10gScheme in Table 22–21
■
enableCoexistMode
and
disableCoexistMode
in the Oracle Fusion
Middleware WebLogic Scripting Tool Command Reference
Table 22–22 Challenge Parameters in Pre-configured Schemes
Pre-configured Schemes Challenge Parameter
BasicSessionlessScheme CookieLessMode=true
Primarily used for clients that do not support URL redirect or cookies.
FederationMTScheme initial_command=NONE
Primarily used for Fusion Applications that support multiple factor authentication.
is_rsa=true
Used with RSA multi-step authentication, as described in Chapter 56, "Integrating RSA
SecurID Authentication with Access Manager" and the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management.
FederationScheme
For Identity Federation 11.1.2.only.
Use OIFScheme for Oracle Identify
Federation 11.1.1.
Primarily used for clients that do not support URL redirect or cookies.
Context Value: /fusion_apps
Challenge Parameters: initial_command=NONE
is_rsa=true
Primarily used for clients that do not support URL redirect or cookies.
OAAMBasic oaamPostAuth=true
oaamPreAuth=true
Protects OAAM-related resources. These parameters should be used when basic
integration with OAAM is required.
OIFScheme
For Oracle Identify Federation 11.1.1
only. Use FederationScheme for
Identity Federation 11.1.2.
TAPPartnerId=OIFDAPPartner
This scheme delegates authentication to Oracle Identity Federation 11.1.1, after which,
Federation sends back a token that is asserted by the OAM Server.
TapScheme TAPPartnerId=TAPPartnerName
Managing Authentication Schemes
22-76 Administrator's Guide for Oracle Access Management
Table 22–23 User-Defined Challenge Parameters for Authentication Schemes
Challenge Parameter Definition
initial_command=NONE Required to enable the plug-in to indicate which credentials are to be collected.
For example, for Form-based authentication, the framework typically expects to collect
"username" and "password" (submitted from the login page). However, you might want
credentials from different fields of the login page; "form_username" and "form_password" for
example. Setting this challenge parameter shifts initial control from the login page to the
plug-in, which decides the parameters to collect from the login page then appropriately
forwards or redirects to the page.
Default: blank (not set)
action= The actions parameter identifies the URL to which the HTML form is posting when you do not
want to use the hard coded ECC default
/oam/server/auth_cred_submit
.
Note: ECC does not use the
action=
parameter. When the
action=
challenge parameter is not
specified, both the DCC and ECC use the default:
/oam/server/auth_cred_submit
.
See Also: "Configuring the PasswordPolicyValidationScheme"
creds=
DCC Only
Supported by the detached credential collector (DCC) only.
In the following 11g example, username and password are the names of relevant fields in the
login form:
creds=username password
NOTE: Format of this challenge parameter has changed since the 10g release.
The Web server source (server parameter) takes precedence over other sources. This prevents
the request data, which is under control of the user, from overriding Web server data. For
example, a remote_user cookie sent from a user will not override a remote_user variable set by
the Web server
Generally, when the user submits a login form that is protected by an authentication scheme
with a Form-based challenge method, the DCC processes the credentials that were specified
with this
creds=
parameter.
For forms using METHOD=POST processing, the browser sends a POST request to the Web
server with the credential data from the form in the body of the request. If the form uses
METHOD=GET, the browser sends a GET request with query string parameters with the same
names as those specified on the creds parameter. Oracle recommends that you use POST
processing, if possible.
Note: You can specify the
creds
parameter with the other types of challenge methods. For a
plug-in to make use of the
creds
parameter, you specify what is passed in the obMap
credentials parameter of the ObUserSession object, as described in the Oracle Fusion
Middleware Developer's Guide for Oracle Access Management.
See Also: "Configuring the PasswordPolicyValidationScheme"
extracreds=
DCC Only
Supported by the DCC only. Specifies optional parameters which, if present, are made available
to the authentication plug-in for collection during each iteration of a multi-step authentication
using the DCC.
The
extracreds
parameter uses the same syntax as the
creds
parameter:
extracreds
=
separated qualified or unqualified names [{any | cookie | header | server | query | post}:]
<name>. However, the value
any
is used by
extracreds
only. For example:
extracreds=[{any | cookie | header | server | query | post}:] <name>
See Also: "Configuring the PasswordPolicyValidationScheme"
OverrideRetryLimit=0 The number of tries that can override the RetryLimit for login.
The value must be a positive integer.
A value of zero (0) disables this function.
See Also: "Configuring the PasswordPolicyValidationScheme"
ChallengeRedirectMethod Authentication POST data preservation parameter for both the embedded credential collector
(ECC) and the detached credential collector (DCC).
Value: GET|POST|DYNAMIC
Note: Preference is given first to the Authentication Scheme containing this parameter; second
to the Webgate providing this user defined parameter. Otherwise, default behavior is Dynamic.
See Also: "Configuring Authentication POST Data Handling"
Table 15–2, " User-Defined WebGate Parameters"
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-77
MaxPreservedPostDataBytes Configure this Authentication Scheme challenge parameter (or user-defined Webgate
parameter) for authentication POST-data preservation.
Default: 8192 bytes
Note: Preference is given first to the Authentication Scheme containing this parameter; second
to the Webgate providing this user-defined parameter. Otherwise, default behavior is 8192
bytes.
This parameter defines the maximum length of POST data that Webgate can preserve. If the size
of inbound raw user POST data (or encrypted post data after processing), crosses this limit,
POST data is dropped and the existing authentication flow continues. The event is logged as
usual.
See Also: "Configuring Authentication POST Data Handling" on page 22-94
Table 15–2, " User-Defined WebGate Parameters"
MaxPostDataBytes=
DCC Only
Configure this Authentication Scheme challenge parameter to restrict the maximum number of
bytes of POST data that is submitted as user credentials and sent to the OAM Server.
Configure this challenge parameter for POST-data preservation by the DCC only to limit the
maximum size of the POST data that can be posted as credentials on the form and sent to the
OAM Server. DCC compares the value of the content-length header with the limit set.
Default: 8192 bytes
This challenge parameter requires a positive integer value.
See Also:
Table 15–2, " User-Defined WebGate Parameters"
"Configuring the PasswordPolicyValidationScheme"
"Configuring Authentication POST Data Handling" on page 22-90
ssoCookie= Controls the OAMAuthnCookie cookie, as described in "Configuring Challenge Parameters for
Encrypted Cookies" on page 22-88.
Default:
ssoCookie=httponly
ssoCookie=Secure
Disable either setting:
ssoCookie=disablehttponly
ssoCookie=disableSecure
Note: These parameters are configured differently depending on your credential collector
configuration.
■For detached credential collector-enabled 11g Webgates, set these parameters directly in
the agent registration page.
■For non-DCC agents (Resource Webgates), these parameters are configured through
user-defined challenge parameters in authentication schemes.
See Also:
Table 22–30, " Challenge Parameters for 10g/11g Encrypted Cookies"
Table 22–23 (Cont.) User-Defined Challenge Parameters for Authentication Schemes
Challenge Parameter Definition
Managing Authentication Schemes
22-78 Administrator's Guide for Oracle Access Management
miscCookies= Controls other miscellaneous Access Manager internal cookies. By default, httponly is enabled
for all other (miscellaneous) cookies.
Default:
miscCookies=httponly
miscCookies=Secure
Disable either setting:
miscCookies=disablehttponly
miscCookies=disableSecure
Note: These parameters are configured differently depending on your credential collector
configuration.
■For detached credential collector-enabled Webgates, set these parameters directly in the
agent registration page.
■For non-DCC agents (Resource Webgates), these parameters are configured through
challenge parameters of the same name.
See Also:
Table 22–30, " Challenge Parameters for 10g/11g Encrypted Cookies"
"Configuring the PasswordPolicyValidationScheme"
DCCCtxCookieMaxLength=
DCC Only
Defines the maximum length of the DCC cookie.
Default: 4096
See Also: TempStateMode in this table for more information.
Table 22–23 (Cont.) User-Defined Challenge Parameters for Authentication Schemes
Challenge Parameter Definition
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-79
22.9.2 Understanding Multi-Level and Step-Up Authentication
This section provides the following topics:
■About Multi-Level and Step-Up Authentication
■Detection of Insufficient Authentication Level by OAM Agent
■Multi-Level Authentication Processing with 10g OSSO Agent
TempStateMode= Controls how the DCC stores the OAM Server state (cookie or form) as specified with the
parameter's value:
■form: This is the default, and is required for retaining authentication POST data. The OAM
Server state stored and passed through the form parameter "OAM_REQ", to avoid the case
when the OAM Server configuration
serverRequestCacheType=COOKIE
, bloated server
state causes DCCCtxCookie to explode beyond limit resulting in incorrect behavior.
The cookie cache mode can be changed to
FORM
mode from default
COOKIE
mode.
FORM
mode works with long URLs. The only difference in behavior is for programmatic
authentication, which requires a proper form Submit to pass the
OAM_REQ
parameter set to
the form. Custom credential collection pages need to handle the
OAM_REQ
parameter that is
submitted with the form.
■cookie: Adding this parameter and value stores the OAM Server state through part of the
DCCCtxCookie
(
encdata=… svrctx=…)
. However, when
serverRequestCacheType=COOKIE
or =FORM
, this could cause incorrect behavior if the resulting cookie length is beyond
browser limit.
Note:
■When
serverRequestCacheType=COOKIE
, Oracle recommends TempStateMode=form.
■When
serverRequestCacheType=BASIC
, either mode is fine.
To update
serverRequestCacheType
, use the WLST command configRequestCacheType as
described in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Editing
serverRequestCacheType
is not supported using the Oracle Access Management
Console.
With ECC: The serverRequestCacheType dictates whether OAM Server stores its state in
memory(BASIC) or not (FORM or COOKIE). serverRequestCacheType = COOKIE or FORM
only makes difference when ECC is used. OAM Server stores its state in a request token, which
ECC keeps in a cookie or hidden form field as specified with the parameter:
serverRequestCacheType=COOKIE, for example.
With DCC: There is no difference between serverRequestCacheType=COOKIE or FORM.
TempStateMode controls how the DCC stores the OAM Server state (cookie or form) as
specified with the parameter's value: TempStateMode=cookie, for example. With the DCC,
POST data restoration with a Form-based Authentication Scheme requires the challenge
parameter TempStateMode=form.
See Also:
■Configuring 11g WebGates and Authentication Policy for DCC
■Table 15–2, " User-Defined WebGate Parameters"
■" Parameters Required for Authentication POST Data Handling"
■"Configuring the PasswordPolicyValidationScheme"
allowedAccessGateList= Authentication Scheme challenge parameter configured with SPACE separated list of WebGate
IDs defining those WebGates that are allowed to enforce authentication by this scheme. For
example:
allowedAccessGateList=WebgateID1 WebgateID2
TunneledUrls ■For OAM : TunneledUrls=/oam
■For OAAM : TunneledUrls=/oam/server/obrareq.cgi,/oam/server/dap/cred_submit
■For OIF : TunneledUrls=/oamfed
■For OIM : TunneledUrls=/oam
Table 22–23 (Cont.) User-Defined Challenge Parameters for Authentication Schemes
Challenge Parameter Definition
Managing Authentication Schemes
22-80 Administrator's Guide for Oracle Access Management
22.9.2.1 About Multi-Level and Step-Up Authentication
Every authentication scheme requires a strength level. The higher the number, the
more more secure the authentication mechanism; the lower the number, the less
stringent the scheme. For example:
■LDAPScheme authLevel=1
■KerbScheme authLevel=3
SSO capability enables users to access more than one protected resource or application
with a single sign in. After a successful user authentication at a specific level, the user
can access one or more resources protected by one or more Application Domains.
However, the authentication schemes used by the Application Domains must be at the
same level (or lower). When a user accesses a resource protected with an
authentication level that is greater than the level of his current SSO token, he is
re-authenticated. In the step-up case, the user maintains his current level of access
even if failing the challenge presented for the higher level. This is "additional
authentication".
Access Manager policies allow different resources of the same application to be
protected with different authentication levels.
In such cases, the application must enforce the Level and send the Dynamic Directive
to mod_osso for re-authentication. On receiving the Dynamic Directive, mod_osso will
redirect to Access Manager for re-authentication at the appropriate level.
Both agent types redirect the user to the OAM Server to authenticate again. The
challenge is presented according to the level of the authentication scheme configured
in the policy for the resource.
Registered agents detect the authentication level as follows:
■OAM Agents receive an insufficient level error message from the OAM Server, as
described in "Detection of Insufficient Authentication Level by OAM Agent" on
page 22-81.
■mod_osso detects the authentication level from dynamic directives, as described in
Multi-Level Authentication Processing with 10g OSSO Agent on page 22-81.
Note: Multi-level authentication does not affect, negate, or alter
X.509 certificate authentication.
Note: A user who is authenticated to access resources at level 3, is
eligible to access resources protected at levels less than or equal to 3.
However, if the user is authenticated to access resources at level 2 and
then attempts to access resources protected by level 3, the user is
asked to re-authenticate (this is known as step-up authentication).
Note: mod_osso delegates authentication to Access Manager. Oracle
recommends that mod_osso-protected resources be protected with
Access Manager authentication levels. the mod_osso plug-in does not
support two resources on the same application with a different trust
level.
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-81
22.9.2.2 Detection of Insufficient Authentication Level by OAM Agent
When the user requests a resource that is protected with a higher level authentication
scheme, the following process occurs.
Process overview: OAM Agent detects insufficient session level
No check of the authentication level is made on the server side. The following example
refers to a 10g OAM Agent.
1. The OAM Agent sends the request to the OAM Proxy to obtain the scheme details
for the protected resource.
2. The OAM Agent sends the request for session information to the OAM Proxy.
3. The OAM Proxy returns details of the ObSSOCookie, including the authenticated
level of the ObSSOCookie.
4. The OAM Agent compares the level of ObSSOCookie with that of the
authentication scheme.
■If insufficient, the agent invokes the authentication process again.
■If sufficient, the access is granted access.
22.9.2.3 Multi-Level Authentication Processing with 10g OSSO Agent
In contrast to OAM Agents, all the resources protected by mod_osso on a host (or
virtual host) are protected at the same level.
With mod_osso, multi-level authentication applies when user is already authenticated
using one mod_osso host (or virtual host) at Level 2 and then tries to access another
mod_osso protected host (or virtual host) at level 3.
Process overview: OSSO Agent multi-level authentication flow
1. The user tries to access a resource protected by mod_osso on host1 at level 2.
2. The OSSO Agent sends the request to the OAM Proxy to obtain the authentication
scheme details for the protected resource.
3. The OAM_ID cookie for SSO Server and a host based cookie "HOST_port" for
host1 are set and contain authentication level information.
See Also: Oracle Fusion Middleware Integration Guide for Oracle
Identity Management Suite; for example, the chapter Integrating
Access Manager and Oracle Adaptive Access Manager. The user was
already authenticated when he accessed another resource with a lower
authentication level using Access Manager. Oracle Adaptive Access
Manager does not show the user name and password pages because
the user is already authenticated. However, the flows that are
executed in Oracle Adaptive Access Manager depend on whether the
user was already logged in to Oracle Adaptive Access Manager.
See Also: "Understanding Authentication Methods and Credential
Collectors" on page 22-18
Note: 11g OAM Agents are associated with individual per-agent
OAMAuthnCookies.
Managing Authentication Schemes
22-82 Administrator's Guide for Oracle Access Management
4. After authentication, the user tries to access a resource on host2 that is protected
with a higher level of authentication.
5. The user is redirected to the OAM Server for authentication because this is the first
time accessing host2.
6. The OAM Server (OSSO Proxy) receives the OAM_ID cookie which has an
insufficient level to access the resource on host2.
■If the level is insufficient, the OAM Server (OSSO Proxy) triggers
re-authentication.
■If the level is sufficient, the access is granted access.
22.9.3 Creating an Authentication Scheme
Users with valid Administrator credentials can use the following procedure to add a
new authentication scheme for use in an Application Domain.
Prerequisites
The authentication module must be defined and ready to use as described in
"Deploying and Managing Individual Plug-ins for Authentication" on page 22-58.
To create an authentication scheme
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security Console, click Authentication Schemes in the Access
Manager section.
3. Click the Create Authentication Scheme.
4. Fill in the fresh Authentication Scheme page (Table 22–20) by supplying
information based on your deployment:
a. Name: LDAPSimpleFormScheme
b. Authentication Level
c. Challenge Method: FORM
d. Challenge Redirect URL: http://CredentialCollectorhost:port
e. Authentication Module: LDAP
f. Challenge URL: /CredentialCollector/loginform...
g. Challenge Parameters: Table 22–22, Table 22–23, Table 22–30
h. Context Type
5. Click Apply to submit the new scheme (or close the page without applying
changes).
6. Dismiss the Confirmation window.
7. Optional: Click the Set as Default button to automatically use this with new
Application Domains, then close the Confirmation window.
See Also:
■"About Authentication Schemes and Pages" on page 22-65
■Configuring 11g WebGates and Authentication Policy for DCC if
needed
Managing Authentication Schemes
Managing Authentication and Shared Policy Components 22-83
8. Confirm the new scheme appears in the list of schemes (refresh if needed).
9. Proceed to "Defining Authentication Policies for Specific Resources" on page 25-31.
22.9.4 Searching for an Authentication Scheme
Users with valid Administrator credentials can perform the following task to search
for a specific authentication scheme.
To search for an authentication scheme
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security Console, click Authentication Schemes in the Access
Manager section.
3. In the Name field, enter the target scheme name (with or without wild card *). For
example:
OA*
4. Click the Search button to initiate the search.
5. Click the Search Results tab to display the results table, and then:
■Edit: Click the Edit button in the tool bar to display the configuration page.
■Delete: Click the Delete button in the tool bar to remove the instance; confirm
removal in the Confirmation window.
■Detach: Click Detach in the tool bar to expand the table to a full page.
■View: Select a View menu item to alter the appearance of the results table.
22.9.5 Viewing, Editing, or Deleting an Authentication Scheme
Users with valid Administrator credentials can use the following procedure to view or
modify an existing authentication scheme.
To view or modify an authentication scheme
1. Search for the target scheme, as described in the previous section.
2. In the list of search results, select the target scheme and click Edit.
3. Edit:
a. On the Authentication Scheme page, modify values for your environment
(Table 22–20).
See Also: "Conducting A Search"
Note: During a delete operation, if the Authentication Scheme is
associated with any authentication policy, she is prompted with
association details. Without policy associations, the scheme is deleted.
See Also:
■"About Authentication Schemes and Pages"
■"Configuring the PasswordPolicyValidationScheme"
Extending Authentication Schemes with Advanced Rules
22-84 Administrator's Guide for Oracle Access Management
b. Click Apply to submit the changes (or close the page without applying
changes).
c. Dismiss the Confirmation window.
4. Set as Default: Click the Set as Default button to automatically use this scheme
when creating policies in fresh Application Domains, then close the Confirmation
window.
5. Delete:
a. Review any Application Domain using this authentication scheme and assign
a different scheme.
b. Review the Authentication Scheme page to confirm this is the scheme to
remove, then close the page.
c. In the navigation tree, click the name of the scheme and then click the Delete
button in the tool bar.
d. Confirm removal (or dismiss the Confirmation window).
22.10 Extending Authentication Schemes with Advanced Rules
Advanced Rules have been added to allow for extending an existing authentication
policy. Both Pre-Authentication and Post-Authentication rules can be applied although
the following configurations are not supported by Post-Authentication Rules.
■Two or more resources front ended by the same OHS/WebGate and protected by
the same Authentication Scheme.
■A Post-Authentication rule configured for one of the resources defined in step up
authentication.
■A user accesses a resource for which no Post-Authentication rule is configured
followed by a resource for which a Post-Authentication rule is configured for step
up authentication. In this case, the Post-Authentication rule configured for the
resource is not effective.
Advanced Rules contain Boolean expressions. If there is more than one triggered
outcome to an Authentication Scheme, the lowest execution order outcome will be
chosen as the final outcome. Table 22–24 documents the attributes that need be defined
when creating an Advanced Rule.
Note: In an upgraded deployment with OSSO Agents, change the
Authentication Scheme and any Protected Resource Policies to use
SSOCoExistMigrateScheme.
Note: Advanced Rules are part of the Adaptive Authentication
Service for which a license is required. See Section 35.1, "Using the
Adaptive Authentication Service."
Table 22–24 Advanced Rules Attributes
Name Description
Name AuthnRule name. Name has to be unique within the checkpoint
Description Description of the rule
Extending Authentication Schemes with Advanced Rules
Managing Authentication and Shared Policy Components 22-85
See the following sections for details.
■Using Advanced Rules
■Using Context Data for Advanced Rules
22.10.1 Using Advanced Rules
Advanced Rules can be configured for the following use cases.
■Non Browser Client - For user authentication, a form-based login page is
presented through the browser for the user to complete. In some cases, a
non-browser client (switches, routers and the like) might need to do basic
authentication based on credentials passed via the request header. Non-browser
client authentication can be configured as a pre-authentication Advanced Rule
only. To support non-browser client authentication, configure the desired
condition in an Authentication Rule (based on the HTTP request header's
availability) and set the desired outcome.
■Windows Native Authentication Option - An Advanced Rule can be configured to
allow for switching between Windows Native Authentication (WNA) and
form-based user authentication depending on whether the user comes thru VPN
or a corporate network.
■User Authentication Scheme Option - An Advanced Rule can be configured to
allow the user to choose the method of authentication. The choice would be
passed as a request parameter.
■Second Factor Authentication - An Advanced Rule can be configured to allow for
Second Factor Authentication (SFA) based on defined user or request attributes.
For details on SFA, see Chapter 35, "Introducing the Adaptive Authentication
Service."
Table 22–25 contains examples of how the conditions might be configured in these
Advanced Rules use cases.
Execution Order Order in which the outcome will be executed in cases of more than 1
outcome
Condition Script; the user can configure condition based on the HTTP request
header's availability and set the desired outcome
Outcome ID of the Authentication Scheme to which the rule applies. Access / Deny.
Table 22–25 Sample Advanced Rules
Sample Rule
Sample Jython Script-based
Condition Notes
Switching authentication
scheme based on private or
public IP rule
location.clientIP.startswith('10.') or
location.clientIP.startswith('172.16') or
location.clientIP.startswith('192.168')
This rule can be used in
Pre and Post
authentication
checkpoints
Black listed IP location.clientIP in ['130.35.50.115',
'130.35.50.112', '130.35.50.113']
This rule can be used in
Pre and Post
authentication
checkpoints
Table 22–24 (Cont.) Advanced Rules Attributes
Name Description
Extending Authentication Schemes with Advanced Rules
22-86 Administrator's Guide for Oracle Access Management
22.10.2 Using Context Data for Advanced Rules
Before executing the Authentication Condition, the Access Manager server prepares a
request context using the available data (to construct a Boolean expression based
condition). The following tables describe the various context data details.
■Table 22–26, " Request Context Data"
■Table 22–27, " Location Context Data"
■Table 22–28, " Session Context Data"
■Table 22–29, " User Context Data"
Client Browser Type request.userAgent.lower().find('firefo
x') > 0
This rule can be used in
Pre and Post
authentication
checkpoints
Blocking access to user
having user attribute
'description' equals 'test'
user.userMap['description'] == 'test' This rule can be used
only in Post
authentication
checkpoints
Non browser client request.authorization.lower().startswi
th('basic')
This rule can be used
only in Pre
authentication
checkpoints
Customer HTTP Header
value
request.requestMap['param'] == 'test' This rule can be used in
Pre and Post
authentication
checkpoints
Switching authentication
scheme based on IP address
in range
location.isIPinRange('192.35.50.180','1
92.35.50.188')
This rule can be used in
Pre and Post
authentication
checkpoints
Table 22–26 Request Context Data
Attribute Name Description
requestMap Map of all the request headers, parameters and post data values.
This example can get the custom-header key from request
header and compare it with value 'test'.
request.requestMap['custom-header'].lower().find('test') > 0
resourceMap Map of matched resource details
accept Returns 'Accept' header value
acceptCharset Returns 'Accept-Charset' header value
acceptEncoding Returns 'Accept-Encoding' header value
acceptLanguage Returns 'Accept-Language' header value
authorization Returns 'Authorization' header value
connection Returns 'Connection' header value
contentLength Returns 'ContentLength' header value
cookie Returns 'Cookie' header value
Table 22–25 (Cont.) Sample Advanced Rules
Sample Rule
Sample Jython Script-based
Condition Notes
Extending Authentication Schemes with Advanced Rules
Managing Authentication and Shared Policy Components 22-87
host Returns 'Host' header value
ifModifiedSince Returns 'ifModifiedSince' header value
pragma Returns 'Pragma' header value
referer Returns 'Referer' header value
userAgent Returns 'UserAgent' header value
resourceHost Returns matched Resource's Host value
resourcePost Returns matched Resource's Port value
resourceOperation Returns matched Resource's Operation value
resourceQueryString Returns matched Resource's QueryString
resourceName Returns matched Resource's name
resourceType Returns matched Resource's Type
resourceURL Returns matched Resource's URL; for example, if 'landingPage'
is in request.resourceURL, condition will evaluate to true if
resourceURL has landingPage in it.
isIPinRange('start IP' ,'end
IP')
Evaluates to true if location.clientIP is in the specified range.
Example:
location.isIPinRange('192.35.50.180','192.35.50.188')
Table 22–27 Location Context Data
Attribute Name Description
locationMap Map of all the location data values; for example:
location.locationMap['CLIENT_IP'] == '10.1.23.4'
clientIP Returns client IP address; for example:
location.clientIP.startswith('10.2')
proxyIP Returns Proxy IP address
Table 22–28 Session Context Data
Attribute Name Description
sessionMap Map of all the session data values; for example:
session.sessionMap['count'] > 2;
count Returns number of sessions for the current user; for example:
session.count > 2
Table 22–29 User Context Data
Attribute Name Description
userMap Map of all the user profile data; for example:
user.userMap['email'] == 'john.joe@example.com'
Table 22–26 (Cont.) Request Context Data
Attribute Name Description
Configuring Challenge Parameters for Encrypted Cookies
22-88 Administrator's Guide for Oracle Access Management
22.11 Configuring Challenge Parameters for Encrypted Cookies
This section provides the following topics:
■About Challenge Parameters for Encrypted Cookies
■Configuring Challenge Parameters for Security of Encrypted Cookies
■Setting Challenge Parameters for Persistence of Encrypted Cookies
22.11.1 About Challenge Parameters for Encrypted Cookies
In addition to the OAM Server cookie (OAM_ID), Access Manager implements single
sign-on through an encrypted cookie:
■11g Webgate, One per agent: OAMAuthnCookie_<host:port>_<random number>
set by Webgate using the authentication token received from the OAM Server after
successful authentication
Note: A valid OAMAuthnCookie is required for a session.
■10g Webgate, One ObSSOCookie for all 10g Webgates.
Access Manager provides the
ssoCookie
challenge parameter that you can use within
any authentication scheme to control how Webgates set the flags of the encrypted
cookie. For example:
■Securing Encrypted Cookie: Ensures that the encrypted cookie is sent only over
an SSL connection and prevents the encrypted cookie from being sent back to a
non-secure Web server.
■Persisting Encrypted Cookie: Allows the user to log in for a time period rather
than a single session. Persistent cookie functionality works with Internet Explorer
and Mozilla browsers.
Table 22–30 describes specific challenge parameters that control how Webgates set
encrypted cookie flags for single sign-on.
Note: The value of the challenge parameter is note case sensitive.
Syntax is the same regardless of your Webgate release. A single value
is specified after the equal sign (=):
ssoCookie=value
Multiple values must be separated by a semicolon (;). For example:
ssoCookie=value1;value2;...
■For detached credential collector-enabled Webgates, set these
parameters directly in the agent registration page (Table 15–2).
■For non-DCC agents (Resource Webgates), these parameters are
configured through Authentication Scheme challenge parameters
(Table 22–30).
Table 22–30 Challenge Parameters for 10g/11g Encrypted Cookies
11g /10g Webgate Challenge
Parameter Syntax for Encrypted
Cookies Description
ssoCookie=
Parameter that controls flags for the SSO cookie OAMAuthnCookie.
Configuring Challenge Parameters for Encrypted Cookies
Managing Authentication and Shared Policy Components 22-89
22.11.2 Configuring Challenge Parameters for Security of Encrypted Cookies
The challenge parameter is not case sensitive.
To secure the encrypted cookie
1. Create an authentication scheme.
2. In the Challenge Parameter field, enter your specification for the desired
encrypted cookies (Table 22–30).
3. Confirm that the OAM Servers and clients (OAM Agents) are communicating
securely across the Oracle Access Protocol channel, as described in Appendix C.
22.11.3 Setting Challenge Parameters for Persistence of Encrypted Cookies
The challenge parameter is not case sensitive.
To define encrypted cookie persistence
1. Define an authentication scheme.
2. In the challenge parameter for this scheme, add the following (Table 22–30):
WebGate
ssoCookie=max-age=
time-in-seconds
miscCookies=
Parameter that controls flags for all other Access Manager encrypted
cookies.
Secure
Ensures that the encrypted cookie is sent only when the resource is
accessed through HTTPS. A secure cookie is required only when a
browser is visiting a server using HTTPS.
ssoCookie=Secure
miscCookies=Secure
disableSecure
Explicitly disables Secure cookies.
ssoCookie=disableSecure
miscCookies=disableSecure
httponly
Enabled by default with 11g Webgate SSO OAMAuthnCookie and
miscellaneous cookies.
ssoCookie=httponly
miscCookies=httponly
disablehttponly
Explicitly disables
httponly
functionality, making the encrypted
cookies accessible to client-side scripts.
ssoCookie=disablehttponly
miscCookies=disablehttponly
ssoCookie=max-age=time-in-secon
ds
Creates a persistent cookie in browsers, rather than one that lasts for
a single session, and specifies the time interval in-seconds when the
cookie expires.
For example, to set the cookie to expire in 30 days (2592000 seconds):
max-age=2592000
See Also: "Creating an Authentication Scheme" on page 22-82
See Also: "Creating an Authentication Scheme" on page 22-82
Table 22–30 (Cont.) Challenge Parameters for 10g/11g Encrypted Cookies
11g /10g Webgate Challenge
Parameter Syntax for Encrypted
Cookies Description
Configuring Authentication POST Data Handling
22-90 Administrator's Guide for Oracle Access Management
22.12 Configuring Authentication POST Data Handling
Post data preservation and restoration functions apply to both credential collectors
(ECC or DCC). This section provides the following topics:
■About Authentication Post Data Preservation and Restoration
■About Configuring Authentication POST Data Handling
■Configuring Authentication POST Data Handling
■Testing POST Data Handling Configuration
22.12.1 About Authentication Post Data Preservation and Restoration
POST data preservation and restoration functions come into play when an application
has a form wherein the user has entered a credential (or other data) but the session has
expired, an idle session timeout has occurred, or the token validity period has ended
by the time the user submits the form. If this scenario occurs, the user is presented
with a fresh login form (depending on the authentication scheme) unless POST data is
preserved and restored.
Administrators can configure the Resource Webgate to perform POST data
preservation when the expired user and newly authenticated user are the same.
Table 22–31 describes Resource Webgate support and behavior for post data.
Note: Authentication POST data preservation and restoration is not
supported when Access Manager performs authentication through
custom agents.
Table 22–31 Resource Webgate Support of POST Data Preservation and Restoration
Resource Webgate Description
Supports Authentication
Schemes
LDAP, Basic, Sessionless Basic, X509, WNA
Supports form encoding with text/html, text/plain, multipart/form-data, and
application/x-www-form-urlencoded type data posted by the
application form.
Preserves The encoding type of the data posted by the original application form,
except the input field of file type.
Ensures The downstream application sees the same post data that was posted by
the original application form.
Constrains The overall size of the inbound request data or the inbound front channel
message. There shall be a configuration parameter to override the code
default value. This shall be per application.
Maintains application data
confidentiality and integrity
Neither the Resource Webgate nor credential collector will interpret, nor
log, application post data.
If, after expiration and during re-authentication, the user authenticates
with different credentials, then the post data of the previous user is
cleared by the Resource Webgate and not restored. However, Webgate
will post to the downstream application URL that was posted by the
original application form.
Configuring Authentication POST Data Handling
Managing Authentication and Shared Policy Components 22-91
Table 22–32 describes credential collector feature support for POST data handling.
22.12.2 About Configuring Authentication POST Data Handling
Table 22–33 summarizes the authentication schemes that support authentication POST
data handling.
Ignores Preservation if ...
Logs a Message when ...
Performs Standard
Authentication if ...
Shows an Error when ...
Post data is larger than the configured or hard-coded limit, preservation
is ignored.
Post data is skipped because it is bigger than the allowed limit, a
message is logged.
Post data size is larger than the hard-coded limit (or the configured
value), the standard authentication flow is used.
Together, if both front channel message data and application post data
are large an error occurs.
Table 22–32 Credential Collector Support for POST Data Handling
Credential Collector Support
ECC and DCC
Compatible with earlier 11g Webgates
Supports post data preservation for Form based authentication scheme with the default login form
provided out of the box.
Preserves application post data during authentication processing by:
■Challenging the user
■Re-challenging the user if invalid credentials are provided
Does not interpret application post data.
Constrains the overall size of inbound front-channel messages using a configuration parameter to override
the default value, per application.
Logs a warning when post data is skipped because it is larger than the allowed limit.
Does not preserve application post data when:
■Authentication policy is configured with Success or Failure authentication URLs
■Password management (password expiration and so on) is involved
■Access Manager is used for performing authentication through custom agents.
ECC Only
■The embedded credential collector does not support POST data handling with the external login
page.
DCC Only
■POST data is preserved through the HTTP header, and the amount of POST data that can be handled
to 8192 characters.
■POST data restoration with a Form-based Authentication Scheme requires the challenge parameter
TempStateMode=form.
■DCC does not support custom login pages.
■DCC does not support POST data restoration during password management operations (password
expiration, for instance) when the URL_ACTION in the password policy plug-in is set to anything
other than FORWARD.
Table 22–31 (Cont.) Resource Webgate Support of POST Data Preservation and
Resource Webgate Description
Configuring Authentication POST Data Handling
22-92 Administrator's Guide for Oracle Access Management
Table 22–34 summarizes complete configuration requirements for authentication POST
data handling. All requirements described in Table 22–34 are supported end to end
with the authentication schemes in Table 22–33.
Table 22–33 Authentication Schemes Supporting POST Data Handling
Authentication Schemes
■FORM challenge method, supported with the out of the box login page.
■WNA
■Basic
■Basic+Sessionless
■X509
■OIF, OIM, OAAM integrations using TAP
Table 22–34 Parameters Required for Authentication POST Data Handling
Parameter Description
MaxPostDataBytes Configure this Authentication Scheme challenge parameter for
POST-data preservation used by the DCC only to limit the maximum
size of the POST data that can be posted as on the login form. DCC
compares the value of the content-length header with the limit set.
Default: unlimited
This Authentication Scheme challenge parameter requires a positive
integer value that restricts the maximum number of bytes of POST
data that is submitted as user credentials and sent to the OAM Server.
MaxPreservedPostDataBytes Configure this Authentication Scheme challenge parameter (or
user-defined Webgate parameter) for authentication POST-data
preservation.
Default: 8192 bytes
Note: Preference is given first to the Authentication Scheme
containing this parameter; second to the Webgate providing this
user-defined parameter. Otherwise, default behavior is 8192 bytes.
This parameter defines the maximum length of POST data that
Webgate can preserve. If the size of inbound raw user POST data (or
encrypted post data after processing), crosses this limit, POST data is
dropped and the existing authentication flow continues. The event is
logged as usual.
See Also: "Configuring Authentication POST Data Handling" on
page 22-90
Table 15–2, " User-Defined WebGate Parameters"
TempStateMode=form
DCC Only
With the DCC, a Form-based Authentication Scheme requires the
challenge parameter TempStateMode=form for POST data restoration
For Form authentication scheme, if this parameter is not defined, the
value will be "form".
See Also: "Configuring Authentication POST Data Handling" on
page 22-90
Table 15–2, " User-Defined WebGate Parameters"
Configuring Authentication POST Data Handling
Managing Authentication and Shared Policy Components 22-93
22.12.3 About Post Data Size Limits
Assuming the usual form data entered by users is about several kilobytes, putting a
limit on data comsumption from the incoming request is a general requirement. The
data transferred in the front channel protocol (either request or response) must also go
through the size check. Considering these situations:
■Limit the size of data passed to the OAM Server on the back channel using the
maxpostdatabytes authentication challenge parameter
In cases where the DCC is used, the maxpostdatabytes authentication challenge
parameter performs this check on the overall POST data.
■Limit the size of the POST data from the end user application using
MaxPreservedPostDataBytes authentication scheme challenge parameter.
The MaxPreservedPostDataBytes authentication scheme challenge parameter
handles this. Additionally, this can be set as a user-defined Webgate parameter.
■Limit size of the front channel payload on obrar.cgi or obrareq.cgi with a Webgate
user-defined parameter ChallengeRedirectMaxMessageBytes.
ChallengeRedirectMaxMessageBy
tes
Configure this user-defined Webgate parameter to limit the size of the
message data received as obrareq.cgi and obrar.cgi. Message data is
comprised of query string length (if present) or POST data length (if
POST data is present). If message size exceeds this limit, the message
is not processed and the existing message is shown in the browser. The
event is logged as usual.
Default: 8192 bytes
Notes:
obrareq.cgi is the authentication request in the form of a query string
redirected from Webgate to the credential collector (OAM Server or
DCC).
obrar.cgi is the authentication response string redirected from the
credential collector (OAM Server or DCC) to Webgate.
See Also: "Configuring Authentication POST Data Handling" on
page 22-90
Table 15–2, " User-Defined WebGate Parameters"
PostDataRestoration Configure this user-defined Webgate parameter to initiate
authentication POST-data preservation for the resource Webgate. This
parameter requires a value of
true
or
false
.
Default:
false
When set to
true
, Webgate initiates POST data preservation.
See Also: "Configuring Authentication POST Data Handling" on
page 22-90
Table 15–2, " User-Defined WebGate Parameters"
serverRequestCacheType
ECC Only
Configure this OAM parameter to define the mechanism used to
remember the request context by the embedded credential collector
(ECC).
This OAM Server parameter in $DOMAIN_
HOME
/config/fmwconfig/oam-config.xml
indicates mechanism to
be used to remember the request context. Possible values are FORM,
COOKIE, or CACHE.
Default: COOKIE
FORM is the required value for POST data preservation, Long URL
handling and Form-based authentication schemes.
See Also:
TempStateMode
in this table.
"Configuring Authentication POST Data Handling" on page 22-90
Table 22–34 (Cont.) Parameters Required for Authentication POST Data Handling
Parameter Description
Configuring Authentication POST Data Handling
22-94 Administrator's Guide for Oracle Access Management
22.12.4 Configuring Authentication POST Data Handling
Be sure to read all POST data topics in this section before attempting this procedure.
There is no need to make any explicit change in your authentication scheme.
To configure authentication POST data handling
1. Configure the Authentication Scheme:
a. Use the Oracle Access Management Console to create or find the desired
scheme (Table 22–33).
b. On the Authentication Scheme page, modify values for POST data handling.
This example uses the embedded credential collector (Table 22–20) and values
for POST data handling (Table 22–23):
Name: DesiredScheme
Authentication Level 2
Challenge Method: Form
Challenge Redirect URL: /oam/server/
Authentication Module: LDAP
Challenge URL: /pages/login.jsp
Context Type: External
Challenge Parameters
c. Click Apply to submit the changes.
2. ECC: Configure serverRequestCacheType, the OAM parameter in oam-config.xml,
if using ECC.
a. Stop the managed server.
b. Stop the administration server.
c. Open oam-config.xml and modify the value of serverRequestCacheType.
d. Save the file.
e. Restart the administration server.
f. Restart the managed server.
3. Configure Webgate Parameters for POST data handling:
a. From the System Configuration tab, Access Manager section, create or find the
desired OAM Agent registration.
b. On the agent registration page, submit values for POST data handling
(Table 22–23):
Name: DesiredAgent
User-Defined Parameters
Authentication Scheme Challenge
Parameters for Post Data with ECC
Authentication Scheme Challenge
Parameters for Post Data with DCC
MaxPreservedPostDataBytes=
9000
MaxPreservedPostDataBytes=
9000
TempStateMode=form
User-Defined Webgate
Post Data Parameters with ECC
User-Defined Webgate
Post Data Parameters with DCC
PostDataRestoration=true PostDataRestoration=true
Long URL Handling During Authentication
Managing Authentication and Shared Policy Components 22-95
c. Click Apply to submit the changes.
22.12.5 Testing POST Data Handling Configuration
The following actions can be performed in sequence to test your POST data handling
configuration.
1. Complete all configurations as documented.
2. Develop a simple script to print the POST data and the URL protected by Webgate.
3. Use a browser to access the protected resource.
4. Provide credentials and establish SSO. Wait for the idle session timeout period.
5. With the same browser, use the form to post data to the same Webgate using the
URL which can print the POST data. You will be redirected to credential collector.
6. Enter the same credentials previously used.
From the HTTP headers you can see, after getting obrar.cgi from the credential
collector, the protected resource Webgate will give a 200 response (previously it
was 302) and the POST data can be printed by your script.
22.13 Long URL Handling During Authentication
Long URL handling applies to both credential collectors (ECC or DCC) and is a default
operation.
22.13.1 About Long URLs and Authentication Handling
Authentication involves redirecting the user's request to a centralized component that
performs authentication, known as a Credential Collector. The mechanism used to
redirect user from the policy enforcement point (OAM Agent) to the Credential
Collector, is a proprietary front channel protocol over HTTP. This protocol currently
provides the context of the request and the authentication response on the query
string. In situations where the URL of the requested page is larger, the overall context
becomes larger and can go beyond the browser's permissible size. This is referred to as
Long URL Handling.
By default, the Resource Webgate checks the payload size of the front channel protocol
message to determine if it is larger than the coded limit. When long URL handling is
explicitly enabled, the limit is ignored and has no impact.
The credential collector determines if the front channel response payload is to be sent
as HTTP Post data when:
■The incoming request indicates that the agent is capable of handling HTTP POST
or REDIRECT type of response
■The credential collector is configured to always send the payload as HTTP post
data
■The credential collector is configured to always send the payload as a query string
If no explicit configuration is present, then if the payload size is greater than
predefined limit, then it shall send payload as the HTTP post data. But if the payload
size is lower than the predefined limit, then it shall send it on the query string.
Note: If application post data is also preserved there is no impact.
Long URL Handling During Authentication
22-96 Administrator's Guide for Oracle Access Management
Table 22–35 identifies Long URL handling functionality with both the ECC and DCC.
22.13.2 About Configuring Long URL Handling
Table 22–36 summarizes the authentication schemes that support authentication Long
URL handling.
Table 22–37 summarizes the parameters and complete configuration requirements for
authentication Long URL handling. All requirements described in Table 22–37 are
supported end to end with the authentication schemes in Table 22–36.
Table 22–35 ECC and DCC: Long URL Handling
ECC Long URL Handling DCC Long URL Handling
ECC is compatible with all 11g Webgates. Same as ECC.
N/A Long URL handling is limited to the maximum
allowed size of the DCCContextCookie.
The DCC does not perform explicit long URL
handling.
There is no support to preserve the front channel
payload on the form.
Table 22–36 Authentication Schemes Supporting Long URL Handling
Authentication Schemes
■FORM challenge method, supported with the out of the box login page.
■WNA
■Basic
■Basic+Sessionless
■X509
■OIF, OIM, OAAM integrations using TAP
Table 22–37 Parameters Required for Long URL Handling
Parameter Description
ChallengeRedirectMethod Configure this as either as an Authentication Scheme challenge
parameter (or as a user-defined Webgate parameter) for POST-data
preservation for both the embedded credential collector (ECC) and the
detached credential collector (DCC).
Note: Preference is given first to the Authentication Scheme
containing this parameter; second to the Webgate providing this
user-defined parameter. Otherwise, default behavior is Dynamic.
Value: GET|POST|DYNAMIC
Behavior when value is:
■POST: Webgate sends encquery as POST data and credential
collectors send encreply as POST data.
■GET: Webgate sends encquery as query string and expects
encreply as query string.
■DYNAMIC: Default behavior, based on the length of the
encquery/encreply. Webgate/credential collector sends data
either as a query string or as POST data. Code default maximum
length is 2000 characters.
See Also: "Configuring Authentication POST Data Handling"
Table 15–2, " User-Defined WebGate Parameters"
Using Application Initiated Authentication
Managing Authentication and Shared Policy Components 22-97
Long URL handling is enabled by default. The Webgate/credential collector sends
data either as a query string or a POST. The length of the querystring parameter sent
with obrareq.cgi and obrar.cgi is 2000 characters maximum.
22.14 Using Application Initiated Authentication
Access Manager exposes a Reauthentication URL that applications may choose to
invoke if the user is accessing a sensitive URL or operation. This re-authentication will
be triggered irrespective of whether or not the user already has a valid session. An
application can trigger re-authentication by invoking the
/oamreauthenticate
URL at:
http://<ohs_host>:<ohs_port>/oamreauthenticate
Access Manager will expect the /oamreauthenticate to be registered and associated
with an authentication policy. Re-authentication will be performed using the scheme
associated with this policy. The re-authentication URL takes the redirection URL as a
query parameter. After re-authentication is complete, Access Manager redirects the
user to this URL. A request to re-authenticate the user might look like the following:
http://<host>:<port>/oamreauthenticate?
redirect_url=http://<host>:<port>/<redirection_resource_url>
If the redirection URL is not specified, a 404 error code is returned. If the incorrect
credentials are specified during re-authentication, the user will remain on the login
page and, after the maximum retry limit, the user will be redirected to an appropriate
error page. The following process is how to configure for application initiated
authentication.
ChallengeRedirectMaxMessageBy
tes
Configure this user-defined Webgate parameter to limit the size of the
message data received as obrareq.cgi and obrar.cgi. Message data is
comprised of query string length (if present) or POST data length (if
POST data is present). If message size exceeds this limit, the message
is not processed and the existing message is shown in the browser. The
event is logged as usual.
Default: 8192 bytes
Notes:
obrareq.cgi is the authentication request in the form of a query string
redirected from Webgate to the credential collector (OAM server or
DCC).
obrar.cgi is the authentication response string redirected from the
credential collector (OAM server or DCC) to Webgate.
See Also: "Configuring Authentication POST Data Handling" on
page 22-90
Table 15–2, " User-Defined WebGate Parameters"
serverRequestCacheType
ECC Only
Configure this OAM parameter to define the mechanism used to
remember the request context by the embedded credential collector
(ECC).
This OAM Server parameter in $DOMAIN_
HOME
/config/fmwconfig/oam-config.xml
indicates mechanism to
be used to remember the request context. Possible values are FORM,
COOKIE, or CACHE.
Default: COOKIE
FORM is the required value for POST data preservation, Long URL
handling and Form-based authentication schemes.
See Also:
TempStateMode
in this table.
"Configuring Authentication POST Data Handling" on page 22-90
Table 22–37 (Cont.) Parameters Required for Long URL Handling
Parameter Description
Using Application Initiated Authentication
22-98 Administrator's Guide for Oracle Access Management
1. Create an
http://<ohs_host>:<ohs_port>/oamreauthenticate
resource and
assign the desired authentication scheme to it.
2. In the redirect URL, set the appropriate responses to verify that re-authentication
has been successful and to communicate back to the application about the
re-authentication responses.
Access Manager sets the last re-authentication time as a "OAM_LAST_
REAUTHENTICATION_TIME" header and this value is updated every time the user
is re-authenticated.
23
Understanding Credential Collection and Login 23-1
23
Understanding Credential Collection and Login
[20]
This chapter introduces the elements that comprise Access Manager credential
collection. Credential collection is a functionality that can be executed either on the
Access Manager server (ECC) or WebGates (DCC).
This chapter includes the following topics:
■Logging In with Access Manager Credential Collection
■Processing SSO Login with OAM Agents and ECC
■Processing SSO Login with OAM Agents and DCC
■Processing SSO Login with OSSO Agents (mod_osso) and ECC
■Configuring 11g WebGates and Authentication Policy for DCC
■Tunneling from DCC to Access Manager Over Oracle Access Protocol
■Configuring a DCC WebGate for X509 Authentication
23.1 Logging In with Access Manager Credential Collection
Access Manager provides two mechanisms for credential collection during
authentication processing:
■The default Embedded Credential Collector (ECC) is installed with the Access
Manager Server and can be used as-is with no additional installation or set up
steps (except the global password policy configuration described in "Managing
Global Password Policy").
The mechanism that redirects the user from the Policy Enforcement Point to the
Credential Collector is a proprietary front channel protocol over HTTP. This
protocol currently provides a context of the request and the authentication
response on the query string.
■The 11.1.2 (or later) WebGate provides a single switch for the optional Detached
Credential Collector (DCC). The DCC provides network isolation for greater
security in production deployments, and is required for some forms of
authentication.
Note: Unless explicitly stated, information in this chapter is the same
for all agent types and Access Manager credential collectors.
For details about single log-out, see Chapter 27, "Configuring
Centralized Logout for Sessions Involving 11g WebGates".
Logging In with Access Manager Credential Collection
23-2 Administrator's Guide for Oracle Access Management
For a detailed comparison of the two mechanisms for credential collection, see
Section 22.5, "Understanding Authentication Methods and Credential Collectors."
Single Sign On login processing determines whether the user is a valid user and
whether the session state is active or inactive (either a first time user or the user
session has expired). Session management support locates, persists, and cleans up the
session context and user token. Details are in the following sections.
■Login with Self-Service Provisioning Applications
■Login Processing with Access Manager-Protected Resources
23.1.1 Login with Self-Service Provisioning Applications
Provisioning does not create the session in Access Manager. When a new user uses a
self-service provisioning application to create an account, he is prompted for his
userID and password again when accessing an application.
The protected application is directed to Access Manager 11g, which requests the user's
credentials. For example, if Oracle Identity Manager is protected by Access Manager,
the user request is redirected to Access Manager from which a request to enter
credentials is made.
23.1.2 Login Processing with Access Manager-Protected Resources
The first time a user attempts to access a protected resource, she is prompted for her
credentials based on the authentication scheme and authentication level for the
resource. Typically a userID and password are needed.
Failure: Authentication fails if the wrong userID or password is entered. The user is
not authenticated and another prompt for credentials appears.
With Oracle Access Manager 11.1.1, only the ECC in the OAM server was available.
Access Manager 11.1.2 supports the ECC by default. However, Access Manager also
enables you to configure an 11g WebGate to use as a detached credential collector
(DCC). A DCC-enabled WebGate can be separate from (or combined with) a Resource
WebGates.
Both the ECC and DCC provide an authentication flow that includes form login, error,
and login retries. They provide SecurID and server affinity as well as password policy
enforcement and a dynamic, multi-step, iterative, and variable (multi-step
authentication) where the credentials are not supplied all at one time. A customizable
authentication flow can include authentication plug-ins with contracts between the
plug-in, OAM Proxy, and Credential Collector; a contract between the plug-in and
login application; and between the Credential Collector and login application.
When deciding whether to use one credential collector or both, consider:
■Co-existence: Allowing both the ECC and DCC to co-exist enables you to use
authentication schemes and policies configured for either the ECC or the DCC.
Note: Although the DCC is the recommended approach for
credential collection, instructions in this book presume you are using
the ECC unless explicitly stated.
Note: Success and failure results are the same as described in "Login
Processing with Access Manager-Protected Resources".
Processing SSO Login with OAM Agents and ECC
Understanding Credential Collection and Login 23-3
This enables a fallback mechanism for resources that rely on the ECC (Oracle
Access Management Console, for instance).
■Disabling ECC: Disabling the ECC entirely prohibits access to resources that rely
on the ECC mechanism (Oracle Access Management Console, for instance).
Table 23–1 provides links to more information.
23.2 Processing SSO Login with OAM Agents and ECC
This topic is based on using the default Embedded Credential Collector with OAM
Agents (Resource WebGates) protecting resources).
Access Manager authenticates each user with a customer-specified authentication
method to determine the identity and leverages information stored in the user identity
store. Access Manager authentication supports several authentication methods and a
number of authentication levels. Resources with varying degrees of sensitivity can be
protected by requiring higher levels of authentication that correspond to more
stringent authentication methods.
When a user tries to access a protected application, the request is received by Access
Manager which checks for the existence of the SSO cookie.
After authenticating the user and setting up the user context and token, Access
Manager sets the SSO cookie and encrypts the cookie with the SSO Server key (which
can be decrypted only by the SSO Engine).
Depending on the actions (responses in Access Manager 11g) specified for
authentication success and authentication failure, the user may be redirected to a
specific URL, or user information might be passed on to other applications through a
header variable or a cookie value.
Based on the authorization policy and results of the check, the user is allowed or
denied access to the requested content. If the user is denied access, she is redirected to
another URL (specified by the Administrator in WebGate registration).
Figure 23–1 shows the processes involved in evaluating policies, validating a user's
identity, authorizing the user for a protected resource, and serving the protected
Table 23–1 Login Processing with Access Manager-Protected Resources
Login Processing Topic See
With OAM Agents and ECC "Processing SSO Login with OAM Agents and ECC" on page 23-3
With OAM Agents and DCC "Processing SSO Login with OAM Agents and DCC" on page 23-5
With OSSO Agents and ECC "Processing SSO Login with OSSO Agents (mod_osso) and ECC" on
page 23-9
With Other Agents or Mixed
Agent Types
Mixed agent types are supported. Processing is the same for each
agent type. For other agent types, see:
■Chapter 28, "Registering and Managing Legacy OpenSSO
Agents"
■Chapter 29, "Registering and Managing Legacy OSSO Agents"
■Chapter 30, "Registering and Managing 10g WebGates with
Access Manager 11g"
Login and Auto Login for
Applications Using Oracle ADF
Security
Oracle Platform Security Services (OPSS) comprise Oracle WebLogic
Server's internal security framework. On the Oracle WebLogic Server,
you can run a Web application that uses Oracles Application
Development Framework (Oracle ADF) security, integrates with
Access Manager 11g SSO, and uses OPSS SSO for user authentication.
For more information, see Appendix A, "Integrating Oracle ADF
Applications with Access Manager SSO".
Processing SSO Login with OAM Agents and ECC
23-4 Administrator's Guide for Oracle Access Management
resource. This example shows the OAM Agent flow. There are slight variations with
11g WebGates/Access Clients.
Figure 23–1 SSO Log-in with Embedded Credential Collector and OAM Agents
Process overview: SSO Login Processing with Embedded Credential
Collector and OAM Agents
1. The user requests a resource.
2. WebGate forwards the request to Access Manager for policy evaluation.
3. Access Manager:
■Checks for the existence of an SSO cookie.
■Checks policies to determine if the resource protected and if so, how?
4. Access Manager Server logs and returns decisions.
5. WebGate responds as follows:
a. Unprotected Resource: Resource is served to the user.
b. Protected Resource:
Request is redirected to the credential collector.
The login form is served based on the authentication policy.
Authentication processing begins
Processing SSO Login with OAM Agents and DCC
Understanding Credential Collection and Login 23-5
6. User sends credentials.
7. Access Manager verifies credentials.
8. Access Manager starts the session and creates the following host-based cookies:
■One per Agent: OAMAuthnCookie set by 11g WebGates (ObSSOCookie set by
10g Webgate) using the authentication token received from the OAM Server
after successful authentication.
Note: A valid cookie is required for a session.
■One for OAM Server: OAM_ID
9. Access Manager logs Success or Failure.
10. Credential collector redirects to WebGate and authorization processing begins.
11. Webgate prompts Access Manager to look up policies, compare the user's identity,
and determine the user's level of authorization.
12. Access Manager logs policy decision and checks the session cookie.
13. OAM Server evaluates authorization policies and cache the result.
14. OAM Server logs and returns decisions
15. WebGate responds as follows:
■If the authorization policy allows access, the desired content or applications
are served to the user.
■If the authorization policy denies access, the user is redirected to another URL
determined by the Administrator.
23.3 Processing SSO Login with OAM Agents and DCC
The detached credential collector is simply a WebGate configured to use the additional
Credential Collection capability in your deployment. There are two deployment types
depending on whether the DCC WebGate is also protecting the applications or not.
Table 23–2 identifies the DCC-supported deployments.
Processing SSO Login with OAM Agents and DCC
23-6 Administrator's Guide for Oracle Access Management
Separate DCC and Resource Webgates: A sample deployment with segregated DCC
is shown in Figure 23–2.
Table 23–2 DCC Deployment Support
Deployment Type Description
Separate DCC and Resource
Webgate
A distributed deployment where WebGates protecting applications
are managed independently from the centralized DCC. You can have:
■Two or more 11.1.1.5 Resource Webgates that redirect to the 11.1.2
DCC-enabled WebGate for authentication
■10.1.4.3 Resource WebGate that redirects to the 11.1.2
DCC-enabled WebGate for authentication
Enable HTTPS between the user-agent and the DCC (but not with
some or all Resource WebGates).
When credential collection is externalized and centralized in the DCC,
the user-agent connections with other WebGates never carry user
credentials, nor session tokens that could be used to obtain access to
resources protected by any other WebGate. This significantly reduces
exposure caused by lack of SSL on these links and may be an
acceptable tradeoff in some deployments.
■Separate OHS Instances: Install the DCC on a different OHS
instance (on the same or different host) as the Resource WebGate.
■Define the Resource WebGate Authentication Scheme Challenge
Redirect URL to point to the DCC.
■Define the Resource WebGate logoutRedirectUrl to point to the
DCC logout script/page (logout callbacks to Resource WebGate
is invoked during logout).
See Also: Figure 23–2
Combined DCC and Resource
Webgate
A streamlined deployment minimizing configuration and processing
overhead.
A DCC WebGate can function as both a resource WebGate (Policy
Enforcement Point) that protects application resources and a DCC. In
this case, there is no front-channel redirection or processing:
■Install the DCC on a the same OHS instance (on the same host) as
the Resource WebGate.
■Simplified configuration: The Challenge Redirect URL can be
empty.
■No logoutRedirectUrl is needed, no logout callback is needed.
See Also: Figure 23–3
Processing SSO Login with OAM Agents and DCC
Understanding Credential Collection and Login 23-7
Figure 23–2 Example: Separate Resource WebGate and DCC WebGate Deployment
This topology (Figure 23–2) showcases choices appropriate for scenarios with
maximum security sensitivity. Both centralized and externalized credential collection
are used: Resource WebGates protecting applications are segregated from the DCC
WebGate performing credential collection.
The user accesses the Access Manager-protected resource from the public network. A
WebGate protecting the application is deployed within a DMZ. The DCC WebGate is
also deployed within a DMZ. The protected application and OAM Server instances are
located within the private network and not directly accessible from the public
network.
Using the DCC in the DMZ, only authenticated network connections are allowed to
reach the server itself. The DCC inherits all back-channel communication
characteristics available to 11g WebGates (network connection using the Oracle Access
Protocol). The OAP offers:
■SSL between the client and the server, optionally using 3rd party signed
certificates
■mutual authentication at the application level using client id and password
■request multiplexing and full-duplex communication at the application level
■built-in connection load balancing and failover capability
The DCC receives an authentication request from the Agent and checks for the
presence of the DCC cookie. If the cookie does not exist, credential collection is
initiated; checks are made, and user-supplied credentials are passed for validation.
Processing SSO Login with OAM Agents and DCC
23-8 Administrator's Guide for Oracle Access Management
Figure 23–3 Combined DCC and WebGate Configuration
Process overview: Authentication with the combined DCC and Resource
Webgate
1. The user requests access to a resource which initiates the authentication process.
2. The DCC redirects through the front channel to the login page.
3. The login page is returned to the user.
4. User enters credentials, which are posted to the action URL (a user-defined
parameter in an authentication scheme, Table 22–23).
5. Authentication occurs using the back channel (OAP) and OAM Proxy.
6. The Authentication Plug-in is activated.
7. The Plug-in requests redirect to a URL to collect additional credentials.
8. The Plug-in request is returned to the DCC.
9. The DCC redirects to the URL and expects specified credentials.
10. The Browser follows the redirect.
11. Credentials are posted to the Action URL.
Note: Encryption occurs only from an 11g resource WebGate to the
DCC. The channel is not encrypted for communication between 10g
resource WebGate and 11g DCC; this is in clear text.
See Also: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate" on page 27-6
Login App with pages:
Login / CredCollection
Logout
Error
Browser
User Agent
OHS
DCC
WebGate
OAM Server
Instance
OAM
Proxy
AUTHN
Plugin
31 4 3
2 9
6
7
5
8
Legend
User-Agent channel: HTTPS
Front channel: HTTPS
Other: SSL
Processing SSO Login with OSSO Agents (mod_osso) and ECC
Understanding Credential Collection and Login 23-9
23.4 Processing SSO Login with OSSO Agents (mod_osso) and ECC
SSO login processing with registered OSSSO Agents (mod_osso) is similar to login
processing with WebGates. However, mod_osso provides only authentication using
Access Manager 11g authentication policies.
Figure 23–4 illustrates the login processing with mod_osso and Access Manager 11g.
Figure 23–4 SSO Login Processing with OSSO Agents and ECC
Process overview: SSO Log-in Processing with OSSO Agents and ECC
1. The user requests a resource.
2. mod_osso forwards the request to Access Manager for policy evaluation.
3. Access Manager:
■Checks for the existence of an SSO cookie.
■Checks policies to determine if the resource protected and if so, how?
4. OAM Server logs and returns decisions.
Note: mod_osso does not support authorization either on its own or
using Access Manager 11g policies.
Configuring 11g WebGates and Authentication Policy for DCC
23-10 Administrator's Guide for Oracle Access Management
5. mod_osso responds as follows:
a. Unprotected Resource: Resource is served to the user.
b. Protected Resource:
Request is redirected to the credential collector.
The login form is served based on the authentication policy.
Authentication processing begins
6. User sends credentials.
7. ECC verifies credentials.
8. Access Manager starts the session, passes an authentication token to the
application, and creates the following cookies:
■One per partner: OHS_host_port
■One for the OAM Server: OAM_ID
■Global Inactivity Out: A domain-level cookie GITO, described in mod_osso
Cookies.
9. Access Manager logs Success or Failure.
10. Credential collector redirects to mod_osso, which transmits the simple header
values that applications can use to authorize the user.
11. Resource is served upon authentication success and the OHS-host-port cookie is
set.
23.5 Configuring 11g WebGates and Authentication Policy for DCC
The following task overview documents how to configure an 11g WebGate and
Authentication Policy for use with the DCC. The appropriate sub sections are linked
within each step.
1. Enabling DCC Credential Operations provides steps for either configuration:
DCC Combined with Resource Webgate: Enable Allow Credential Collector
Operations in the DCC's OAM Agent registration page.
Separate DCC and Resource Webgate: Enable Allow Credential Collector
Operations in the DCC's OAM Agent registration page and edit the Resource
Webgate registration page to set the
Logout Redirect URL
to the DCC's logout.pl.
2. Locating and Updating DCC Forms for Password Policy
3. Adding PasswordPolicyValidationScheme to Authentication Policy for DCC
provides steps for either configuration:
DCC Combined with Resource Webgate: In the combined DCC/Resource
Webgate Application Domain, update the Protected Resources Authentication
Policy to use your DCC Authentication Scheme.
Separate DCC and Resource Webgate: In the separate Resource Webgate
Application Domain, update the Protected Resources Authentication Policy to use
your DCC Authentication Scheme.
4. Supporting Federation Flows With DCC provides steps to incorporate the DCC
into Federation flows.
Configuring 11g WebGates and Authentication Policy for DCC
Understanding Credential Collection and Login 23-11
23.5.1 Enabling DCC Credential Operations
Whether you are using a separate DCC or combined DCC and Resource WebGate, you
must enable Allow Credential Collector Operations in the DCC's OAM Agent
registration page.
With a separate DCC and Resource WebGate, you must also edit the Resource
WebGate registration page to set the
Logout Redirect URL
to the DCC's logout.pl, as
described in Step 3.
The following procedure presumes your deployment uses Open mode
communication. If your deployment uses Simple or Cert mode communication, be
sure to copy the appropriate artifacts when you perform Step 4.
Prerequisites
■Configuring and Managing Registered OAM Agents Using the Console
■Managing Global Password Policy
■Configuring Password Policy Authentication using DCC-specific details
To enable DCC credential operations
1. In the Access Manager section of the Oracle Access Management Console, click
SSO Agents to find and open the registration page for the 11.1.2 Webgate that will
function as the DCC.
2. DCC WebGate Registration: Check Allow Credential Collector Operations, click
Apply, then perform Steps 4 and 5.
3. Separate Resource WebGate: Edit the Resource WebGate registration to set the
Logout Redirect URL
to the DCC's logout.pl (Table 24–3), click Apply, then
perform Steps 4 and 5.
4. Copy Agent configuration file (including Simple or Cert mode files) from the
AdminServer (Console) host to the Agent host. For example:
5. Restart the OHS Web server.
Note: If your environment uses the ECC, go to "Completing
Password Policy Configuration".
Note: If the DCC is combined with a Resource WebGate, skip Step 3.
Agent & Artifacts Artifacts
11g WebGate/Access Client
ObAccessClient.xml and
cwallet.sso
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/webgate/config
Simple or Cert Mode Copy to the Agent host: $11gWG_install_dir/webgate/config
■aaa_key.pem
■aaa_cert.pem
■aaa_chain.pem
■password.xml
See Also: Appendix C, "Securing Communication"
Configuring 11g WebGates and Authentication Policy for DCC
23-12 Administrator's Guide for Oracle Access Management
6. Proceed to "Locating and Updating DCC Forms for Password Policy".
23.5.2 Locating and Updating DCC Forms for Password Policy
Access Manager provides several dynamic pages for user interactions with the DCC.
Prerequisites
Enabling DCC Credential Operations
To locate and update the DCC forms
1. Locate the DCC forms in the WebGate host (Table 24–3)
:
$WEBGATE_HOME/webgate/ohs/oamsso/*,
$
WEBGATE_HOME/webgate/ohs/oamsso-bin/*pl
, and
$WEBGATE_HOME/webgate/ohs/oamsso-bin/templates/*
.
2. Customize their location, depending on the desired topology of the authentication
scheme being developed.
3. Update Perl Location: Update the Perl location to be consistent with the actual
location, in the first line of the login, logout, and securid scripts on Webgate host
in
$WEBGATE_HOME/webgate/ohs/oamsso-bin/*pl
(Table 24–3).
4. Customize the default pages for your enterprise, or replace them entirely with
custom pages. For example, you can design, implement, and deploy a custom
page that displays a different version of the login form for a mobile browser than
is used for a desktop browser.
5. Proceed to "Adding PasswordPolicyValidationScheme to Authentication Policy for
DCC".
23.5.3 Adding PasswordPolicyValidationScheme to Authentication Policy for DCC
The following procedure provides steps that you must perform to use your DCC
Authentication Scheme in a Protected Resources Authentication Policy. The steps you
perform depend on the type of deployment you have:
■Combined DCC/Resource WebGate: Perform Step 1 to add your DCC
Authentication Scheme to the Protected Resources Authentication Policy of the
combined DCC/Resource WebGate Application Domain.
■Separate Resource WebGate: Perform Step 3 to add your DCC Authentication
Scheme to the Protected Resources Authentication Policy of the separate Resource
WebGate Application Domain.
Perform Step 2 regardless of your DCC deployment type. By default, login and logout
forms are excluded through OHS /httpd.conf/webgate.conf so that you do not need
to exclude them through policies. However, with the Chrome browser, you must
explicitly exclude the async favicon.ico request (which overrides the DCCCtxCookie).
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management
Note: This example refers to the PasswordPolicyValidationScheme
set for the DCC in Section 24.7, "Configuring Password Policy
Authentication."
Configuring 11g WebGates and Authentication Policy for DCC
Understanding Credential Collection and Login 23-13
Prerequisites
Locating and Updating DCC Forms for Password Policy
To use the DCC Authentication Scheme in an Authentication Policy
1. Combined DCC/Resource WebGate: Open the DCC application domain:
Policy Configuration
Application Domains
DCCDomain
a. Locate and open the Authentication Policy, Protected Resource Policy (see
"Searching for an Authentication Policy" on page 25-34).
b. Add your DCC Authentication Scheme to this policy (see "Defining
Authentication Policies for Specific Resources" on page 25-31).
PasswordPolicyValidationScheme (DCC Authentication Scheme)
c. Perform Step 2 if you have the Chrome Browser. Otherwise, go to Step 4.
2. Chrome Browser: Add and exclude resource
/favicon.ico
in the DCCDomain, as
follows.
a. From DCCDomain, click the Resources tab.
b. Find and open the HTTP resource
/favicon.ico
(or click the New Resource
button and then add this resource).
c. Confirm or edit the Resource URL to:
/favicon.ico
d. In the Protection section, Protection Level list, select Excluded, then click
Apply.
e. Proceed to Step 4.
3. Separate Resource Webgate: Open the Resource Webgate application domain.
Policy Configuration
Application Domains
ResourceWGDomain
a. Locate and open the Authentication Policy, Protected Resource Policy (see
"Searching for an Authentication Policy" on page 25-34).
b. Add your DCC Authentication Scheme and an optional Failure URL (when
not specified, Failure URL displays the default error page) to this policy (see
"Defining Authentication Policies for Specific Resources" on page 25-31):
DCC Authentication Scheme
Failure URL (optional)
c. Perform Step 2 if you have the Chrome Browser. Otherwise, go to Step 4.
4. Restart your Web server and proceed to "Completing Password Policy
Configuration".
See Also: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate" on page 27-6
Tunneling from DCC to Access Manager Over Oracle Access Protocol
23-14 Administrator's Guide for Oracle Access Management
23.5.4 Supporting Federation Flows With DCC
The DCC is enhanced to work as a public end-point to the Access Manager server.
HTTP requests to the DCC are tunneled via NAP to the proxy module of the Access
Manager server. Only requests defined in the TunneledUrls parameter of the DCC
Profile will be tunneled. The JSP pages and servlets are executed in the Access
Manager server and the response is tunneled back to the DCC. The end user effectively
communicates only to the DCC.
To use DCC for converged Federation flows, perform the following manual steps.
1. Configure the following internal resources as Public instead of Excluded.
/oamfed/.../*
/oam/.../*
/.../*
2. In the DCC WebGate, set the logout value to a valid DCC WebGate logout URL;
for example,
/oamsso-bin/logout.pl
3. Update the DCC Agent entry by adding the following entry to the User Defined
Parameters list using the Access Manager Administration Console.
TunneledUrls=/oam,/oamfed
See Section 23.6.2, "Configuring OAP Tunneling."
4. Update the OAM public endpoint entry so that it points to the DCC WebGate.
Under Access Manager Settings, set the OAM Server Host, OAM Server Port and
OAM Server Protocol to the values pertinent to the OHS/DCC and click Apply.
5. Update the ProviderID value under Federation Settings (if applicable) and
redistribute the new metadata to all Federation partners due to the endpoint
change.
6. Set the contextType to 'External'.
See Section 22.9.1, "About Authentication Schemes and Pages" for details on this
setting.
23.6 Tunneling from DCC to Access Manager Over Oracle Access
Protocol
Access Manager supports HTTP communication over the Oracle Access Protocol
(OAP). In this case, a WebGate configured as a DCC uses the ECC servlets for
Note: If a WebGate is configured as a DCC and federated flows are
in use, the DCC WebGate cannot be used to protect the resource. A
separate WebGate must be configured and used to protect the
resource. Authentication and authorization requests will be tunneled
to the OAM Server, and the ECC login form will be tunneled and
displayed in the user’s browser.
Note: Alternately you can update a single Authentication Scheme to
point to the DCC WebGate by altering the challenge redirect URL
leaving the REST parameters unchanged.
Tunneling from DCC to Access Manager Over Oracle Access Protocol
Understanding Credential Collection and Login 23-15
credential collection during Access Manager authentication. The following sections
contain more details.
■How DCC Tunneling with OAP Works
■Configuring OAP Tunneling
23.6.1 How DCC Tunneling with OAP Works
Figure 23–5 illustrates how the tunneling process works. This process works for DCC
WebGates only.
Figure 23–5 OAP Tunneling with DCC
The following steps provide more details in regards to the OAP Tunneling process.
1. The URL to be tunneled is configured in the DCC WebGate profile.
2. This same URL is mapped to a servlet or JSP page in the Access Manager server.
3. On accessing the tunneled URL, the WebGate intercepts the HTTP request and
converts it to an OAP request.
4. The OAP request is forwarded to the Access Manager server.
5. The Access Manager server (OAM proxy) receives the OAP request and passes it
to the tunnel proxy.
6. The tunnel proxy will convert the OAP request to an HTTPServletRequest and
invoke the corresponding servlet (or compiled servlet in the case of a JSP).
7. The response is converted back to an OAP message and passed to the OAP end
point.
8. The OAM end point responds to the WebGate with the converted OAP message.
9. The WebGate converts the OAP message back to an HTTP response.
10. The WebGate provides the HTTP response to the caller (browser).
23.6.2 Configuring OAP Tunneling
To configure OAP Tunneling, a WebGate must be installed and configured to work
with the Access Manager server as a DCC. The Access Manager endpoint must be
deployed on the Access Manager Server. After ensuring these prerequisites have been
met, add a user-defined parameter to the WebGate profile that defines all URLs to be
tunneled using the form
TunneledUrls=<URL>,<URL1>
. For example:
TunneledUrls=/oam,/sampleapp
Note: For details on the DCC, see Section 22.5.2, "Comparing
Embedded Credential Collector with Detached Credential Collector."
Configuring a DCC WebGate for X509 Authentication
23-16 Administrator's Guide for Oracle Access Management
Lastly, protect the Tunneled URLs with an Authentication Policy. For details, see
Chapter 22, "Managing Authentication and Shared Policy Components."
23.7 Configuring a DCC WebGate for X509 Authentication
The following sections document the procedures to configure a DCC WebGate for use
with X509 authentication.
1. Configuring the WebLogic Server
2. Configuring a WebGate For DCC
3. Converting the DCC WebGate to SSL
23.7.1 Configuring the WebLogic Server
Use the procedures in the following sections to configure a WebLogic Server for X509
authentication.
1. Creating the Server and Trust Store
2. Configuring the WebLogic Server Instance
3. Creating the User Certificate
4. Adding the Root CA Certificate
23.7.1.1 Creating the Server and Trust Store
These are common procedures for WebLogic Server.
1. Create Server certificate
Create a Server Certificate and key for the WLS domain on which Oracle Access
Management 11g is deployed. This entails requesting a certificate (in which the
Common Name is the OAM server machine name), having the certificate signed
and converting it to the P12 format. The Server certificate can be created and
signed using any Certificate utility.
2. Create the server store and the trust store using keytool.
See Section C.2, "Securing Communication Between OAM Servers and WebGates"
for details.
23.7.1.2 Configuring the WebLogic Server Instance
Use the WebLogic console to configure the instance of the WebLogic Server to be SSL
and client certificate enabled.
1. Navigate to the server instance which is to be SSL and Client Cert enabled.
Configuring a DCC WebGate for X509 Authentication
Understanding Credential Collection and Login 23-17
Figure 23–6 Enable SSL
2. Check the SSL Listen Port Enabled check box and provide the port number as in
Figure 23–6.
3. Provide the server and trust keystore path under the “Keystore” tab.
Figure 23–7 Keystore Configuration
4. Add the private key alias details under the SSL tab.
The alias name is same name specified as the server store name in Section 23.7.1.1,
"Creating the Server and Trust Store."
Configuring a DCC WebGate for X509 Authentication
23-18 Administrator's Guide for Oracle Access Management
Figure 23–8 Add Private Key Alias
5. Display the Advanced options under the SSL tab and make the configurations
illustrated in Figure 23–9.
Figure 23–9 SSL Advanced Options
23.7.1.3 Creating the User Certificate
Run the following OpenSSL commands to create a user certificate in the .p12 format
and install it in your browser.
1.
openssl req -config openssl.cnf -new -out weblogic.csr
Provide the certificate details. The Common Name is the name of the user for
whom the certificate is requested.
Configuring a DCC WebGate for X509 Authentication
Understanding Credential Collection and Login 23-19
2.
openssl x509 -req -md5 -CAcreateserial -in weblogic.csr -days 180 -CA
F:\openssl\simpleCA\ca.pem -CAkey F:\openssl\simpleCA\ca-key.pem
-extfile
F:\openssl\openssl.cnf -out weblogic.pem
3.
openssl rsa -in privkey.pem -out weblogic.key
4.
openssl pkcs12 -export -in weblogic.pem -inkey weblogic.key -out
user1k1.p12
5. Install the .p12 formatted certificate output in your browser.
23.7.1.4 Adding the Root CA Certificate
This procedure adds the Root CA certificate of the certificate utility used to SSL enable
the WebLogic server. (In this example, the OpenSSL certificate utility is used.) The
Root CA certificate must be added to the
.oamkeystore
and
amtruststore
files located
in the following WebLogic directory:
$DOMAIN_HOME/base_domain/config/fmwconfig
1. Retrieve the password for the
.oamkeystore
and
amtruststore
files in WebLogic.
a. Navigate to $MIDDLEWARE_HOME/Oracle_IDM1/common/bin/.
b. Run wlst.sh.
c. Run connect() in the WLST shell.
d. Run domainRuntime() in the WLST shell.
e. Run listCred(map="OAM_STORE",key="jks") in the WLST shell to display the
password.
2. Add the Root CA certificate to the
.oamkeystore
and
amtruststore
files using the
keytool
command.
The value of –storepass is the password retrieved in the previous step. For
example:
./keytool -importcert -alias ROOT_CA -file /scratch/CA/ca.pem -keystore
/scratch/Oracle/Middleware/user_projects/domains/base_
domain/config/fmwconfig/.oamkeystore -storepass oru8nd3hhd4t4nrmh6unhv825b
-storetype jceks
./keytool -importcert -alias ROOT_CA -file /scratch/CA/ca.pem -keystore
/scratch/Oracle/Middleware/user_projects/domains/base_
domain/config/fmwconfig/amtruststore -storepass oru8nd3hhd4t4nrmh6unhv825b
-storetype jks
23.7.2 Configuring a WebGate For DCC
This section details the steps to configuring a WebGate for DCC. As part of this
procedure you will also create the LDAPScheme_DCC Authentication Scheme. You
will use the Oracle Access Management Console for the configuration steps. This
procedure assumes you have already installed the WebGates for which you will be
creating profiles.
1. Configure an 11g WebGate profile named, for example, ABC_WG1 on
http://<host>:7778/index.html.
Configuring a DCC WebGate for X509 Authentication
23-20 Administrator's Guide for Oracle Access Management
2. Configure an 11g WebGate profile named, for example, XYZ_WG1_DCC on
http://<host>:7779/index.html.
This WebGate will act as the authentication WebGate.
3. Navigate to the XYZ_WG1_DCC WebGate profile and Select Allow Credential
Collector Operations Option.
This configures the WebGate for use as a DCC.
4. Create a new Authentication Scheme by making a copy of the LDAPScheme
Authentication Scheme and modifying the following values.
Only modify the following values; leave the other parameters untouched.
a. Name as LDAPScheme_DCC
b. Challenge redirect URL is http://<host>:<port>/ (http://<host>:7779/)
c. Challenge URL : /oamsso-bin/login.pl
5. Navigate to the ABC_WG1 Application Domain and do the following.
a. Go to Authentication Policy.
b. Select Authentication Policy (Protected Resource Policy).
c. Select the newly created Authentication Scheme LDAPScheme_DCC.
6. Restart the Oracle HTTP Server with port 7779 in use.
7. Access the protected resource at http://<host>:7778/index.html.
You should get challenge page from the authenticating WebGate server (port
7779). After providing valid credentials, the resource on the port 7778 server
should be displayed.
23.7.3 Converting the DCC WebGate to SSL
Execute the following steps to convert the DCC WebGate instance to SSL. The
following sections have details.
■Generating Server Certificates
■Generating and Importing Client Certificates
23.7.3.1 Generating Server Certificates
Generate server certificates using Oracle Wallet Manager (OWM).
1. Create a Wallet using OWM.
a. Start OWM.
$ <webtier>/bin/owm
b. Select Wallet > New and follow the on screen instructions to create a
Certificate Request.
c. Save the created Wallet in an accessible location and write down the path for
future reference.
d. Select the Auto Login option and save the Wallet again.
2. Create and export the server request file as server.csr using OWM.
a. Select Operations > Export Certificate Request.
Configuring a DCC WebGate for X509 Authentication
Understanding Credential Collection and Login 23-21
b. Save as server.csr
3. Sign server.csr to generate user certificate server.pem.
You can use the OpenSSL utility as follows:
openssl x509 -req -md5 -CAcreateserial -in ohs_server.csr -days 3656 -CA /
<path>/ca.pem -CAkey /<path>/ca-key.pem -out server.pem
The values of ca.pem and ca-key.pem should be the same ones used when
generating the client certificate.
4. Import the CA certificate (ca.pem) into OWM.
a. Select Operations > Import Trusted Certificate.
b. Point to ca.pem, your CA certificate.
c. Import the CA certificate and save the wallet.
5. Import server.pem as user cert
a. Select Operations > Import User Certificate.
b. Point to the server.pem certificate generated in step 3.
c. Import the server certificate and save the wallet.
6. Edit the Oracle HTTP Server (OHS) ssl.conf file to point to this wallet as follows.
#Path to the wallet
SSLWallet "/<path to wallet>/wallet"
SSLVerifyClient require
ssl.conf is located at <webtier>/<instance_home>/config/ohs/ssl.conf.
7. Restart the OHS instance.
23.7.3.2 Generating and Importing Client Certificates
Generate and import client certificates and create a new X509 authentication scheme.
1. Create a user certificate by following the steps documented in Creating the User
Certificate.
2. Create a new Authentication Scheme named X509_DCC as illustrated in
Figure 23–10.
Add a Challenge Redirect URL. The Challenge URL should be blank.
Configuring a DCC WebGate for X509 Authentication
23-22 Administrator's Guide for Oracle Access Management
Figure 23–10 New X509 Scheme
3. Import <user_cert>.p12 into your browser.
4. Access the protected resource via its SSL port. For example:
https://<ohs_host>:<ohs_port>/index.html
A popup is displayed asking which certificate to use. Select the appropriate
certificate and the requested resource is accessed.
24
Using Password Policy 24-1
24
Using Password Policy
[21]
Access Manager provides several pages for user interactions during credential
collection. This includes login, error and password forms. This chapter contains details
on these forms and how to configure a password policy.
■Using Password Management
■Enabling Password Management
■Configuring Password Policy
■Specifying Credential Collector URLs with Password Policy
■Using the Oracle-Provided Password Forms
■Managing Global Password Policy
■Configuring Password Policy Authentication
■Completing Password Policy Configuration
■Configuring the IPFUserPasswordPolicyPlugin
24.1 Using Password Management
The Password Management feature is only supported when the identity store used is
an LDAP directory. When enabled, Password Management can be used for the
following scenarios.
■When a user account is disabled by an administrator, the user is not allowed to
enter the system. An appropriate error message is displayed if the user requests
access.
■When a user account is locked by an administrator (whether permanently or
temporarily due to incorrect passwords or challenges), the user is not allowed to
enter the system. An appropriate error message is displayed if the user requests
access.
■A user can be forced by the administrator to change a password if specific values
are set in the user’s LDAP entry.
■When a user has to change a soon-to-be expiring password, a screen is displayed
from which the user can choose one of the following options: change the password
now or continue to the requested page without changing the password.
■If a user submits a password with invalid characters during a password reset
operation, an error message can be displayed with the password creation rules
that the user must follow.
Enabling Password Management
24-2 Administrator's Guide for Oracle Access Management
Using the Oracle-Provided Password Forms has screenshots of the error messages
discussed.
Caveats for Integrated Deployments
When you are using Oracle Identity Management and Oracle Access Management
with Oracle Internet Directory, there are two sets of password policy definitions and
enforcement. Password Policy Definition can be configured in both Oracle Identity
Management and in Oracle Internet Directory. Password Policy Enforcement occurs
according to the following:
■Oracle Access Management enforces state policies (incorrect password, for
example) during Web access; Oracle Internet Directory enforces its own state
policies as well as LDAP operations (bind and compare, for example).
■Oracle Identity Management enforces value policies (characteristics of the
password) during user creation of the password update; Oracle Internet Directory
enforces it's own value policies as well for policies for LDAP operations (add,
modify for example).
Password Policy is only certified when the configured Identity Store is an LDAP
directory. It is not certified with a virtualized LDAP directory (for example, Oracle
Virtual Directory fronting another data repository) or a non LDAP directory
Any LDAP directory (such as Oracle Internet Directory) has a way to configure
password policies that define lexical constraints to which the user password must
conform (minimum characters, maximum length of time the password is valid, use of
special characters, etc.) This password policy gets applied when the user's password is
changed in the LDAP directory. To make sure that this LDAP directory password
policy does not conflict with the password policy configured in OAM, the
administrator has to manually study the LDAP password policy and do one of the
following.
1. Make the backend LDAP identity store policies weaker or the same strength as the
Oracle Identity Management and Oracle Access Management policies. However,
this leads to a double enforcement.
2. Disable native LDAP password policy validation, which unfortunately leaves no
enforcement for direct LDAP operations.
24.2 Enabling Password Management
Use the Oracle Access Management Console to enable the Password Management
service. This is done as a configuration of the defined user identity store. The
Password Management feature is only supported when the identity store used is an
LDAP directory.
1. Log in to the Oracle Access Management Console as Administrator.
2. Click Configuration at the top right of the Oracle Access Management Console.
3. Click User Identity Stores in the Configuration console.
4. Select the appropriate LDAP directory to enable Password Management.
Alternately, click Create to register a user identity store. See Chapter 5, "Managing
Data Sources" for details.
5. Under Password Management, check Enable Password Management.
6. Define the Password Management parameters and click Apply to save.
Table 24–1 documents the parameters used for configuration.
Configuring Password Policy
Using Password Policy 24-3
24.3 Configuring Password Policy
Once Password Management is enabled, you can configure the Password Policy.
Administrators define password policy based on enterprise requirements. When
configured, the Password Options and Challenge Options are used by both the
Embedded Credential Collector (ECC) and Detached Credential Collector (DCC). See
Chapter 23, "Understanding Credential Collection and Login" for information on the
Credential Collection options.
Follow this procedure to access the Password Policy configuration page.
1. Log in to the Oracle Access Management Console as Administrator.
2. Click Application Security at the top right of the Oracle Access Management
Console.
3. Click Password Policy in the Application Security console.
Figure 24–1 is a screenshot of the Password Policy page in the Oracle Access
Management Console. Table 24–2 below it describes the options in detail.
Table 24–1 Password Policy Configuration Parameters
Parameter Description
Enable Password
Management
Enables password management for this identity store. If password
management is not enabled, the password plugin returns right
away and the status is not captured.
Use Oblix Schema If checked, the Oblix schema is used. If not, the Oracle Schema is
used.
Global Common ID
Attribute
This is the userid attribute used for password policy verification to
make sure the password doesn’t contain the user id attribute value.
First Name Attribute This is the first name attribute used for password policy verification
to make sure the password doesn’t contain the first name attribute
value.
Last Name Attribute This is the last name attribute used for password policy verification
to make sure the password doesn’t contain the last name attribute
value.
Email Address Attribute This is the email attribute of the users in this identity store. It is
used for password policy verification.
Configuring Password Policy
24-4 Administrator's Guide for Oracle Access Management
Figure 24–1 Password Policy Configuration Page
Table 24–2 describes the configurable Password Policy options (as read from left to
right in the console). These elements are used by both the ECC and DCC.
Table 24–2 Password Policy Elements
Element Description
Minimum Uppercase Characters Defines the minimum number of uppercase characters required in a
password.
Minimum Lowercase Characters Sets the minimum number of lowercase characters required in a
password.
Minimum Alphabetic Characters Defines the minimum number of special characters allowed in the
password.
Minimum Numeric Characters Sets the minimum number of numeric characters required in a
password.
Minimum Alphanumeric
Characters
Defines the minimum number of alphanumeric characters required in
a password.
Minimum Special Characters Sets the minimum number of special characters required in a
password.
Maximum Special Characters Defines the maximum number of special characters allowed in a
password.
Minimum Unicode Characters Defines the minimum number of unicode characters required in a
password.
Maximum Unicode Characters Sets the maximum number of unicode characters allowed in a
password.
Specifying Credential Collector URLs with Password Policy
Using Password Policy 24-5
24.4 Specifying Credential Collector URLs with Password Policy
Regardless of the credential collection method, you can configure one global password
policy that applies to all Access Manager-protected resources (using the Password
Policy Validation Module in the authentication scheme). The relevant URLs for the
credential collector and related forms must be specified as outlined in Table 24–3.
Minimum Password Length Sets the total minimum number of characters required in a password.
Maximum Password Length Defines the total maximum number of characters allowed in a
password.
Characters Required Defines the specific characters that are required in a password. No
delimiter is needed or allowed in this definition.
Characters Not Allowed Sets the specific characters that cannot be used in a password. No
delimiter is needed or allowed in this definition
Characters Allowed Defines all allowed characters in a password. No delimiter is needed
or allowed in this definition
Substrings Not Allowed Specific character strings that are not allowed in a password. Use a
comma as the delimiter in this definition.
Alphabetic Character Must Start
Password
Specifies that the first character in a password must be alphabetic,
when checked.
Can Include User’s Last Name Specifies that the user's last name is allowed in the password, when
checked.
Can Include User’s First Name Specifies that the user's first name is allowed in the password, when
checked.
Can Include User ID Specifies that the user's userID is allowed in the password, when
checked.
Warn after (days) Defines the number of days before a designated date in which a user
will be warned about password expiration. For example, you enter 30
in the Expires After (Days) field, and 20 in the Warn After (Days) field,
and the password is created on November 1. On November 21, the
user will be informed that the password will expire on December 1.
This field accepts values from 0 to 999.
Maximum Attempts Identifies the maximum number of login attempts a user can make
before a lockout.
Expire after (days) Defines the period of time (in days) that the password is valid.
Lockout Duration (minutes) Identifies the period of time the user is locked out (in minutes) after
the designated number of failed login attempts. After this period, the
user can attempt a fresh login.
Permanent Lockout specifies permanent lockout after the designated number of failed
login attempts.
Disallow Last Defines the number of previous passwords that cannot be used when
the user changes her password.
Password Dictionary File Identifies the physical file on OAM Servers that contain the list of
restricted words that can not be specified in a password.
Password File Delimiter Defines the delimiter used in the Password Dictionary file to separate
various words. For example, if the file contains
abc,def,welcome
and
the dictionary delimiter is comma (,), the words that are restricted and
cannot be used in a user password are
abc def
and
welcome
.
Password Service URL The location of various password pages.
Table 24–2 (Cont.) Password Policy Elements
Element Description
Specifying Credential Collector URLs with Password Policy
24-6 Administrator's Guide for Oracle Access Management
Table 24–3 Specifying Credential Collectors and Related Forms for Authentication
In the . . . For the ECC . . . For the DCC . . .
OAM Agent Registration
DCC Only
N/A. Check the box beside Allow Management
Operations in the OAM Agent registration page.
See Also: "Enabling DCC Credential Operations"
login, error, and password
pages
Pages where the user enters credentials
arrive out of the box on the OAM Server and
require no additional settings or changes.
■Login page: /pages/login.jsp
■Logout page: /pages/logout.jsp
■Error page: /pages/servererror.jsp
■Multi-step authentication: /pages/mfa_
login.jsp
Dynamic pages for general login/logout and
password policy with the DCC are excluded
automatically through the OHS
httpd.conf/webgate.conf
file--you do not need to
configure a policy to exclude these.
See WebGate host directories
$WEBGATE_
HOME/webgate/ohs/oamsso/*,
$
WEBGATE_
HOME/webgate/ohs/oamsso-bin/*pl
, and
$WEBGATE_
HOME/webgate/ohs
/
oamsso-bin/templates
/* for:
■Login page:
/oamsso-bin/login.pl
■Logout:
/oamsso-bin/logout.pl
■RSA SecurID login pages:
/oamsso-bin/securid.pl
Perl Scripts for DCC-based Login and Logout
The path name of the Perl executable must be
updated in Oracle-provided Perl scripts on the
WebGate host
$WEBGATE_
HOME/webgate/ohs/oamsso-bin/*pl
to be
consistent with the actual location.
See Also: Table 22–5, " Comparing the DCC and
ECC"
Password Policy, Password
Service URL
The Default/ECC password page is used
automatically:
Password Service URL for ECC:
/oam/pages/pswd.jsp
See Also: "Defining Your Global Password
Policy" on page 24-11
Enter the DCC password page:
Password Service URL for DCC:
/oamsso-bin/login.pl
See Also: "Locating and Updating DCC Forms for
Password Policy"
User Identity Store The user data object definition in the Access
Manager schema is extended with attributes
that enable password user status and
password history maintenance. This
definition is provided in an LDIF file, and
must be added to each user identity store
using the
ldapadd
tool. Oracle-provided
LDIFs are identified in Table 24–6.
Same for both DCC and ECC:
See Also:
■"Adding Key Password Attributes to the
Default Store" on page 24-13
■"Adding an Administrator to Change User
Attributes After a Password Change"
Password Policy Validation
Authentication Module
Enter the Default Store as the KEY_
IDSTORE_REF for each of the three plug-ins
/ steps (with an Error redirect on Failure):
See Also:
■Table 22–13, " Parameter Details for
Various Plug-ins"
■"Configuring the Password Policy
Validation Authentication Module"
Same for both DCC and ECC:
Authentication Scheme,
Challenge Redirect URL
Enter the Credential Collector host:
■For ECC, relative URI format:
/oam/server (server prepends the
host:port)
See Also: "Configuring the
PasswordPolicyValidationScheme"
Enter the Credential Collector host:
■For DCC, full URL: http://dcchost:port
■For DCC combined with Resource Webgate:
Leave empty
See Also: "Configuring the
PasswordPolicyValidationScheme"
Specifying Credential Collector URLs with Password Policy
Using Password Policy 24-7
Authentication Scheme,
Challenge URL
Enter the Credential Collector login form
relative URI:
■For ECC: /pages/login.jsp
See Also: "Configuring the
PasswordPolicyValidationScheme"
Enter the Credential Collector login form relative
URI:
■For DCC: /oamsso-bin/login.pl
See Also: "Configuring the
PasswordPolicyValidationScheme"
Authentication Scheme,
Challenge Parameters
ECC: User-defined Challenge Parameters:
OverrideRetryLimit=0
initial_command=NONE
See Also:
■Table 22–23, " User-Defined Challenge
Parameters for Authentication
Schemes"
■"Configuring the
PasswordPolicyValidationScheme"
DCC: User-defined Challenge Parameters:
■creds
■extracreds
■MaxPostDataBytes
■DCCCtxCookieMaxLength
■TempStateMode
See Also:
■Table 22–23, " User-Defined Challenge
Parameters for Authentication Schemes"
■"Configuring the
PasswordPolicyValidationScheme"
Table 24–3 (Cont.) Specifying Credential Collectors and Related Forms for Authentication
In the . . . For the ECC . . . For the DCC . . .
Using the Oracle-Provided Password Forms
24-8 Administrator's Guide for Oracle Access Management
24.5 Using the Oracle-Provided Password Forms
Access Manager provides several pages for user interactions during credential
collection, as described in Table 24–4, " Credential Collector Password Pages". The
location can be customized, depending on the desired topology of the authentication
scheme being developed.
Server Error Mode Same for both DCC and ECC.
See: "Setting the Error Message Mode for
Password Policy Messages" on page 24-21
Same for both DCC and ECC.
See: "Setting the Error Message Mode for Password
Policy Messages" on page 24-21
Authentication Policy Credential collectors in authentication
policies:
■ECC: Use any authentication scheme
configured for the ECC in the
application domain for the protecting
Webgate (Resourcre Webgate)
See Also: "Adding Your
PasswordPolicyValidationScheme to ECC
Authentication Policy"
Credential collectors in Authentication Policies:
DCC Separate from Resource Webgate:
***Protecting (Resource) Webgate Application
Domain, (Authentication Policy protecting
resources), use the DCC-related Authentication
Scheme.
***DCC Webgate Application Domain,
Authentication Policy protecting resources, use
the DCC-related Authentication Scheme. Consider:
--With No Action URL: DCC uses the
default /oam/server/auth_cred_submit, which is
automatically protected with the DCC-related
authentication scheme.
--With an Action URL: Explicitly protect the
specified Action URL with the DCC Scheme.
See Also: "Adding
PasswordPolicyValidationScheme to
Authentication Policy for DCC"
Logout Configuration ECC:
In the protecting (Resource) Webgate Agent
registration, configure the
Logout URL
as
shown in Table 15–3, " Elements on
Expanded 11g and 10g WebGate/Access
Client Registration Pages"
See "Configuring Centralized Logout for 11g
WebGates" on page 27-4
DCC:
■In the DCC Agent registration page the
Logout Redirect URL is ignored.
■In the protecting (Resource) Webgate
registration, define the:
Logout Redirect URL
:
http//
dcchost:port/
oamsso-bin/logout.pl
Note: If the Resource Webgate's Logout Redirect
URL is anything other than
logout.*
, then that
URL must be defined in the
Logout URL
parameter
of the DCC Webgate registration. For example:
If Resource Webgate registration has:
Logout Redirect URL
http//dcchost:port/someurl.html
then DCC Webgate registration must have:
Logout URL:
someurl.html
■DCC: Perl path must be updated in
Oracle-provided scripts.
See "Configuring Logout When Using Detached
Credential Collector-Enabled WebGate" on
page 27-6
Table 24–3 (Cont.) Specifying Credential Collectors and Related Forms for Authentication
In the . . . For the ECC . . . For the DCC . . .
Using the Oracle-Provided Password Forms
Using Password Policy 24-9
Table 24–5 shows the password forms provided. The default pages can be customized
for your enterprise, or replaced entirely with custom pages. For example, you can
design, implement, and deploy a custom page that displays a different version of the
login form for a mobile browser than is used for a desktop browser.
Table 24–4 Credential Collector Password Pages
Credential
Collector Description
ECC pages The default embedded credential collector jsp forms, by default, reside on the OAM
Servers.
■Login page: /pages/login.jsp
■Logout page: /pages/logout.jsp
■Error page: /pages/servererror.jsp
■Multi-step authentication page: /pages/mfa.jsp
DCC pages Dynamic pages general login/logout and password policy with the DCC are excluded
automatically through the OHS httpd.conf/webgate.conf file--you do not need to
configure a policy to exclude these. See the Webgate host:
■
$WEBGATE_HOME/webgate/ohs/oamsso/*
■$
WEBGATE_HOME/webgate/ohs/oamsso-bin/*pl
(update the Perl location in the
first line of the login, logout, and securid scripts)
■
$WEBGATE_HOME
/webgate/ohs/
oamsso-bin/templates
/*
See Also:
For details about customizing pages and messages, see the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management.
Table 24–5 Password Management Forms and Functions
Form Function
Sign In Form The standard login form provides fields for userID and password. Clicking the
Login button initiates authentication processing governed by the configured
authentication module.
See: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about customizing login forms.
Sign In Error This standard login form appears when an error occurs. The text in red identifies
the errors, which can be suppressed or displayed.
See: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about suppressing or displaying.
Password Expiry
Notification
The following message appears to inform the user that her password will expire,
based on the notification policy.
Managing Global Password Policy
24-10 Administrator's Guide for Oracle Access Management
24.6 Managing Global Password Policy
Authentication involves determining which credentials a user must supply when
requesting access to a resource, gathering credentials, and returning a response that is
based on the results of credential validation. Access Manager authentication
processing relies on an authentication module (or plug-in) to define the rules
governing requirements and transmission of information to the back-end
authentication scheme. By default, Access Manager supports using the OAM Server
Embedded Credential Collector (ECC) for authentication processing. However, you
can also configure an 11g WebGate to use as an detached credential collector (DCC)
instead.
Change Password
Form
Based on password expiration policy configuration, the following window
appears to enforce the policy and require user to change his password.
Password Change
Success
The following message appears to confirm the password change was successful.
Locked or Disabled
User Account
Based on the password policy, user account lockout occurs when supplied
credentials fail during the maximum allowed login attempts.
Table 24–5 (Cont.) Password Management Forms and Functions
Form Function
Managing Global Password Policy
Using Password Policy 24-11
Regardless of whether you choose the ECC or DCC, you can configure a global
password policy that applies to all Access Manager-protected resources. The following
overview provides links to topics that describe how to configure and use the password
policy. Unless explicitly stated, all tasks apply equally to the ECC and DCC. Skip any
tasks that do not apply to your deployment.
Task overview: Password policy management includes
1. Defining Your Global Password Policy
2. Adding Key Password Attributes to the Default Store
3. Adding an Administrator to Change User Attributes After a Password Change
4. Configuring Password Policy Authentication
5. DCC: Configuring 11g WebGates and Authentication Policy for DCC
6. Completing Password Policy Configuration
7. Testing Your Multi-Step Authentication
24.6.1 Defining Your Global Password Policy
Users with Oracle Access Management Administrator credentials can use the
following procedure to define a common password policy based on enterprise-defined
requirements.
The specifications in this example are for illustration only. Your environment will be
different.
To configure the password policy in Oracle Access Management
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Password Policy.
3. On the Password Policy page, enter the Password Service URL for the desired
credential collector login page (ECC or DCC, Table 24–3).
4. On the Password Policy page, enter values (Table 24–2) based on requirements for
your enterprise. For example:
Note: Both the ECC and DCC facilitate multi-step authentication
flows where credentials are not provided all at once. This increases the
flexibility of interaction with users or programmatic entities for the
purpose of collecting authentication-related information. For more
information, see Section 22.7, "Orchestrating Multi-Step
Authentication with Plug-in Based Modules."
Note: The only difference between a global password policy for the
ECC versus the DCC is
Password Service URL
, which is credential
collector-specific and defaults to ECC pages as shown in Step 2.
ECC Password Service URL DCC Password Service URL
/pages/login.jsp /oamsso-bin/login.pl
Managing Global Password Policy
24-12 Administrator's Guide for Oracle Access Management
■Warn After 3
■Expire After 20
■Permanent Lockout (Disable)
■Lockout duration 1
■Minimum Special Characters 1
5. Click Apply to submit the policy.
6. Proceed as needed for your environment; skip any tasks that have been completed
already:
■Adding Key Password Attributes to the Default Store
■Adding an Administrator to Change User Attributes After a Password Change
24.6.2 Designating the Default Store for Your Password Policy
The Password Policy operates only with the designated Default Store. Administrator
roles and credentials must reside in the System Store.
To designate a Default Store for the global password policy
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, click User Identity Stores.
3. Set the System Store: Administrator roles and credentials must reside in this store.
a. Open the page of the store to designate as the System Store.
b. Check Set as system store (for domain wide authentication and authorization
operations).
c. Click Apply.
d. Add Administrators: See "Understanding Administrator Roles" on page 5-26.
e. Authentication Module: Set the LDAP Authentication Module used by the
OAMAdminConsoleScheme
(authentication scheme) to use this System Store.
f. Configure one or more authentication plug-ins to use this store, as described
in "Orchestrating Multi-Step Authentication with Plug-in Based Modules".
4. Set Default Store: This store is required for Password Policy, Security Token
Service, and migration when patching.
a. Open the page of the store to designate as the Default Store.
b. Check the box beside Set as default store.
c. Authentication Module: Locate
OAMAdminConsoleScheme
and confirm that the
LDAP module does not refer to this store. See "Managing Native
Authentication Modules".
d. Authorization Policy Conditions: Choose the desired user identity store
when setting Identity Conditions in Authorization Policies. See "Defining
Authorization Policy Conditions" on page 25-43.
e. Token Issuance Policy Conditions: Choose the desired user identity store
when setting Identity Conditions in Token Issuance Policies. See "Managing
See Also: "Using the System Store for User Identities"
Managing Global Password Policy
Using Password Policy 24-13
Token Issuance Policies, Conditions, and Rules" on page 45-27.
5. Close the registration page.
24.6.3 Adding Key Password Attributes to the Default Store
The Password Policy operates only with the designated Default Store. This section
provides steps for extending the default store schema for Oracle Access Management
password policy operations.
■About Extending the Default Store Schema
■Extending the Default Store Schema with Password Policy Attributes
24.6.3.1 About Extending the Default Store Schema
The LDIF (Lightweight Directory Interchange Format) files distributed as part of
Access Manager are meant to extend the schema with required object classes.
Generally, these are applied using the idmConfigTool or Access Manager and Oracle
Identity Management wiring has been performed manually.
The user data object definition in the Access Manager schema is extended with
attributes that enable password user status and password history maintenance. This
definition is provided in an LDIF file, and must be added to each user identity store
using the
ldapadd
tool. Oracle-provided LDIFs are identified in Table 24–6.
The attributes that enable password user status and password history maintenance are
shown in Table 24–7. The user data object of each user identity store must include the
attributes shown in Table 24–7. These can be added with the
ldapadd
tool, LDIF
(Lightweight Directory Interchange Format) file.
Note: OAM_HOME contains installed files necessary to host Oracle
Access Management. OAM_HOME resides within the directory
structure of the Middleware home ($MW_HOME).
Table 24–6 Location of Oracle-provided LDIFs for LDAP Providers
LDAP Provider LDIF Location
OID: Oracle Internet Directory
$OAM_HOME/
oam/server/pswdservice/ldif/OID_PWDPersonSchema.ldif
OVD: Oracle Virtual Directory
$OAM_HOME/
oam/server/pswdservice/ldif/OVD_PWDPersonSchema.ldif
AD: Microsoft Active Directory
$OAM_HOME/
oam/server/pswdservice/ldif/AD_PWDPersonSchema.ldif
SJS: sun Java System Directory
$OAM_HOME/
oam/server/pswdservice/ldif/IPLANET_PWDPersonSchema.ldif
eDirectory: Novell eDirectory
$OAM_HOME/
oam/server/pswdservice/ldif/EDIR_PWDPersonSchema.ldif
ODSEE: Oracle Directory Server
Enterprise Edition
$OAM_HOME/
oam/server/pswdservice/ldif/IPLANET_PWDPersonSchema.ldif
OUD: Oracle Unified Directory
$OAM_HOME/
oam/server/pswdservice/ldif/OUD_PWDPersonSchema.ldif
SLAPD: OpenLDAP Directory
$OAM_HOME/
oam/server/pswdservice/ldif/OLDAP_PWDPersonSchema.ldif
IBM: OBM Tivoli Directory
$OAM_HOME/
oam/server/pswdservice/ldif/TIVOLI_PWDPersonSchema.ldif
Managing Global Password Policy
24-14 Administrator's Guide for Oracle Access Management
24.6.3.2 Extending the Default Store Schema with Password Policy Attributes
You can skip this task if the environment has been configured using
idmConfigTool
-prepareIDStore
.
If your user identity store has not been extended with the
oblix
schema, you must
update the schema to include the object classes required by the password service.
LDAP tools should be run from the
/bin
directory beneath
$OAM_HOME
. The following
procedure illustrates extending the Oracle Internet Directory schema. Your
environment might be different.
To extend the Default User Identity Store schema
1. Use the following command to update the Oracle Internet Directory object classes
of the designated Default Store required by the password service:
ldapadd -D "cn=orcladmin" -w <password> –h <hostname> -p 3060 –x -f $OAM_HOME/
oam/server/pswdservice/ldif/OID_PWDPersonSchema.ldif
2. Proceed to "Adding an Administrator to Change User Attributes After a Password
Change".
Table 24–7 Key Password Attributes in a Password Policy
Attribute Description Format and Values
obPasswordCreationDate The date and time used to calculate
(at the time of user login) whether
the password has expired and
whether a warning needs to be
issued.
YYYY-MM-DDThh:mm:ssZ
obPasswordHistory Used to track the number of last
passwords used. Access Manager
understands 10g
oblixPersonPwdPolicy format and
changes it to new format.
New format:
password1###password2###
Previous format:
passwordX = SHA256
(password+canonical userid)
obPasswordChangeFlag Used during forced password
change for first time user login (or
forced password change initiated by
the Administrator.
Boolean string value.
true | false
Empty string represents
false
.
obuseraccountcontrol Used to represent a disabled user. Non-encrypted string value.
activated | deactivated
Empty string represents "activated".
obpasswordexpirydate The time after which the user
password is considered to be
expired.
YYYY-MM-DDThh:mm:ssZ
Empty value represents
not
expired
.
obLockoutTime The time up to which the user is
considered to be locked out due to
too many login attempts.
Epoch value (in seconds)
representing time in the future.
Seconds
(since 01 January, 1970)
obLoginTrvCount The number of consecutive login
failures by the user. This counter is
reset on the first correct password
entry.
Non-encrypted integer value.
1,2,
3, and so on.
oblastsuccessfullogin The time of the last successful login. YYYY-MM-DDThh:mm:ssZ
oblastfailedlogin The time of the last failed login. YYYY-MM-DDThh:mm:ssZ
Configuring Password Policy Authentication
Using Password Policy 24-15
24.6.4 Adding an Administrator to Change User Attributes After a Password Change
In this procedure, you modify the Default Store (Oracle Internet Directory in this
example) to use a different privileged account as the Bind DN. This enables sufficient
privileges to change user attributes after a password change.
Prerequisites
Register a supported LDAP store and designate it as the Default Store. Ensure that the
user you add is defined within the Default Store.
To add a new Administrator
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, click Administration.
3. Add a New Administrator:
a. In the Administration page, click Grant.
b. In the dialog that appears, click Search.
c. Select the desired role from the Roles drop-down list and click Add Selected
to grant it to the selected user.
d. Click Apply to submit the changes.
4. Proceed with "Configuring Password Policy Authentication".
24.7 Configuring Password Policy Authentication
After preparing your password policy, Default Store, and Administrator, you can
develop your authentication module and scheme as described in this section.
■Configuring the Password Policy Validation Authentication Module
■Configuring the PasswordPolicyValidationScheme
■Adding Your PasswordPolicyValidationScheme to ECC Authentication Policy—If
you are using the DCC, skip this topic and go to "Configuring 11g WebGates and
Authentication Policy for DCC"
24.7.1 Configuring the Password Policy Validation Authentication Module
You must also configure the Password Policy Validation Authentication Module to use
the Default Store.
A sample module is shown in Figure 24–2. The User Password Status Step is the
unique step that relies on the
UserPasswordPolicyPlugin
.
See Also: "Understanding Administrator Roles" on page 5-26
Note: There are no credential collector dependencies when defining
the Password Policy Validation Module for authentication.
Note:
UserPasswordPolicyPlugin
is supported only when using
LDAP based authentication modules. It does not work with non
LDAP authentication modules.
Configuring Password Policy Authentication
24-16 Administrator's Guide for Oracle Access Management
Figure 24–2 Password Policy Validation Authentication Module with Orchestrated
Plug-ins
Each step identifies the action provided by a specific named plug-in.
Figure 24–3 shows the orchestration of steps within the authentication module. For
more information on modules and steps, see "About Plug-in Based Modules for
Multi-Step Authentication".
Figure 24–3 Step Orchestration for Password Policy Validation Module
Table 24–8 describes the Password Policy Validation module step details that you
specify.
See Also: "Orchestrating Multi-Step Authentication with Plug-in
Based Modules".
Configuring Password Policy Authentication
Using Password Policy 24-17
Table 24–8 User Password Step Details
Step Name Step Details Description
User Identification Step KEY_LDAP_FILTER Add the LDAP filter to the KEY_LDAP_FILTER attribute.
Only standard LDAP attributes can be used when
defining an LDAP search filter. For example:
(uid={KEY_USERNAME})
See Also: Table 25–15, " LDAP Search Filter Examples for
Access Manager" and your vendor documentation for the
exact syntax for your identity store
KEY_IDENTITY_STORE_REF The name of the registered Identity Store containing the
module users.
Default: The registered Default Store.
KEY_SEARCH_BASE_URL Base URL for user searches. For example:
dc=us,dc=example,dc=com
User Authentication Step KEY_IDENTITY_STORE_REF The name of the registered Identity Store containing the
module users.
Default: The registered Default Store.
KEY_PROP_AUTHN_
EXCEPTION
Enable or disable the propagation of LDAP errors. "KEY_
PROP_AUTHN_EXCEPTION" needs to be set to TRUE
when the Authentication module has "Password Policy
Plugin" as the next step of plugin execution; for example,
when the module has Authentication Plugin ->Password
Plugin, change this parameter to TRUE.
User Password Status Step PLUGIN_EXECUTION_MODE The execution mode of plug-in. Depending upon the
configuration, this plug-in can operate either alone or
with other default plug-ins. Values are one of the
following:
■PSWDONLY: The most preferred configuration
where only the password status is determined. The
ID and authentication must be performed using the
UserIdentification and UserAuthentication Plugins.
■AUTHWITHPSWD: Both authentication and
password are performed using this plug-in.
■AUTHONLY: Only the user identification and
authentication is performed using this plug-in
Default: PSWDONLY
OBJECTCLASS_EXTENSION_
SUPPORTED
The object classes "oblixpersonpwdpolicy" and
"oblixorgperson" are required to be present in the OAM
user's entry for successful execution of this plugin. If this
parameter is FALSE, the plugin will not add these object
classes. If this parameter is TRUE, the plugin will try to
add these object classes to the user's entry if the current
user's entry does not already have them present.
Default: FALSE
KEY_IDENTITY_STORE_REF The name of the registered Identity Store containing the
module users.
Default: The registered Default Store.
NEW_USERPSWD_BEHAVIOR Configures retroactive behavior of the new-user
password-policy. Values are either:
■FORCEPASSWORDCHANGE: Forces a password
change.
■NOFORCEPASSWORDCHANGE: The password
policy change does not affect user passwords that
are already set.
Default: NOFORCEPASSWORDCHANGE
Configuring Password Policy Authentication
24-18 Administrator's Guide for Oracle Access Management
Prerequisites
Defining Your Global Password Policy
To configure the Password Policy Validation Module
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Modules. in the Plug-ins
section.
3. In the Authentication Modules page, click Search, then click Password Policy
Authentication Module.
4. Select the Steps tab; for each of the three steps add the Default Store name in the
field beside KEY_IDSTORE_REF (Save after each change). For example:
a. User Identification Step
KEY_IDSTORE_REF: OID
Save.
b. User Authentication Step
KEY_IDSTORE_REF: OID
Save.
c. User Password Status Step
KEY_IDSTORE_REF: OID
Save.
5. Click Apply.
6. Proceed to "Configuring the PasswordPolicyValidationScheme".
POLICY_SCHEMA Policy schema for password service. Currently only
OAM10G is supported.
Default: OAM10G
URL_ACTION The type of servlet action needed for redirecting the user
to the specific password page for expiry and warning
pages. Values can be either:
■REDIRECT_POST
■REDIRECT_GET
■FORWARD
Default: REDIRECT_POST
DISABLED_STATUS_SUPPORT Specifies whether the disabled status is to be supported
and acted upon in this password service. Valid values are
either True or False.
Default: TRUE
Note: There are no credential collector dependencies when defining
the Password Policy Validation Module. Enter the Default Store as the
KEY_IDSTORE_REF for each of the three plug-ins (with an Error
redirect on Failure).
Table 24–8 (Cont.) User Password Step Details
Step Name Step Details Description
Configuring Password Policy Authentication
Using Password Policy 24-19
24.7.2 Configuring the PasswordPolicyValidationScheme
You can have multiple authentication schemes for use with the global password policy.
Users with Administrator credentials can follow this procedure to configure the
PasswordPolicyValidationScheme.
Prerequisites
Configuring the Password Policy Validation Authentication Module
To configure the PasswordPolicyValidationScheme
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Schemes in the Access
Manager section.
3. In the Search Authentication Schemes page, click Search, then click
PasswordPolicyValidationScheme.
4. Set up the scheme for your environment. For example:
■Authentication Level 2
■Default (blank)
■Challenge Method: Form
■Challenge Redirect URL:
http://
CredCollector_host:port/
■Authentication Module: Password Policy Validation Module
■Challenge URL:
/CredCollector_pages/
■Context Type: External
■Challenge Parameters:
Note: Differences between values for the ECC versus the DCC
include (Table 24–3):
■Challenge Redirect URL: Credential Collector host and port
■Challenge URL: Credential Collector Pages
■Challenge Parameters: Table 22–22
See Also: "Managing Authentication Schemes"
ECC Challenge Parameters DCC Challenge Parameters
OverrideRetryLimit=0
initial_command=NONE
OverrideRetryLimit=0
creds=userid password
Configuring Password Policy Authentication
24-20 Administrator's Guide for Oracle Access Management
5. Click Apply.
6. Proceed to "Adding Your PasswordPolicyValidationScheme to ECC
Authentication Policy".
24.7.3 Adding Your PasswordPolicyValidationScheme to ECC Authentication Policy
A user with Administrative privileges can use the PasswordPolicyValidationScheme
configured for the ECC in the application domain of the protecting Webgate (Resource
Webgate).
Prerequisites
Configuring the PasswordPolicyValidationScheme
To add PasswordPolicyValidationScheme to an ECC authentication policy
1. ECC: In the console, search for and open the appropriate Application Domain.
(See "Searching for an Existing Application Domain" on page 25-12).
2. ECC: Protect Resources using the PasswordPolicyValidationScheme:
a. Find and open your Protected Resource Policy on the Authentication Policies
tab (see "Viewing or Editing an Authentication Policy" on page 25-34):
Authentication Policies
Protected Resource Policy
b. Select PasswordPolicyValidationScheme for the Protected Resource Policy
(Authentication Scheme) and click Apply.
c. Finish updating your Authentication and Authorization policies, as desired
(Chapter 25).
See Also: Table 22–23, " User-Defined Challenge
Parameters for Authentication Schemes"
action
If not specified, the default for both ECC and DCC is
/oam/server/auth_cred_submit.
DCCCtxCookieMaxLength
(default is 4096)
TempStateMode
controls how the DCC stores the OAM Server state:
cookie or form (the default) as specified with the
parameter's value.
MaxPostDataBytes
Restricts the maximum number of bytes of POST data
submitted as user credentials.
creds
Whatever is passed must be specified in the
obMap
credentials parameter of the
ObUserSession
object, as
described in the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management
See Also: "Adding Your PasswordPolicyValidationScheme to ECC
Authentication Policy"
ECC Challenge Parameters DCC Challenge Parameters
Completing Password Policy Configuration
Using Password Policy 24-21
3. Proceed as needed for your environment:
■ECC: Completing Password Policy Configuration
■DCC: Configuring 11g WebGates and Authentication Policy for DCC
24.8 Completing Password Policy Configuration
These tasks are the same regardless of the credential collector you have configured.
Perform the following tasks to complete your password policy configuration:
■Setting the Error Message Mode for Password Policy Messages
■Overriding Native LDAP Password Policy Validation
■Disabling ECC Operation and Using DCC Exclusively
■Testing Your Multi-Step Authentication
24.8.1 Setting the Error Message Mode for Password Policy Messages
Users with administrative privileges can use this procedure to set the Server Error
Mode for password policy messages, as shown in Figure 24–4.
Figure 24–4 Server Error Mode for Password Management
Prerequisites
■Managing Global Password Policy
■Configuring Password Policy Authentication
■Optional: Configuring 11g WebGates and Authentication Policy for DCC
To set the error message mode
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Access Manager from the Settings drop-down
list.
3. In the Load Balancing section, set the Server Error Mode to Internal.
4. Click Apply.
5. Proceed with "Overriding Native LDAP Password Policy Validation".
24.8.2 Overriding Native LDAP Password Policy Validation
As described earlier, you need to disable native LDAP password policy validation
before the non-native password policy can be used.
For example, with Oracle Internet Directory registered for Oracle Access Management,
native password policy is generally located as follows:
Completing Password Policy Configuration
24-22 Administrator's Guide for Oracle Access Management
dn: cn=default,cn=pwdPolicies,cn=Common,cn=Products,cn=OracleContext,<DOMAIN_
CONTAINER>
You can disable the Oracle Internet Directory password policy by setting the
orclpwdpolicyenable
parameter to zero (0).
The following procedure is only an example. Your environment will be different.
Prerequisites
Setting the Error Message Mode for Password Policy Messages
To override native LDAP policy with Oracle Access Management password
policy
1. Refer to the manual from your LDAP directory vendor.
2. Oracle Internet Directory: Disable native policy by setting
orclpwdpolicyenable
to zero (0).
■Confirm the location of the password policy for your domain.
■When you are sure you have the proper native LDAP policy, disable the
policy. For example:
orclpwdpolicyenable = 0
3. Proceed as follows, depending on your deployment:
■"Disabling ECC Operation and Using DCC Exclusively"
■"Testing Your Multi-Step Authentication"
■Chapter 27: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate"
24.8.3 Disabling ECC Operation and Using DCC Exclusively
You can skip this task to allow the DCC and ECC to co-exist, and maintain
authentication schemes and policies for both credential collectors.
To disable ECC, you must edit the oam-config.xml file as described here. Generally,
Oracle recommends not editing oam-config.xml. Changes to this file could result in
lost data or overwriting of the file during data sync operations. However, there is no
other way to disable the ECC completely in favor of the DCC.
Caution: Disabling the native LDAP password policy validation
leaves no enforcement for direct LDAP operations. There are various
password policies in Oracle Internet Directory, including one in the
following:
dn:
cn=default,cn=pwdPolicies,cn=Common,cn=Products,cn=OracleContext
However, this might not apply to your domain.
See Also: The various attributes described in Oracle Fusion
Middleware Administrator's Guide for Oracle Internet Directory
Completing Password Policy Configuration
Using Password Policy 24-23
Prerequisites
Configuring 11g WebGates and Authentication Policy for DCC
To disable ECC operation and use DCC exclusively
1. Make your changes on the node running the AdminServer to minimize possible
conflicts that another AdminConsole user might make.
2. Back up oam-config.xml in $DOMAIN_HOME/config/fmwconfig/ and store the
copy in a different location for use later if needed.
3. Locate the
ECCEnabled
parameter in the
OAMServicesDescriptor
section and make
the changes shown here in bold:
<Setting Name="OAMServicesDescriptor" Type="htf:map">
... ...
<Setting Name="ECCEnabled" Type="htf:map">
<Setting Name="ServiceStatus" Type="xsd:boolean">false</Setting>
</Setting>
4. Increment by 1, the configuration version number at the top of the file to associate
your change and enable automatic propagation and dynamic activation across all
running OAM Servers (see the next to last line of this example):
<Setting Name="Version" Type="xsd:integer">
<Setting xmlns="http://www.w3.org/2001/XMLSchema"
Name="NGAMConfiguration" Type="htf:map:>
<Setting Name="ProductRelease" Type="xsd:string">11.1.1.3</Setting>
<Setting Name="Version" Type="xsd:integer">2</Setting>
</Setting>
5. Proceed to "Testing Your Multi-Step Authentication".
24.8.4 Testing Your Multi-Step Authentication
This section provides a number of evaluations you can perform to confirm that your
deployment is working properly.
To confirm your multi-step authentication
1. Confirm access after login:
a. Open a new browser and request a resource.
b. Log in with your user credentials.
c. Confirm that you have access to the resource.
2. Confirm no access on incorrect login:
a. Open a new browser and request a resource.
b. Log in with incorrect user credentials.
c. Confirm that you must re-authenticate.
Note: After disabling the ECC, access to resources protected by
schemes and policies that rely on the ECC will be prohibited,
including access to the Oracle Access Management Console.
See Also: Chapter 27, "Configuring Centralized Logout for Sessions
Involving 11g WebGates"
Configuring the IPFUserPasswordPolicyPlugin
24-24 Administrator's Guide for Oracle Access Management
3. Confirm lockout after exceeding maximum incorrect login attempts:
a. Open a new browser and request a resource.
b. Log in with incorrect user credentials repeatedly.
c. Confirm that the user account is locked.
4. Modify and evaluate your password expiry policy:
a. Log in to the Oracle Access Management Console.
b. In your password policy, reset the expiry and lockout periods (Table 24–2) so
that you will see warnings on your next login.
c. Save the policy updates.
d. Open a new browser and request a resource.
e. Verify the warning page appears advising that the password will expire.
f. Click the link to continue without password change.
5. Change your password:
a. Open a new browser and request a resource.
b. On the password expiry warning page, click the link to change your
password.
c. On the password change page, enter your correct old password.
d. In the new password field, enter a different new password that does not
follow the password policy and confirm the password validation error.
e. Enter a new password that meets requirements and confirm success and
access to the resource.
24.9 Configuring the IPFUserPasswordPolicyPlugin
The Identity Password Framework (IPF) password policy plugin handles the
password related flows during login. Configuring the IPF password policy plugin is
the most critical step in making sure that OAM and OIM LDAP applications can work
in tandem. Using the IPF password plugin in OAM makes sure that password features
act across both OAM and OIM in similar ways. This section contains the following
information:
■Enabling the IPF Password Service
■Configuring Password Policy for IPF Password Service
■Extending the LDAP Definitions
■Configuring the Password Policy Validation Authentication Module and Scheme
■Setting Up the Forgot Password Module
24.9.1 Enabling the IPF Password Service
The IPF password service can be enabled in a newly installed (not upgraded)
environment by manually editing oam-config.xml to add the following line:
<Setting Name="pswdServiceDataVersion" Type="xsd:string">3</Setting>
This procedure assumes:
Configuring the IPFUserPasswordPolicyPlugin
Using Password Policy 24-25
■The WebLogic Server, Oracle Internet Directory, Oracle HTTP Server and a
database are installed.
■Oracle Access Management is installed in DB mode and configured to use OID as
a user store.
■WebGate 11g is installed and configured against the policy server.
■The exact mechanism of extending LDAP directory for each directory type.
1. Shut down the entire domain including the WebLogic Admin Server and all OAM
Managed Servers.
2. Locate the correct
oam-config.xml
file in
<DOMAIN_HOME>/config/fmwconfig/
and
make a backup of it before editing.
3. Modify the file so it contains the following snippet.
<Setting Name="PasswordService" Type="htf:map">
<Setting Name="pswdServiceDataVersion" Type="xsd:string">3</Setting>
<Setting Name="pswdServiceUrl" Type="xsd:string">/oam/pages/pswd.jsp</Setting>
</Setting>
Be sure to increment the version number of the file by 1 to ensure that the changes
are not overwritten by the Oracle Access Management Console.
4. Save the file.
5. Restart the WebLogic Admin Server.
6. Restart the OAM Managed Servers.
As a verification step, check <DOMAIN_HOME>/config/fmwconfig/oam-config.xml
on each of the OAM Managed Server nodes to ensure that the updated version has
propagated correctly.
24.9.2 Configuring Password Policy for IPF Password Service
See Configuring Password Policy for details. Note that the password policy in OAM
should be in sync with that of OAM LDAP to work consistently between both
products. It is up to the administrator to ensure that the policies are indeed the same
and consistent.
24.9.3 Extending the LDAP Definitions
Depending on the type of the directory, add the required objectclass schema
definitions so that the LDAP directory can use these to extend the user objectclass. The
appropriate schema files are located in $IDM_HOME/modules/oracle.idm.ipf_
11.1.2/scripts/ldap. Table 24–9 documents the LDIF file to use with supported LDAP
directories.
Table 24–9 Included LDIF Schema Files
LDAP Directory LDIF Schema File
OID OID_OblixSchema.ldif, OID_OracleSchema.ldif
AD AD_OblixSchema.ldif, AD_OracleSchema.ldif
OUD OUD_OblixSchema.ldif, OUD_OracleSchema.ldif
ODSEE IPLANET_OblixSchema.ldif, IPLANET_OracleSchema.ldif
OPENLDAP OLDAP_OblixSchema.schema, OLDAP_OracleSchema.schema
Configuring the IPFUserPasswordPolicyPlugin
24-26 Administrator's Guide for Oracle Access Management
24.9.4 Configuring the Password Policy Validation Authentication Module and Scheme
The Password Policy Validation Authentication Module needs to be configured to use
the required identity store, as well as some of the operations configuration as per
installation requirements. There are no credential collector dependencies when
defining the Password Policy Validation Module for authentication. The User
Password Status Step is the unique step that relies on the
IPFUserPasswordPolicyPlugin. See "Configuring the Password Policy Validation
Authentication Module" and "Configuring the PasswordPolicyValidationScheme."
24.9.5 Setting Up the Forgot Password Module
If the forgot password feature needs to be enabled in OAM, the
IPFForgotPasswordModule is used. The forgot password authentication enables OAM
users to change their password by authenticating them using previously collected
challenges. The administrator can setup forgot password URL by following the
procedure documented in Section 2.9.1, "Administering the Forgot Password URL."
OVD OVD_OblixSchema.ldif, OVD_OracleSchema.ldif
Tivoli TIVOLI_OblixSchema.ldif, TIVOLI_OracleSchema.ldif
EDIR EDIR_OblixSchema.ldif, EDIR_OracleSchema.ldif
Table 24–9 (Cont.) Included LDIF Schema Files
LDAP Directory LDIF Schema File
25
Managing Policies to Protect Resources and Enable SSO 25-1
25
Managing Policies to Protect Resources and
Enable SSO
Access Manager Application Domains and policies can be accessed and managed
through the Oracle Access Management Console. This chapter describes how to create
and manage policies, and identify the resources to be governed by these policies. It
includes the following topics:
■Prerequisites
■Introduction to Application Domain and Policy Creation
■Understanding Application Domain and Policy Management
■Managing Application Domains Using the Console
■Adding and Managing Policy Resource Definitions
■Defining Authentication Policies for Specific Resources
■Defining Authorization Policies for Specific Resources
■Configuring Success and Failure URLs for Authorization Policies
■Introduction to Authorization Policy Rules and Conditions
■Defining Authorization Policy Conditions
■Defining Authorization Policy Rules
■Configuring Policy Ordering
■Introduction to Policy Responses for SSO
■Adding and Managing Policy Responses for SSO
■Validating Authentication and Authorization in an Application Domain
■Understanding Remote Policy and Application Domain Management
■Managing Policies and Application Domains Remotely
■Defining an Application
25.1 Prerequisites
Preview:
■Understanding Application Domain and Policy Management
See Also: Appendix D, "Reviewing Bundled, Generated, and
Migrated Artifacts"
Introduction to Application Domain and Policy Creation
25-2 Administrator's Guide for Oracle Access Management
System level requirements for tasks in this chapter include the following:
■OAM Server should be running
■Users and groups who can access a protected resource should already be created
in the User Identity Store associated with Oracle Access Management.
■Policy-enforcement Agents should be registered as described in Chapter 14.
■Shared components for use in any Application Domain should be defined, as
described in Chapter 22.
25.2 Introduction to Application Domain and Policy Creation
Application domains are the top-level constructs of the Access Manager 11g policy
model. Each Application Domain provides a logical container for resources or sets of
resources, and the associated policies that dictate who can access specific protected
resources. Certain shared components are used within each Application Domain. Each
Application Domain represents a singular application on a particular host or
Administrators can define different Application Domains for resources that reside on
the same Web server and are closely tied to each other in one way or another. For
example, an Administrator can create a single Application Domain for a financial
application and an accounts receivable application, or have a different Application
Domain for each. Configurable policies allow or deny access to the resources.
Each Access Manager Application Domain contains information regarding:
■Resource Definitions
Each resource definition in an Application Domain requires a Resource Type, Host
Identifier (for HTTP resources), and a URL to the specific resource. You can have
as many resource definitions as you need in an Application Domain.
■Authentication Policies and Responses for Specific Resources
Each authentication policy includes a unique name, one authentication scheme,
success and failure URLs, one or more resources to which this policy applies, and
Administrator-defined responses to be applied after successful authentication.
■Authorization Policies, Conditions, Rules, and Responses for Specific Resources
Each authorization policy includes a unique name, success and failure URLs, and
one or more resources to which this policy applies. In addition, Administrators can
define specific conditions that must be fulfilled for a successful authorization and
define responses to be applied after successful authorization.
■Token Issuance Policies, Conditions, and Rules for Specific Resources
Note: To enhance security, Access Manager, by default, will deny
access when a resource is not protected by a policy that explicitly
allows access.
Note: Depending on the policy responses specified for
authentication or authorization success and failure, the end user might
be redirected to a specific URL, or user information might be passed to
other applications through a header variable or a cookie value.
Introduction to Application Domain and Policy Creation
Managing Policies to Protect Resources and Enable SSO 25-3
A Token Issuance Policy defines the rules under which the Security Token Service
can issue a token for a resource (Relying Party Partner) based on the client's
identity, with the client either being a Requester Partner or an end user.
■Policy Ordering
Policy ordering is a new feature in which the administrator manually designates
the order in which policies within an application domain will be matched to
incoming requests for access to protected resources. Previous versions of Access
Manager used the best match algorithm for this purpose.
When a new application is placed behind an existing agent, the Administrator must
decide if the application should be protected by a separate (new) Application Domain
and policies or an existing Application Domain and policies. This section provides
information in the following sections to inform your choice.
■Generating Application Domains and Policies Automatically
■Managing Application Domains and Policies Remotely
■Creating or Managing an Application Domain and Policies
25.2.1 Generating Application Domains and Policies Automatically
When you register a policy-enforcement Agent with Access Manager, you can choose
to have the domain and policies generated automatically or decline the automatic
generation. An automatically generated Application Domain is named for the Agent
and seeded with default resources and basic policies (authentication and
authorization). No Token Issuance Policy is defined, though an empty container is
provided.
During Agent registration, it is presumed that the Agent resides on the same Web
Server as the application it protects. However, the Agent can be on a proxy Web server
and the application can be on a different host. Default resources are protected by basic
policies until an Administrator adds more resources or modifies or adds policies.
25.2.2 Managing Application Domains and Policies Remotely
Access Manager provides two modes to manage Application Domains and their
policies without registering or modifying the companion agent. Remote policy and
Application Domain management supports only create and update functions. Remote
management does not support removing Application Domains or policies. For more
information, see "Understanding Remote Policy and Application Domain
Management" on page 25-77.
25.2.3 Creating or Managing an Application Domain and Policies
The following overview outlines the procedures that must be performed to manually
create or manage an Application Domain and policies, and identifies the topics that
provide the steps to complete the procedure.
Task overview: Managing an Application Domain
1. Get acquainted with the following details:
Note: IAMSuiteAgent is a pre-registered Java Agent filter that
provides an Application Domain (IAMSuite) to protect the Oracle
Fusion Middleware console and other consoles. For more information,
see "Bundled 10g IAMSuiteAgent Artifacts" on page D-1.
Understanding Application Domain and Policy Management
25-4 Administrator's Guide for Oracle Access Management
■Chapter 21, "Understanding Single Sign-On with Access Manager"
■Chapter 22, "Managing Authentication and Shared Policy Components"
■Understanding Application Domain and Policy Management
■Understanding Remote Policy and Application Domain Management
2. Perform all prerequisite tasks for this chapter, as described in:
■Prerequisites
3. Start a fresh Application Domain (or view an existing one), as described in:
■Creating a New Application Domain
■Viewing or Editing an Application Domain
■Managing Policies and Application Domains Remotely
4. Add resource definitions to your Application Domain as described in:
■Adding and Managing Policy Resource Definitions
5. Define your Authentication Policy, as described in:
■Creating an Authentication Policy for Specific Resources
■Adding and Managing Policy Responses for SSO
6. Define your Authorization Policy, as described in:
■Creating an Authorization Policy and Specific Resources
■Adding and Managing Policy Responses for SSO
■Defining Authorization Policy Conditions
■Defining Authorization Policy Rules
7. Define your Token Issuance Policy, as described in:
■Chapter 45: Managing Token Issuance Policies and Conditions
■Adding and Managing Policy Responses for SSO
■Defining Authorization Policy Conditions
■Defining Authorization Policy Rules
8. Configure SSO settings and policy evaluation caches, as described in:
■Chapter 13: "Managing SSO Tokens and IP Validation"
■Chapter 13: Managing Run Time Policy Evaluation Caches
9. Validate your policies and configuration, as described in:
■Chapter 27: Validating Global Sign-On and Centralized Logout
25.3 Understanding Application Domain and Policy Management
Whether you create an Application Domain manually or you accept automatic policy
generation when registering an Agent, the elements of an Application Domain are the
same. All policies and Application Domains are managed using the Oracle Access
Management Console. For details, see the following topics:
■Navigating the Application Domain Pages
■Displaying the Application Domain Summary Page
Understanding Application Domain and Policy Management
Managing Policies to Protect Resources and Enable SSO 25-5
■Defining an Application
■Displaying the Resource Container in an Application Domain
■Displaying Authentication Policy Pages
■Displaying Authorization Policy Pages
■Displaying Token Issuance Policy Pages
25.3.1 Navigating the Application Domain Pages
Regardless of the method you choose to create an Application Domain, a unique name
is required to be used as an identifier. When you click Application Domains, a Search
page is displayed. The Create Application Domain button in the upper-right corner
enables you to start a fresh domain definition. Otherwise, enter a name (or leave the
Name field blank) and click the Search button to list existing Application Domains.
Figure 25–1 is the Application Domains Search page, controls, and the Search Results
table with its own tool bar.
Figure 25–1 Application Domains Search Page
25.3.2 Displaying the Application Domain Summary Page
When you click the name of an Application Domain in the Search results, the Name,
an optional description and Policy Ordering configuration are displayed on the
Summary tab. Other information is organized in the following tabs.
■Resources
■Authentication Policies
■Authorization Policies
■Token Issuance Policies
■Administration
Figure 25–2 is a screenshot of a typical Application Domain page. In a generated
Application Domain, the Name and Description are populated as shown. When you
create an Application Domain manually, the Description is entered by the
Administrator.
Understanding Application Domain and Policy Management
25-6 Administrator's Guide for Oracle Access Management
Figure 25–2 Example Application Domain Summary Page
25.3.3 Displaying the Resource Container in an Application Domain
The Resources tab in the Application Domain represents the container for all resource
definitions in that domain. When the Resources tab is clicked and displayed, the
Search controls are available to help you find specific definitions quickly.
Figure 25–3 illustrates Search controls that you can use to refine your resource
definition search. There is also a New Resource button in the upper-right corner. The
Search Results table provides key information about each definition found.
Figure 25–3 Search Results for Resources in an Application Domain
The default Resource Type is HTTP; default Resource URL is /**. With HTTP resource
definitions you can also search on a query string defined for that resource. The query
string can be only the Base URL and can include optional pattern-matching special
characters to represent a set of URLs. In this generated domain, the Host Identifier
matches the name of the HTTP agent that was registered. Basic information about the
policies is also provided.
Understanding Application Domain and Policy Management
Managing Policies to Protect Resources and Enable SSO 25-7
25.3.4 Displaying Authentication Policy Pages
The Authentication Policies tab provides access to defined or generated policies with
no search controls needed. When an Administrator creates an Application Domain
manually she must also manually create all policies. In a generated Application
Domain, two Authentication policies are created automatically, as shown in
Figure 25–5:
■Authentication Policy: Protected Resource Policy
■Authentication Policy: Public Resource Policy
Figure 25–4 Authentication Policies Tab
Authentication policies are local, which means that each policy applies only to the
resources specified for the policy. Each resource can be protected by only a single
authentication policy.
Figure 25–5 shows the Protected Resource Policy and the columns of information
displayed automatically on the policy's Resources tab. The Responses tab is available.
See Also:
■"Adding and Managing Policy Resource Definitions" on
page 25-13
■Appendix D, "Reviewing Bundled, Generated, and Migrated
Artifacts"
Understanding Application Domain and Policy Management
25-8 Administrator's Guide for Oracle Access Management
Figure 25–5 Authentication Policy Page: Resources and Responses
A description is provided during automatic generation:
"Policy set during domain creation. Add resources to this policy to protect them."
This generated policy uses the LDAPScheme as the authentication scheme. However,
the optional elements of the policy are not yet defined.
Protected Resources are identified on the Resources tab as
HostIdentifier/**
.
Public Resource Policy: A second authentication policy is also generated
automatically. This policy uses AnonymousScheme as the default scheme for
authentication, which allows anyone access.
Initially, this Public Resource Policy does not include or serve any Resources. The
Description tells Administrators what is needed:
Policy set during domain creation. Add resources to this policy to allow anyone
access.
25.3.5 Displaying Authorization Policy Pages
The Authorization Policies tab also provides access to defined or generated policies
with no search controls needed. In a generated Application Domain, two
Note: Initially, all resources are protected. Success and Failure URLs
and Responses must be added manually; no default values are
supplied.
Note: Administrators can change the authentication scheme, specify
Success and Failure URLs, add other resources, and define SSO
Responses.
See Also: "Introduction to Policy Responses for SSO" on page 25-68
Understanding Application Domain and Policy Management
Managing Policies to Protect Resources and Enable SSO 25-9
Authorization policies are created automatically; however, each resource can be
protected by only a single authorization policy:
■Protected Resource Policy
■Public Resource Policy
The Authorization Policy tab is shown in Figure 25–7. From this tab, you can select a
policy to edit or create a new policy.
Figure 25–6 Authorization Policies Page
The Authorization Policy page is shown Figure 25–7. It provides several tabs where
you can define the various components of this Authorization policy. Initially, all
resources are protected and access is denied. Success and Failure URLs Conditions,
Rules, and Responses must be added manually (no default are supplied).
Figure 25–7 Individual Authorization Policy Page
The Authorization Policy Resources tab is shown in Figure 25–8. You use this page to
add (or remove) resources for this policy.
Managing Application Domains Using the Console
25-10 Administrator's Guide for Oracle Access Management
Figure 25–8 Individual Authorization Policy Resources tab
Administrators can also define Conditions, Rules, and Responses for this policy. None
are generated automatically.
25.3.6 Displaying Token Issuance Policy Pages
By default, only a container for Token Issuance Policies is provided in a generated
Application Domain. Any Resources, Conditions, Rules, and Responses must be
added manually.
Figure 25–9 Token Issuance Policies Page
For specific information on this policy type, see:
■"Managing TokenServiceRP Type Resources" on page 45-30
■"Managing Token Issuance Policies, Conditions, and Rules" on page 45-27
25.4 Managing Application Domains Using the Console
Managing an Application Domain involves adding, modifying, or deleting general
and resource-related settings and policies. Each Application Domain must have a
unique name that matches the agent name. After entering a name and optional
description for the new Application Domain, click Apply to create it. This manual
creation makes available the complete series of tabs: Summary, Resources,
Authentication Policies, Authorization Policies, Token Issuance Policies.
See Also:
■"Introduction to Policy Responses for SSO" on page 25-68
■"Introduction to Authorization Policy Rules and Conditions" on
page 25-40
Managing Application Domains Using the Console
Managing Policies to Protect Resources and Enable SSO 25-11
This section describes how to create and manage an Application Domain using the
Oracle Access Management Console. It includes the following topics:
■Creating a New Application Domain
■Searching for an Existing Application Domain
■Viewing or Editing an Application Domain
■Deleting an Application Domain and Its Contents
25.4.1 Creating a New Application Domain
Decide whether you need a new Application Domain or if you can add resources to an
existing Application Domain. You can protect multiple applications using the same
Agent by manually creating one Application Domain and manually adding resources
and policies.
Users with valid Administrator credentials can perform the following task to manually
create an Application Domain using the Oracle Access Management Console.
Alternatively, Application Domains can be generated automatically during agent
registration, as described in Chapter 14 and Chapter 15.
Prerequisites
See Prerequisites at the beginning of this chapter.
To create a new Application Domain
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, select Create Application Domain from the
Create (+) menu in the Access Manager section.
3. On the Create Application Domains page, add a unique name, an optional
description and other details, then click Apply and close the Confirmation
window.
See Configuring Policy Ordering.
4. View and manage the following containers (tabs) within the Application Domain
container:
■Resources: See "Adding and Managing Policy Resource Definitions" on
page 25-13.
■Authentication Policies: See "Defining Authentication Policies for Specific
Resources" on page 25-31.
■Authorization Policies: See "Defining Authorization Policies for Specific
Resources" on page 25-35.
■Token Issuance Policies: See "Managing Token Issuance Policies, Conditions,
and Rules" on page 45-27.
Note: If the Application Domain was created using remote
registration or while registering an agent, basic policy information is
generated with it. For details, see Understanding Remote Policy and
Application Domain Management and Managing Policies and
Application Domains Remotely.
Managing Application Domains Using the Console
25-12 Administrator's Guide for Oracle Access Management
25.4.2 Searching for an Existing Application Domain
Users with valid Administrator credentials can use the following procedure to search
for a specific Application Domain.
To search for an Application Domain
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Application Domains.
3. In the page that appears, enter the name of the Application Domain you want to
find (or partial name and wild card, *, or leave the field blank to retrieve all
domains). For example:
DesiredDomain
4. Click the Search button to initiate the search.
5. Choose a name in the Search Results table to perform the desired task. For
instance:
■Edit: Click the Edit button in the tool bar to display the configuration page
and go to "Viewing or Editing an Application Domain".
■Delete: See "Deleting an Application Domain and Its Contents" before you
perform this task.
■Detach: Click Detach in the tool bar to expand the table to a full page.
■View: Select a View menu item to alter the appearance of the results table.
25.4.3 Viewing or Editing an Application Domain
Users with valid Administrator credentials can perform the following task to view or
modify an Application Domain (including its resources, policies, conditions, and
responses) using the Oracle Access Management Console.
Oracle recommends that you consider grouping similar applications into the same
Application Domain. While editing the Application Domain, be aware that different
applications are using the same domain. Editing the description and domain name are
supported.
To view or modify an Application Domain and its content
1. Locate the desired Application Domain as described in "Searching for an Existing
Application Domain".
2. Click to open each of the following tabs to add, view, modify, or delete specific
details:
■Resources: See "Adding and Managing Policy Resource Definitions" on
page 25-13.
■Authentication Policies: See "Defining Authentication Policies for Specific
Resources" on page 25-31.
Note: This Search operation is case sensitive.
See Also: "Managing Policies and Application Domains Remotely"
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-13
■Authorization Policies: See "Defining Authorization Policies for Specific
Resources" on page 25-35
■Token Issuance Policies: See "Managing Token Issuance Policies, Conditions,
and Rules" on page 45-27.
25.4.4 Deleting an Application Domain and Its Contents
Users with valid Administrator credentials can perform the following task to delete an
Application Domain (including its resources, policies, conditions, and responses)
using the Oracle Access Management Console.
Deleting the Application Domain and its content removes all referenced objects,
including the Agent registration. Using this method, if you later need to re-register the
same Agent, you can because there are no remaining references to the previous
Application Domain and its content.
Prerequisites
Ensure that resources in the domain to be deleted are placed in another Application
Domain for protection.
To delete an Application Domain
1. Locate the desired Application Domain as described in "Searching for an Existing
Application Domain".
2. Ensure that resources in the domain to be deleted are placed in another
Application Domain for protection.
3. In the Search Results table, click the Serial Number beside the desired name, and
then click the Delete (x) button in the tool bar.
4. In the Warning window, click Delete (or click Cancel to dismiss the window).
5. Check the results table to confirm the Application Domain has been removed.
25.5 Adding and Managing Policy Resource Definitions
Protecting resources requires an Application Domain containing definitions of the
specific resources. With OAM, you can protect different types of resources, including
non-HTTP/HTTPS-based resources and HTTP/HTTPS-based resources such as:
■An entire external Web site
■Specific pages in a Web site
■Partner portals
■A parts order application
■Invoice applications
■A benefits enrollment application on Web servers of an enterprise in many
countries
Each Application Domain includes a container for resource definitions, the Resources
tab. Once you have defined a resource in this container, you can add it to a policy in
the Application Domain. This section provides the following topics:
Note: During a Delete operation, if the Application Domain contains
any policy elements, you are alerted.
Adding and Managing Policy Resource Definitions
25-14 Administrator's Guide for Oracle Access Management
■Defining Resources in an Application Domain
■Searching for a Resource Definition
■Defining Resources in an Application Domain
■Viewing, Editing, or Deleting a Resource Definition
25.5.1 Defining Resources in an Application Domain
Each resource must be defined separately in an Application Domain. Within an
Application Domain, resource definitions exist as a flat collection of objects. Each
resource is defined as a specific type, and the URL prefix that identifies the resource
(document or entity) stored on a server and available for access by a large audience.
The location is specified using an existing shared Host Identifier.
Resource Definition Guidelines
1. No URL prefixes. Resource definitions are treated as complete URLs.
2. Pattern matching (with limited features) for:
' * ' and '...' are supported
3. Resources need not be unique across domains.
4. Query-string protection for HTTP URLs.
5. Each HTTP resource is defined as a URL path, and associated with a host
identifier. However, resources of other types are associated with a specific name
(not a host identifier).
6. Non-HTTP resource types are supported, with definition of specific operations.
Non-HTTP resource types are never associated with a host identifier.
7. Resources can designated as either Protected, Unprotected, or Excluded.
8. Custom resource types are allowed.
Figure 25–10 illustrates the Create Resource page.
Note: If a resource that is not explicitly marked as excluded, is not
associated with a policy, then access is denied to all users because
there is no policy match.
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-15
Figure 25–10 Create Resource Page in the Application Domain
Table 25–1 describes elements that comprise a resource definition.
Table 25–1 Resource Definition Elements
Elements Description
Type The
HTTP
type is the default; it covers resources that are accessed using either the HTTP or HTTPS
protocol. Policies that govern a particular resource apply to all operations defined for the resource.
The
wl_authen
resource type is used for Fusion Middleware application scenarios, as described in
the Oracle Fusion Middleware Application Security Guide.
The
TokenServiceRP
resource type is used to represent the Token Service Relying Party as
described in "Managing TokenServiceRP Type Resources" on page 45-30.
Any custom resource type that has been defined is listed with default resource types when you
add a resource definition (or search for resources).
See Also: "About the Resource Type in a Resource Definition" on page 25-17.
Description An optional unique description for this resource.
Host Identifier A list of host identifiers is available, which contains all identifiers that were defined as a shared
component. You must choose a host identifier to assign this resource.
Note: The combination of the host identifier and URL string that make up a resource definition
must be unique across all Application Domains.
See Also: "Managing Host Identifiers" on page 22-7.
URI Section Information will differ depending on the selected Resource Type.
Adding and Managing Policy Resource Definitions
25-16 Administrator's Guide for Oracle Access Management
Query
Name-Value list
For HTTP resource types only. You can provide a list of Name and Value pairs for use in access
policies.
See Also: "About Query String Name and Value Parameters for Resource Definitions" on
page 25-21.
Query
String
For HTTP resources, you can provide a query string for literal full query string matching within
access policies.
See Also: "About Literal Query Strings in Resource Definitions" on page 25-25.
Resource URL The value must be expressed as a single relative URL string that represents a path component of a
full URL composed of a series of hierarchical levels separated by the '/' character. The URL value
of a resource must begin with / and must match a resource value for the chosen host identifier.
Based on its contents, a URL is matched in response to an incoming request as a literal or a wild
card pattern. The special characters available to define a pattern, if included, are:
■The asterisk (*) is allowed only at the lowest, terminating level of the path. The asterisk
matches zero or more characters.
■An ellipses (…) is allowed at any level of the path except the terminating level. The ellipses
represents a sequence of zero or more intermediate levels.
See Also Table 25–2.
Operations Section You can define specific allowed operations to customize you own resource definitions.
Note: Oracle-provided Resource Types are read-only. Operations associated with Oracle-provided
Resource Types need not be defined and cannot be modified. Policies developed and applied to
resources of Oracle-provided types apply to all operations.
Operations Available Identify all HTTP operations that are allowed for this resource definition. Policies developed and
applied to this customized resource apply to only the operations you identify. Unless explicitly
noted, all of the following possible operations are for HTTP resource types:
■Connect
■Options
■Put
■Post
■Trace
■Head
■Delete
■Connect
■Login (wl_authen resource type only)
■Issue (TokenServiceRP resource type only)
Note: During Agent registration, if no operation is specified for the resource definition itself, then
All operations for that resource type are supported.
See Also: "About Resource Types and Their Use" on page 22-2.
Protection Using the controls in this section of the Resource Definition, you can identify the desired level of
protection for this resource and name the policies to be used.
Table 25–1 (Cont.) Resource Definition Elements
Elements Description
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-17
After adding the resource, it is grouped under the Resources node of the named
Application Domain. When you create policies all defined resources for the domain
are listed and you can choose one or more for inclusion in the policy.
For more information about different specifications within a resource definition, see
the following topics:
■About the Resource Type in a Resource Definition
■About the Host Identifier in a Resource Definition
■About the Resource URL, Prefixes, and Patterns
■About Query String Name and Value Parameters for Resource Definitions
■About Literal Query Strings in Resource Definitions
■About Run Time Resource Evaluation
25.5.1.1 About the Resource Type in a Resource Definition
When adding a resource definition to an Application Domain, Administrators must
choose from a list of defined Resource Types. Native Resource Types are read-only
cannot be modified or deleted; these include HTTP, TokenserviceRP, and wl_authen.
Protection Level Choose the appropriate protection level from the following:
■Protected (the default)
Protected resources are associated with a protected-level Authentication policy that uses a
variety of authentication schemes (LDAP, or example).
Authorization policies are allowed for protected resources.
Responses, conditions, auditing, and session management are enabled for protected
resources using a policy that protects the resource.
■Unprotected
Unprotected resources are associated with an unprotected-level Authentication policy (level
0) that can use a variety of authentication schemes (LDAP, for example).
Authorization policies are allowed for unprotected resources, and a basic one is needed to
allow such access. However, an elaborate policy with conditions and responses is irrelevant.
Responses, conditions, and auditing are enabled for Unprotected resources using a policy
that protects the resource. Only Session Management is not enabled. Access to Unprotected
resources incur an OAM Server check from Webgate, which can be audited.
■Excluded (these are public)
Only HTTP resource types can be excluded. Typically security insensitive files like Images
(*.jpg, *.png), protection level Excluded resources do not require an OAM Server check for
Authentication, Authorization, Response processing, Session management, and Auditing.
Excluded resources cannot be added to any user-defined policy in the console.
While allowing access to excluded resources, Webgate does not contact the OAM
Server.Therefore, such access is not audited. Most regular resource validations apply to
Excluded resources. However, excluded resources are not listed when you add resources to a
policy.
There is no Authentication or Authorization associated with the resource.
Authentication Policy A list of Authentication policies based on the specified resource protection level becomes
available. Only policies within this domain, and that match the specified protection level, are
listed.
Authorization Policy A list of authorization policies defined in the domain become available from which you can
choose the one to protect this resource.
See Also: "About Resource Types and Their Use" on page 22-2
Table 25–1 (Cont.) Resource Definition Elements
Elements Description
Adding and Managing Policy Resource Definitions
25-18 Administrator's Guide for Oracle Access Management
When adding an HTTP type resource to an Application Domain, Administrators
choose from a list of existing host identifiers and then add the resource URL.
Operations associated with the HTTP resource type need not be defined by an
Administrator. Instead, policies apply to all HTTP operations.
Table 25–2 shows sample URL values for resources. For more information, see "About
the Resource URL, Prefixes, and Patterns" on page 25-18.
25.5.1.2 About the Host Identifier in a Resource Definition
Administrations identify resources in an Application Domain by the host where the
resources reside and the resource URL.
Host identifiers create a context for each resource, which is useful when adding
resources that have the same URL paths on different computers. Administrations can
protect all of these resources in the same way within the same Application Domain.
The only variable that distinguishes one set of resources from another is identification
of its host computer.
All defined host identifiers appear on the Host Identifiers list on the Resources page.
When adding a resource to an Application Domain, administrations must choose one
host identifier for the computer hosting the resource.
To ensure that Access Manager recognizes the URL for a resource, Access Manager
must know the various ways used to refer to that resource's host computer.
25.5.1.3 About the Resource URL, Prefixes, and Patterns
During automated Application Domain generation, a URL prefix is defined under
which all resources are protected. Resources are linear, not hierarchical. Resource
definitions are treated as complete URLs.
Administrations identify individual resources in the Application Domain using a
specific resource URL. Individual resource URLs need not be unique across domains.
Table 25–2 HTTP Resources Sample URL Values
Resource Sample URL Values
Directories ■/mydirectory
■/mydirectory/**
Pages ■/mydirectory/projects/index.html
■/mydirectory/projects/*.html
■/mydirectory/.../*.html
Web applications ■/mydirectory/projects/example.exe
■/mydirectory/projects/*.exe
■/mydirectory/**
Note: Non-HTTP resource types are not associated with a host
identifier. Instead, Administrators must enter the type's name into the
Resource URL field of the resource definition page.
Note: No host identifier is associated with a non-HTTP resource
type.
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-19
However, the combination of a resource URL, Query String, and a host identifier must
be unique across domains.
An HTTP type resource is expressed as a single relative URL string representing a
path. The string is composed of a series of hierarchical levels separated by the '/'
character. Based on its content, a URL is matched in response to an incoming request
as a literal or a wild card pattern.
URL Prefixes
The Access Manager policy model does not support a resource prefix. In other words,
there is no policy inheritance.
If a policy is defined for
/mydirectory/projects/
, it only applies to this URL (and
does not apply to
/mydirectory/projects/index.html
, for example).
If you need a policy for all resources with the same prefix string, you can define the
resource using special characters (three periods ... (ellipsis) or * (asterisk) for instance:
/mydirectory/projects/.../*
.
URL Patterns, Matching, and Precedence
Administrators can create granular URL patterns to specify the fine-grained portion of
a resource's namespace. All matching is case insensitive.
■Supported wildcard matching is provided for the patterns in Table 25–3
■Sample Resource URLs and their correctness are shown in Table 25–4
Note: The Access Manager policy model does not support a resource
prefix. In other words, there is no policy inheritance.
Table 25–3 Supported Wildcards in Resource URL Patterns (Precedence Order)
Pattern Description Example
/** The default. Matches any sequence of zero or more
characters that starts with the forward slash character (/).
You can use this pattern to protect a path under a specific,
named directory.
Note: This is not an existing 10g wildcard. In 10g, the /.../*
pattern yielded an exclusive match that did not include the
root of the level at which the pattern was defined. For
example, /foo/.../* matched /foo/bar and the root
directory /foo/ itself, but it wouldn't match foo/ or /foo.
10g had the notion of a prefix (the "root"), and most
evaluation occurred after striping off the prefix.
·/**
Matches
/foo/bar
/foo/
Literals The resource's pattern contains no special characters.
{pattern1,patter
n2,...}
Matches one from a set of patterns.
The patterns inside the braces can themselves include any
other special characters (except braces; sets of patterns
cannot be nested).
■a{ab,bc}b matches aabb and abcb.
■a{x*y,y?x}b matches axyb, axabayb, ayaxb,
and so on.
Adding and Managing Policy Resource Definitions
25-20 Administrator's Guide for Oracle Access Management
Table 25–4 illustrates a number of resource definitions within an Application Domain,
organized alphabetically according to the Host Identifier and Resource URL. The
right-hand column in Table 25–4 declares whether the form is correct or not.
[range or set] Matches one from a set of characters.
A set can be specified as a series of literal characters or as a
range of characters. A range of characters is any two
characters (including -) with a hyphen (-) between.
A range of characters is any two characters (including -)
with a hyphen (-) between them.
The forward slash character (/) is not a valid character to
include in a set.
A set of characters will not match / even if a range that
includes / is specified.
■[nd] matches only n or d.
■[m-x] matches any character between m and
x, inclusive.
■[--b] matches any character between - and b
inclusive (except for /; see /usr/pub/ascii
for order of punctuation characters).
■[abf-n] matches a, b, and any character
between f and n, inclusive.
■[a-f-n] matches any character between a and f
inclusive, -, or n. (The second - is interpreted
literally because the f preceding it is already
part of a range.)
Single
Character
Wildcard ?
The ? (question mark) matches any one character other
than /. This is not treated as a query string delimiter.
a?b matches aab and azb but not a/b.
Wildcard * The * (asterisk) wildcard matches any sequence of zero or
more characters. However, the * (asterisk) does not match
the forward slash character (/).
a*b matches ab, azb, and azzzzzzb but not a/b.
* The * (asterisk) can be used only at the lowest, terminating
level of the path. It matches zero or more characters.
Every character in a URL pattern must match the
corresponding character in the URL path exactly.
Exceptions:
■At the end of a pattern, /* matches any sequence of
characters from that point forward.
■The pattern *.extension matches any file name ending
with the named extension.
■Does not match /.
The following URL pattern:
/.../update.html
Matches:
/humanresources/benefits/update.html
/corporate/news/update.html
update.html
See Also: Table 25–4
/.../ Hierarchy
/.../* Host
wide
Matches any sequence of one or more characters that starts
and ends with the forward slash character (/).
Evaluation descends from the root /. At each directory
level, resources matching the highest precedence level are
selected as candidates for continued evaluation and then
descend to the next level. This continues until resources
representing the best match possible, based solely on the
path information, is obtained.
Host wide; the entirety of the pattern.
■The pattern /.../index.html matches:
/index.html
/oracle/index.html
/oracle/sales/index.html
index.html
It does not match xyzindex.html or
xyz/index.html.
■/oracle/.../*.html matches:
/oracle/index.html
/oracle/sales/order.html, and so on.
\ The backslash character is used to escape special
characters. Any character preceded by a backslash matches
itself.
■Escaped special characters need to be ignored if
putting the pattern in wildcard buckets
■Escaped special characters are matched literally to the
special characters, if any, within the incoming URL
■abc\*d only matches abc*d
■abc\\d only matches abc\d
Table 25–3 (Cont.) Supported Wildcards in Resource URL Patterns (Precedence Order)
Pattern Description Example
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-21
25.5.1.4 About Query String Name and Value Parameters for Resource Definitions
The Policy Model supports Query String Name and Value parameters in a Resource
pattern definition:
■Name: A string literal that can contain any characters, including symbols; all
characters are treated as literal.
■Value: Can be a string literal with any characters and can contain a wildcard (*
only) to match a sequence of 0 or more characters. Asterisk (*) is treated as a
wildcard.
■Amount: There is no limit to the number of name and value pairs in a query
string. However, for a single resource there will be only a few pairs.
■Order: Any order can be used for name and value pairs because at run time these
might come in any order as part of the query string.
Resource Matching and Precedence: Query String Name and Value Parameters
Access Manager uses an algorithm that locates the least specific match and continues
to the most specific possible resource. When you have candidates defined with both a
single-query string and query parameters, those with the single string take
precedence.
For resources containing parameter lists, the best match is determined as follows:
1. Path Matching: Access Manager attempts to match the path of the requested
resource. There may be multiple candidates matched, differing by query
component and/or operations declared.
2. Query String Matching: For matches obtained, Access Manager attempts to match
the query string (if present in the requested URL). If candidates are defined with
both single query string and query parameters, those with the literal string take
precedence. There may be multiple candidates remaining, differing by operation.
3. Operation Matching: For matches obtained, attempt to match the requested
operation. If there is no exact match present, then check for resources for which no
specific operation(s) have been defined. In other words, they apply to any
operation defined as part of the resource's type. In either case, this yields a single,
best match.
Path Matching: Defined resources are evaluated for potential match, against the
requested URL's path component, in the following precedence order:
■Literals (as in, the resource's pattern contains no special characters)
Table 25–4 Sample Resource URLs
Resource URL
/bank/accounts/*
/bank/accounts/*.jsp
/bank/accounts/checking
/bank/.../checking.jsp
/.../*.jsp
/bank/accounts/checking*.jsp
/bank/accounts/c*.jsp
/bank/.../accounts/def.gif
Adding and Managing Policy Resource Definitions
25-22 Administrator's Guide for Oracle Access Management
■Choice: {pattern1,pattern2,...} , each of which may itself contain the below special
characters and is evaluated, in turn, using this same precedence order
■Range: [ ]
■Single-char wildcard: ?
■Wildcard: *
■Hierarchy: /.../
■Hostwide: /…/* is the entirety of the pattern
Evaluation descends from the root '/'. At each directory level, resource(s) matching
with the highest precedence level are selected as candidates for continued evaluation
and then descent to the next level occurs. This continues until resource(s) representing
the best match possible, based solely on the path information, is obtained.
Table 25–5 illustrates the matching pattern for each of several requested URLs.
Query String Matching
When you have candidates defined with both single query string and query
parameters, those with the single string take precedence. Single query strings are
scored using the algorithm already-mentioned.
For resources containing parameter lists, the best match is determined as follows:
■Resources with parameter values without wildcards are given higher order of
precedence; the combined length of the parameter names and values is used to
determine the best match among the set of such resources.
■As for query string literals, if there are two or more matches with the same
combined length, then matching will fail.
■Resources with parameter values containing wildcards are considered next. The
total number of wildcards within each resource is used to determine the best
match among such resources. If there are two or more matches having same
number of wildcards, then the combined length of the parameter names and
values determines the best match
■Matching fails if multiple resources contain the same combined length.
Query String Matching Patterns: Second and subsequent patterns use parameter lists:
/oam/index.html::a=*d (a single query string)
/oam/index.html::a:b
/oam/index.html::a:b,c:d
/oam/index.html::a:b*
Note: All matching in 11g has been, and remains, case insensitive.
Table 25–5 Pattern Matching for Requested URLs
Requested URL Matching Pattern
/oam/sales/oam/page8.html /oam/.../*.html
/oam/Dept1/page8.html /oam/Dept?/page8.html
/oam/DeptQ/page8.html /oam/Dept[A-Z]/page[1-8].html
/oam/DeptQ/page8.html /oam/Dept[A-Z]/page?.html
/oam/saals/foo/aba/zzz/indexp.html /oam/sa{*,le,l?,a[k-m],[a-f-m]}s/.../{*b,?a}{a,/../ii}/.../{ind
ex,test}[pa].?tml
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-23
/oam/index.html::a:b*,c:d
/oam/index.html::a:b*,c:d*
/oam/index.html::a:b*,c:*d*
Table 25–6 illustrates the matching pattern for each of several requested URLs.
Operation Matching Examples: At this point in request processing, there are one or
more candidate resources, all of which match the requested URL path and query string
components equally. Access Manager now matches the requested operation to one of
those candidates: a resource defined to protect that operation specifically (as well as
other, specific operations). As only a single resource can be defined to protect any
given operation, this will give the single best match.
Run Time Evaluation: Name value pairs are evaluated at run time as follows:
NAME VALUE
a ab
a a*
Same Resource URL Specified Differently: Resources with the same URL and with
the same characters in the query string (although specified differently in the console
(one as a key and value and the other as a single string)) are considered different and
are allowed. For example, the two following resource patterns are considered as
different:
Resource URL:
/test.html
Query string:
area=*&dept=*
Resource URL:
/test.html
Query NAME VALUE
area *
dept *
Resource Matching During Policy Evaluation: The order in which name and value
pairs arrive at run time does not matter. As long as all the names and values match the
query string, the match is successful. The incoming request can have more name and
value parameters than defined and still have a successful match.
Example 1: The following pattern matches the incoming URL if no other pattern is
defined with the same URL, query string variables, and the extra query string variable
(revenue=1000):
Incoming URL =>
/test.html?area=emea&dept=engg&revenue=1000
resource pattern =>
/test.html
Query String NAME VALUE
area emea
dept engg
Table 25–6 Query String Matching: Examples
Requested URL Matching URL Pattern Matching Query String Pattern
/oam/index.html?a=b&c=d /oam/index.html a=*d
/oam/index.html?a=b1&c=d /oam/index.html a:b*,c:d
/oam/index.html?a=b1,c=d1 /oam/index.html a:b*,c:d*
/oam/index.html?a=b1,c=1d1 /oam/index.html a:b*,c:*d*
Adding and Managing Policy Resource Definitions
25-24 Administrator's Guide for Oracle Access Management
Example 1: For a resource with the same resource URL and the same query string,
with one defined as a single string and the other defined as name and value pairs, the
policy evaluation preference matches the literal query string before considering name
and value pairs. For instance, in the following example, a) is matched:
Runtime Request: URL =>
/test.html?area=emea&dept=engg
Resource Patterns:
a)
Resource:
/test.html
Query string:
area=emea&dept=engg
b)
Resource:
/test.html
Query String NAME VALUE
area emea
dept engg
Best Match, Multiple Resources: When you have multiple resources with query string
name and value pairs defined, the best resource match is the pattern that matches the
most number of query string parameters. When wildcard values are used, this is
followed by how closely each parameter value matches.
For example: With the following two query string patterns defined:
Query String NAME VALUE
area e*
dept e*
and
area em*
dept en*
Run Time Query String Parameters:
area emea
dept engg
Result: The second name and value pattern match order is higher.
Figure 25–11 shows the resource definition page. Here, "rev*" is a valid name (the
asterisk character is allowed and treated as a literal character, which is equivalent to
10g behavior). The Oracle Access Management Console enables you to add query
strings as name and value pairs. You can also add the query string as a literal string. If
If you select a literal query string, then the name and value option is disabled (and vice
versa).
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-25
Figure 25–11 HTTP Resources, Query String Resource URL Controls
Behavior When Migrating to Access Manager: If you upgrade to Access Manager
(from 10g), previous query strings are created in 11g appropriately (whether a single
string or a name and value pair). The appropriate type of query string is created in
Access Manager.
25.5.1.5 About Literal Query Strings in Resource Definitions
The Policy Model supports resource protection based on matching literal, full
query-string-based HTTP resource definitions within Access Policies.
A single Query String Pattern that would be matched against the entire input Query
string (as opposed to matching only portions (selected name and value pairs) of the
query string. For example:
status=active&adminrole=*
A Query String pattern specified as a regular free form string with these extra features:
■Optional: Special character (*) that matches zero or more characters, which is
applied to a set of names in the run time Query String.
■Two resource definitions can exist with same URL base path pattern and different
Query String patterns. These two are independent and non-equal resources. For
example, these are all valid and can exist at same time:
/foo
/foo?bar=true
/foo?bar=false
The Query String is free form with no restriction in terms of format or characters. It is
not required to specify Query String as key/value pairs
At run time, only the Query String that is part of HTTP GET requests is processed;
Query String pattern does not apply to HTTP POST data.
Resource Matching at run time:
■The base URL path is matched and then the Query String is matched
■Multiple resource patterns that contain matching Query Strings: The best match is
determined based on the number of tokens (pattern delimited by '*') and the
length of the token at each position. Patterns with longer tokens in the beginning
are preferred and then the pattern that contains more number of tokens. (If there
are matching patterns that contain same number of tokens and same length at each
position then the match would fail.)
Conflicts:
Adding and Managing Policy Resource Definitions
25-26 Administrator's Guide for Oracle Access Management
■Super Set: The input resource definition contains a set of name-value Query String
patterns that are a super set of patterns of an existing resource definition in the
policy store.
■Overlap: The input resource specification contains a set of name-value Query
string patterns that overlap a set of patterns of an existing resource definition in
the policy store.
Remote Registration: For OAM Agents, the remote registration tool (oamreg) accepts
Query-string based HTTP resource definitions and generates the relevant policy
objects for securing access of these resources. If any conflicts are encountered during
policy provisioning, only policies for resources that do not have any conflicts are
provisioned. This feature does not apply to 10g OSSO agent-based partners and
applications. OSSO agents are not capable of enforcing authentication scheme per
resource. Instead, a single authentication scheme is applied to all resources of an
application.
25.5.1.6 About Run Time Resource Evaluation
While processing requests for resources, an evaluation is made to ensure that the
proper policy is invoked for the resource.
Process overview: Resource evaluation
1. A user specifies the URL for a requested resource.
2. Access Manager creates a fully qualified URL that includes the URL pattern, based
on the host identifier and URL.
3. Access Manager compares the incoming URL for the requested resource to the
fully-qualified URL constructed from Application Domain information and the
policy's URL pattern:
■If there is a match, the various policies are evaluated to determine whether the
requester should be allowed or denied access to the resource.
■If the requester is allowed access, the resource is served.
Table 25–7 describes the possible outcomes.
See Also: Other processing details in the following topics:
■"About the Resource URL, Prefixes, and Patterns" on page 25-18
■"About Query String Name and Value Parameters for Resource
Definitions" on page 25-21
■"About Literal Query Strings in Resource Definitions" on
page 25-25
■"Managing Run Time Policy Evaluation Caches" on page 13-9
Table 25–7 Resource Evaluation Outcomes
Outcome Description
Best Match The best match is when a resource definition has the least resource scope compared
to other possible matches to the run time resource. The term resource scope
represents all possible resources that could be matched using a particular resource
definition
No Match1 If no match is found, the default evaluation outcome is FAILURE. Depending on
what kind of policy was being evaluated, this could mean no authentication is
attempted, or no resource access is granted.
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-27
Look Up Mechanism Examples
■The default resource URL in an Application Domain defines the broadest scope of
content possible (all directories and below):
/.../*
■The pattern /.../index.html matches:
/index.html
/oracle/index.html
/oracle/sales/index.html
It does not match, for example,
xyzindex.html
.
■/oracle/.../*.html matches:
/oracle/index.html
/oracle/sales/order.html
and so on
Resource Scope Examples
■Resource scope of the following resource definition (includes the asterisk):
/mybank/…/*
includes all URLs prefixed with "/mybank/"
■Resource scope of the following resource definition (no special characters in the
definition):
/mybank/account.html
includes only one URL: "/mybank/account.html"
25.5.2 Defining Resources in an Application Domain
Users with valid Administrator credentials can use the following procedure to add the
resource definitions to protect to the corresponding Application Domain.
Resource protection based on a list of discrete query parameters is more secure and
easier to administer than literal query strings. You might want to create a policy based
on resource URL with query parameters (string and name-value pairs).
Prerequisites
The Resource Type must be defined as a Shared Component. Several elements in the
Resource definition page are based on the defined and selected Resource Type. For
details, see "Managing Resource Types" on page 22-2.
To add resource definitions to an Application Domain
1. In the Oracle Access Management Console, locate and view the desired
Application Domain, as described in "Searching for an Existing Application
Domain" on page 25-12.
Note: An error can occur if you specify a host identifier value that is
invalid:
The challenge URL is invalid
.
See Also: "Defining Resources in an Application Domain" on
page 25-14
Adding and Managing Policy Resource Definitions
25-28 Administrator's Guide for Oracle Access Management
2. In the Application Domain, click the Resources tab, then click the New Resource
button in the upper-right corner of the Search page.
3. On the Resource Definition page:
a. Select or enter your details for a single resource (Table 25–1):
Type
Description
Host Identifier
Resource URL (Table 25–4)
Operations
Query String (Table 25–6)
Protection Level
Authentication Policy (if level is Protected)
Authorization Policy (if level is Protected and Authentication Policy is chosen)
b. Click Apply to add this resource to the Application Domain.
c. Repeat this procedure to add other resources to this Application Domain.
4. Proceed by adding defined resources to specific policies in the
Application domain as described in:
■Defining Authentication Policies for Specific Resources
■Defining Authorization Policies for Specific Resources
■Managing Token Issuance Policies, Conditions, and Rules
25.5.3 Searching for a Resource Definition
This section provides the following topics:
■About Searching for a Specific Resource Definition
■Searching for a Specific Resource Definition
25.5.3.1 About Searching for a Specific Resource Definition
Figure 25–12 shows the default Search elements and Search Results table for resource
definitions in an Application Domain.
Adding and Managing Policy Resource Definitions
Managing Policies to Protect Resources and Enable SSO 25-29
Figure 25–12 Resource Search within an Application Domain
You can simply click the Search button using the defaults or refine your search by
supplying as much or as little of the information in Table 25–8 as needed to find the
resource.
You can click Reset to clear the form or Search to initiate the search. Each resource
listed includes everything specified when it was added to the domain. The Actions
and View menus are available for use with the table. Also you can click the Create
command button to add a new resource definition to this domain.
25.5.3.2 Searching for a Specific Resource Definition
Users with valid Administrator credentials can use the following procedure to search
for a specific resource definition.
Table 25–8 Search Elements for a Resource in an Application Domain
Search Elements Description
Resource Type Provides a list of defined resource types from which you can choose. You can
also leave this blank.
Default: HTTP
Host Identifier Enter a host identifier here, if desired. You can leave this blank
Default: blank
Resource URL Enter a resource URL, if desired. You can leave this blank
Default: blank
Query String Enter a query string for the resource, or leave this blank. You can include this in
the search criteria if a query string was defined for the resource when it was
added to the Application Domain.
Default: blank
Authentication Policy Provides a list of defined authentication policies for this Application Domain.
You can choose one or leave the space blank.
Default: blank
Authorization Policy Provides a list of defined authorization policies for this Application Domain.
You can choose one or leave the space blank.
Default: blank
Adding and Managing Policy Resource Definitions
25-30 Administrator's Guide for Oracle Access Management
To find a resource definition
1. In the Oracle Access Management Console, locate and view the desired
Application Domain, as described in "Searching for an Existing Application
Domain" on page 25-12.
2. Click the Resources tab to display Resources Search controls.
3. Fill in your search criteria (Table 25–8), and click the Search button.
4. In the Search Results table, click the desired resource definition and take the
desired action:
■Actions Menu: Select an item to Create, Edit, or Delete the selected resource.
■View Menu: Select an item to alter the appearance of the results table.
■Edit Button: Click the button in the tool bar to display the configuration page.
■Delete: See "Viewing, Editing, or Deleting a Resource Definition".
■Detach: Click Detach in the tool bar to expand the table to a full page.
25.5.4 Viewing, Editing, or Deleting a Resource Definition
Users with valid Administrator credentials can use the following procedure to modify
resource definitions within a specific Application Domain.
If a resource protection level is modified from "Protected" to "Excluded" while it is
associated with a policy, the modification will fail. First, remove the resource from the
policy, make the change, and add the resource to the policy.
Prerequisites
You must have the desired resource type defined as a shared component. For details,
see "Managing Resource Types" on page 22-2.
To view, modify, or delete resource definitions
1. Find the Resource, as described in "Searching for a Resource Definition".
■View Only: Close the page when you finish.
■Modify: Alter the definition as desired and then click Apply to submit
changes (or close the page without applying changes).
■Delete:
–Open the resource definition and confirm this is the one to be deleted,
then close the page.
–Click the name of the desired resource definition and then click the Delete
button in the tool bar.
–In the Confirmation window, click Delete (or click Cancel to dismiss the
window).
If the Resource is associated with a policy, remove it from the policy first.
Note: During a Delete, you are alerted if the resource is associated
with a policy. Without a policy association, the resource is deleted.
See Also: "Defining Resources in an Application Domain" on
page 25-14
Defining Authentication Policies for Specific Resources
Managing Policies to Protect Resources and Enable SSO 25-31
–Repeat as needed to delete other resources in the Application Domain.
25.6 Defining Authentication Policies for Specific Resources
Each resource assigned to an Application Domain can be protected by only one
authentication policy. After adding a resource definition to the Application Domain,
the Administrator can begin refining a default authentication policy, adding a new
policy, and assigning resources to the authentication policy.
In an automatically generated Application Domain, the following authentication
policies are seeded as defaults to help streamline the Administrator's tasks:
■Protected Resource
■Public Resource
This section provides the following topics:
■About the Authentication Policy Page
■Creating an Authentication Policy for Specific Resources
■Searching for an Authentication Policy
■Viewing or Editing an Authentication Policy
■Deleting an Authentication Policy
25.6.1 About the Authentication Policy Page
Administrators use authentication policies to protect specific resources. The
authentication policy provides the sole authentication method for resources governed
by the policy.
Each authentication policy defines the type of verification that must be performed to
provide a sufficient level of trust for Access Manager to grant access to the user
making the request.
Authentication policies are local. A single policy can be defined to protect one or more
resources in the Application Domain. However, each resource can be protected by only
one authentication policy.
Authentication Policy Guidelines
1. Authentication policies include resources, success responses, and an
authentication scheme.
2. Authentication and Authorization policies can evaluate to Success or Failure.
3. Query Builder and support for LDAP filters (for retrieving matches based on an
attribute of a certain display type, for example).
4. Define a policy for resource: /…/* which can be used within a determined scope.
5. Token Issuance Policies can be defined using resources and user- or partner-based
conditions.
Figure 25–13 shows the Authentication Policies page of an Application Domain.
See Also: "Understanding Application Domain and Policy
Management" on page 25-4
Defining Authentication Policies for Specific Resources
25-32 Administrator's Guide for Oracle Access Management
Figure 25–13 Sample Authentication Policies Page in the Application Domain
Figure 25–14 shows a specific Authentication Policy. The resources assigned to this
policy are displayed on the Resources tab of the policy.
Figure 25–14 Sample Individual Authentication Policy Page
Table 25–9 describes authentication policy elements.
Table 25–9 Authentication Policy Elements and Descriptions
Element Description
Name A unique name used as an identifier.
Description Optional unique text that describes this authentication policy.
Authentication Scheme A single, previously-defined authentication scheme to be used by this policy for user authentication.
See Also: "Managing Authentication Schemes" on page 22-64 for details.
Success URL The redirect URL to be used upon successful authentication.
Defining Authentication Policies for Specific Resources
Managing Policies to Protect Resources and Enable SSO 25-33
25.6.1.1 About Resources in an Authentication Policy
You can choose to add one or more resources to be protected by the authentication
policy. The Resources tab on the Authentication Policy page provides a table where
you can enter resource URLs. A list is also provided from which you can choose from
defined resources within the Application Domain.
To add a resource, click the + button and select from the list. To delete a resource, select
the name from the Resources table and click the Delete button in the table.
25.6.2 Creating an Authentication Policy for Specific Resources
Users with valid Administrator credentials can use the following procedure to add an
authentication policy and resources to an Application Domain. You can use a
pre-configured authentication scheme or a custom authentication scheme in the
authentication policy.
Prerequisites
Any resource to be added to a policy must be defined within the same Application
Domain as the policy.
To add an authentication policy for specific resources
1. Locate the desired domain as described in "Searching for an Existing Application
Domain".
2. Click the Authentication Policies tab, then click the Create Authentication Policy
button to open a fresh page.
3. Required Elements: Add your information for this policy.
■Name
■Authentication Scheme
4. Optional Elements (Table 25–9): Add as needed for your policy.
■Description (optional)
■Success URL
■Failure URL
Failure URL The redirect URL to be used if authentication fails.
Resources The URL of a resource chosen from those listed. The listed URLs were added to this Application
Domain earlier. You can add one or more resources to protect with this authentication policy. The
resource definition must exist within the Application Domain before you can include it in a policy.
See Also: "About Resources in an Authentication Policy" on page 25-33.
Responses The obligations (post authentication actions) to be carried out by the Web agent. After a successful
authentication, the application server hosting the protected application should be able to assert the
User Identity based on these responses.After a failed authentication, the browser redirects the
request to a pre-configured URL
See Also: "Introduction to Policy Responses for SSO" on page 25-68.
See Also:
■"About the Authentication Policy Page" on page 25-31
■"Managing Authentication Schemes" on page 22-64
Table 25–9 (Cont.) Authentication Policy Elements and Descriptions
Element Description
Defining Authentication Policies for Specific Resources
25-34 Administrator's Guide for Oracle Access Management
5. Add Resources: A Resource must be defined within the Application Domain
before you can add the resource to a specific policy.
■Click the Resources tab on the Authentication Policy page.
■Click the Add button on the Resources tab.
■Click the Search button.
■Click a URL in the Results table, then click Add Selected.
■Repeat these steps as needed to add more resources.
6. Click Apply to save changes and close the Confirmation window.
7. Responses: Add policy Responses as described in "Adding and Managing Policy
Responses for SSO" on page 25-75.
8. Close the page when you finish.
25.6.3 Searching for an Authentication Policy
Users with valid Administrator credentials can use the following procedure to search
for a specific authentication policy.
To search for an authentication policy in an Application Domain
1. Locate the desired domain as described in "Searching for an Existing Application
Domain".
2. Click the Authorization Policies tab and:
■Edit: See "Viewing or Editing an Authentication Policy".
■Delete: "Deleting an Authentication Policy".
■Detach Table: Click Detach in the tool bar to expand the table to a full page.
■View Menu: Select a menu item to alter the appearance of the results table.
25.6.4 Viewing or Editing an Authentication Policy
Users with valid Administrator credentials can use the following procedure to modify
an authentication policy in an Application Domain. This includes changing the
authentication scheme, adding or removing resources or responses, and altering the
Success or Failure URLs.
To view or modify an authentication policy
1. Locate the desired policy as described in "Searching for an Authentication Policy".
2. Click the desired policy name to display its configuration.
3. Edit Policy Elements (Table 25–9):
4. Resource: Click the Resources tab and:
■Add: Click the Add button on the Resources table, click a URL in the list, click
Apply.
Tip: See Configuring Success and Failure URLs for Authorization
Policies.
See Also: "About the Authentication Policy Page" on page 25-31
Defining Authorization Policies for Specific Resources
Managing Policies to Protect Resources and Enable SSO 25-35
■Delete: Click a URL in the Resources table, click the Delete button on the table.
5. Click Apply to submit changes and close the Confirmation window (or close the
page without applying changes)
6. Responses: View or edit responses as described in "Adding and Managing Policy
Responses for SSO" on page 25-75.
7. Close the page when you finish.
25.6.5 Deleting an Authentication Policy
Users with valid Administrator credentials can use the following procedure to delete
an authentication policy from an Application Domain.
When you remove the policy, all resource definitions remain within the Application
Domain. However, the policy and all responses are eliminated.
The following procedure describes how to delete the entire policy. To simply alter an
element in the policy, see "Viewing or Editing an Authentication Policy".
To delete an authentication policy
1. Locate the desired policy as described in "Searching for an Authentication Policy".
2. Click the desired policy name to display and confirm this configuration.
3. Ensure that resources governed by this policy are added to a different policy.
4. Delete all responses, as described in "Adding and Managing Policy Responses for
SSO" on page 25-75.
5. On the Authentication Policies tab, click the Serial Number beside the policy, then
click the Delete button in the tool bar.
6. In the Confirmation window, click Delete to confirm (or click Cancel to dismiss
the window).
25.7 Defining Authorization Policies for Specific Resources
Each resource assigned to an Application Domain can be protected by only one
authorization policy.
In an automatically generated Application Domain, the following authorization
policies are seeded as defaults:
■Protected Resource
■Public Resource
After adding resource definitions to the Application Domain, Administrators can
begin refining a default authorization policy, adding a new policy, and adding
resources to authorization policies. This section provides the following topics:
Note: During a Delete operation, you are alerted to confirm removal
of the policy. Confirmation is required to complete the operation.
See Also: "About the Authentication Policy Page" on page 25-31
See Also: "Understanding Application Domain and Policy
Management" on page 25-4
Defining Authorization Policies for Specific Resources
25-36 Administrator's Guide for Oracle Access Management
■About Authorization Policies for Specific Resources
■Creating an Authorization Policy and Specific Resources
■Searching for an Authorization Policy
■Viewing or Editing an Authorization Policy and Resources
■Deleting an Entire Authorization Policy
25.7.1 About Authorization Policies for Specific Resources
Administrators can create an authorization policy to protect access to one or more
resources based on attributes of an authenticated user or the environment. The
authorization policy provides the sole authorization protection for resources included
in the policy.
Authorization policies are local, which means that each policy applies only to the
resources specified for the policy. A policy cannot be derived or applied to any other
resource.
A single policy can be defined to protect one or more resources in the Application
Domain. However, each resource can be protected by only one authorization policy.
Figure 25–15 shows the Authorization Policy page within an Application Domain. The
resources assigned to this policy are displayed on the Resources tab of the policy.
Figure 25–15 Sample Individual Authorization Policy Page
Table 25–10 describes authorization policy elements. The elements are the same
regardless of the domain; only the details will differ.
Table 25–10 Authorization Policy Elements and Descriptions
Element Description
Name A unique name used as an identifier in the navigation tree.
Description Optional unique text that describes this authorization policy.
Success URL The redirect URL to be used upon successful authorization.
Failure URL The redirect URL to be used if authorization fails.
Summary General information (usually Name and optional Description).
Resources One or more previously-defined resource URLs to be protected by this
authorization policy.
Conditions See Also "Introduction to Authorization Policy Rules and Conditions" on
page 25-40.
Defining Authorization Policies for Specific Resources
Managing Policies to Protect Resources and Enable SSO 25-37
25.7.2 Creating an Authorization Policy and Specific Resources
Users with valid Administrator credentials can use the following procedure to add an
authorization policy to an Application Domain.
Prerequisites
Any resource to be added to a policy must be defined within the same Application
Domain as the policy.
To create an authorization policy and resources
1. Locate the desired domain as described in "Searching for an Existing Application
Domain".
2. Click the Authorization Policies tab, then click the Create button to open a fresh
page.
3. Summary Tab: Add your information to the Summary tab (Table 25–10).
4. Add Resources: The Resource must be defined in the Application Domain before
you can add the resource to a specific policy.
■Click the Resources tab on the Authorization Policy page.
■Click the Add button on the Resources tab.
■Click the Search button.
■Click a URL in the Results table, then click Add Selected.
■Repeat these steps to add more resources.
5. Click Apply to save changes and close the Confirmation window.
6. Responses: Add policy Responses as described in "Adding and Managing Policy
Responses for SSO" on page 25-75.
7. Conditions: Add authorization conditions, as described in "Defining
Authorization Policy Conditions" on page 25-43.
8. Rules: Add authorization rules, as described in "Defining Authorization Policy
Rules" on page 25-43.
9. Close the page when you finish.
25.7.3 Searching for an Authorization Policy
Users with valid Administrator credentials can use the following procedure to locate a
specific authorization policy.
Rules See Also "Introduction to Authorization Policy Rules and Conditions" on
page 25-40.
Responses See Also "Introduction to Policy Responses for SSO" on page 25-68.
See Also: "About Authorization Policies for Specific Resources" on
page 25-36
Table 25–10 (Cont.) Authorization Policy Elements and Descriptions
Element Description
Defining Authorization Policies for Specific Resources
25-38 Administrator's Guide for Oracle Access Management
To search for an authorization policy
1. Locate the desired domain as described in "Searching for an Existing Application
Domain".
2. Click the Authorization Policies tab and:
■Edit: See "Viewing or Editing an Authorization Policy and Resources".
■Delete: "Deleting an Entire Authorization Policy".
■Detach Table: Click Detach in the tool bar to expand the table to a full page.
■View Menu: Select a menu item to alter the appearance of the results table.
25.7.4 Viewing or Editing an Authorization Policy and Resources
Users with valid Administrator credentials can use the following procedure to view or
modify an authorization policy within an Application Domain.
To view or edit an authorization policy
1. Locate the desired domain as described in "Searching for an Authorization Policy".
2. Summary: Edit as needed (Table 25–10):
3. Resource: Click the Resources tab and add or delete resources as needed:
■Add: Click the Add button on the Resources table, click a URL in the list, click
Apply.
■Delete: Click a URL in the Resources table, click the Delete button on the table
then confirm.
4. Click Apply to submit changes and close the Confirmation window (or close the
page without applying changes).
5. Conditions: See "Viewing, Editing, or Deleting Authorization Policy Conditions"
on page 25-59.
6. Rules: See "Defining Authorization Policy Rules" on page 25-43.
7. Responses: See "Viewing, Editing, or Deleting a Policy Response for SSO" on
page 25-76.
8. Close the page when you finish.
25.7.5 Deleting an Entire Authorization Policy
Users with valid Administrator credentials can use the following procedure to delete
an authorization policy or simply delete resources within the policy.
When you remove the entire policy, all resource definitions remain within the
Application Domain. However, the authorization policy and the conditions and rules
governing access are eliminated.
See Also: "About Authorization Policies for Specific Resources" on
page 25-36
Note: During a Delete operation, you are alerted to confirm removal
of the policy. Confirmation is required to complete the operation.
Configuring Success and Failure URLs for Authorization Policies
Managing Policies to Protect Resources and Enable SSO 25-39
To simply alter an element in the policy see "Viewing or Editing an Authentication
Policy".
Prerequisites
Assign resources governed by this policy to another authorization policy, either before
or after deleting the policy.
To delete an authorization policy
1. Locate the desired domain as described in "Searching for an Authorization Policy".
2. Optional: Double-click the policy name to review its content, and then close the
page when finished.
3. Delete: Click the policy name, and then click the Delete button in the tool bar.
4. In the Confirmation window, click Delete (or click Cancel to dismiss the window).
5. Confirm that the policy is no longer listed in the navigation tree.
25.8 Configuring Success and Failure URLs for Authorization Policies
When an Authorization Success or Failure redirect URL is set, the target URL for
which the end user is seeking access should be passed along as a parameter. The
following information has relevance when configuring an Authorization policy
Success or Failure URL.
■The original resource location will be URL encoded and added as a value to the
oam_res query parameter before redirecting to the success or failure URL. The
following rules are relevant to building the oam_res value; during an
authorization call, only the HostIdentifier is passed so building the URL with a
fully qualified host and port is slightly more involved. Here are two examples.
Using the HostIdentifier, we find the first fully qualified host:port entry and
construct the URL with it. The rest of the entries are then added as query
parameters to the resource URL. For example:
HostList = [Host hostName:="adc00oyf.us.example.com", port=7777",
Host hostName:="11gAgent", port=null",
Host hostName:="adc00oyf.us.example.com", port=80"] ,
HostIdentifier = 11gAgent
The resource URL built will be:
HTTP://adc00oyf.us.example.com:7777/index.html?Host1=adc00oyf.us.example.com:80
In this second example:
HostList =[Host hostName:="adc00oyf.us.example.com", port=7777",
Host hostName:="11gAgent", port=null] ,
HostIdentifier = 11gAgent
The resource URL built will be:
HTTP://adc00oyf.us.example.com:7777/index.html
■To send a Hashed value of the resource URL for security reasons, run the
displayAuthZCallBackKey()
WLST command. This will return a Base64 encoded
See Also: "About Authorization Policies for Specific Resources" on
page 25-36
Introduction to Authorization Policy Rules and Conditions
25-40 Administrator's Guide for Oracle Access Management
string value of the AES 128 key which is generated. This key can be used by the
OAM server and the receiving app. It is stored in the oam-config.xml. The entry in
oam-config.xml is found under
/DeployedComponent/Server/NGAMServer/Profile
.
<Setting Name="AuthZCallBack" Type="htf:map">
<Setting Name="AuthZHashKey"
Type="xsd:string">1E8461DFA32AD746AF28BAAAA9F327327941C14CAC216DCFA9AC17985E09
7A0DD603EC1DF5C6D9F5C904ED44952A5D5F</Setting>
<Setting Name="AuthZCallBackEnabled" Type="xsd:boolean">true</Setting>
</Setting>
■If WLST in step 2 is enabled, we also send a hashed value of the original resource
URL as a value of the oam_res_hash query parameter. For example:
http://adc00oyf.us.example.com:7001/SampleLoginWAR/pages/MFALogin.jsp?
oam_res=HTTP%3A%2F%2Fadc00oyf.us.example.com%3A0%2Findex.html%3FHost1
%3D11gAgent%3Anull&oam_res_hash=45438D536865B256681D328AA1BFD47D5D4D0039
25.9 Introduction to Authorization Policy Rules and Conditions
In Access Manager 11g, each Authorization policy includes a rule that defines whether
the policy allows or denies access to resources protected by the policy. The rule
references conditions that define the user or population to be granted or denied access
and other considerations for authorization. Authorization rules and conditions apply
to all resources within a specific authorization policy.
Evaluation of conditions and rules determines if the authorization policy applies to the
incoming request. The appropriate obligations take affect after successful
authentication and work in concert with defined authorization rules, conditions, and
responses. For each incoming request, the authorization policy determines if there are
any conditions that apply. If so, these conditions are evaluated.
This section provides the following topics:
■About Allow or Deny Rules
■About Authorization Policy Conditions
■About Classifying Users and Groups for Conditions
■Guidelines for Authorization Responses Based on Conditions
25.9.1 About Allow or Deny Rules
In an authorization policy, a Rule contains all (or a subset) of conditions defined for the
policy. The effect of the Rule determines the effect of the policy.
You can set one or more rule effects (outcomes) per policy. However, you can specify
only one Rule per outcome. The following outcomes can be applied to authorization
and token issuance policies:
Note: The Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference for Identity and Access Management provides details on the
displayAuthZCallBackKey()
WLST command.
Introduction to Authorization Policy Rules and Conditions
Managing Policies to Protect Resources and Enable SSO 25-41
■Allow authorized users access to a protected resource. If Allow conditions do not
apply to a user, the user is not qualified by the policy and, by default, the user is
denied access to the requested resource.
■Deny authorized users access to a protected resource.
You can develop simple rules that rely on a single condition, or use expressions to
define more complex rules based on multiple conditions. For more information, see
"About Expressions and Expression-Based Policy Evaluation" on page 25-63.
25.9.2 About Authorization Policy Conditions
A condition is an element that specifies one or more criteria to be satisfied by the
access request. In structure, conditions are similar to constraints (in 11.1.1.3 and
11.1.1.5). However, earlier constraints included Allow and Deny rules that are now
specified independently on the Rules tab.
Each authorization policy can contain one or more conditions. Using different
condition types, you can:
■Identify the users or groups of users who are either allowed or denied access
(based on the rule) to protected resources.
■Stipulate the range of IP addresses who are either allowed or denied access to
protected resources.
■Set a time period defining when the condition applies.
■Specify attributes that enforces evaluation of request context, user session state,
and user attributes
The Conditions tab provides a table of defined conditions, organized by name, and a
table of details for the selected condition, as shown in Figure 25–16.
Note: If the user's IP address falls outside the range of denied
addresses, this by itself is not enough for authorization to be
successful. For authorization to be successful, the user must
specifically be granted access based on an Allow rule.
Introduction to Authorization Policy Rules and Conditions
25-42 Administrator's Guide for Oracle Access Management
Figure 25–16 Individual Authorization Policy Conditions Tab
Table 25–11 describes elements and controls on the Conditions tab.
25.9.3 About Classifying Users and Groups for Conditions
Oracle recommends that you consider the same information for the policies and
conditions when analyzing users and groups to determine who is explicitly allowed or
denied access. For example, one authorization policy might be constrained to a
particular time of day (Temporal Type) while another might be constrained to a
specific group of users (Identity Type).
Table 25–11 Authorization Policy Condition Tab
Element Description
Conditions Table Elements Lists all conditions defined for this policy.
Name A unique name used as an identifier for the condition.
Type The kind of condition you want to use. Only one Type can be
specified:
■Identity
■IP4 Range
■Temporal
■Attribute
■True (see Table 21–5)
Description Optional unique text that describes this condition.
Condition Details Section Depending on the Type of the selected condition, the information in
this table will differ. For details, see:
■"About Identity Conditions" on page 25-46
■"About IP4 Range Condition Types" on page 25-52
■"About Temporal Conditions" on page 25-54
■"About Attribute Conditions" on page 25-56
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-43
When classifying users Oracle recommends that you divide the users, and groups of
users, into groups for whom different conditions apply. For example, conditions can
determine when the users can access the resources, the computers from which they
must make their requests, and so on.
If some users fall into multiple categories, for example, a user in the marketing group
belongs to a certain project group, or a user in the human resources group also belongs
to the project group, put the user in both categories. You can require that the user meet
the conditions of two conditions.
To create policies for subsets of resources in an Application Domain and protect them
with different authorization rules and conditions, consider the same information: who
can access the resources protected by this policy and under what conditions you want
explicitly to allow or deny access to the resources.
25.9.4 Guidelines for Authorization Responses Based on Conditions
For each condition type, consider the response actions that you want to occur for
authorized users. For example, you might want the system to return user profile
information and pass that information to a downstream application. For example:
■If the user is authorized, you might want to pass the user's common name (cn) to
another application so that the application can present a customized greeting to
the user.
■If the user is not authorized, you might also want to return information about the
user for security purposes.
25.10 Defining Authorization Policy Conditions
You use conditions in an authorization policy to:
■Identify the users by user name, role, or an LDAP filter whose criteria the user
must satisfy.
■Stipulate the computers where users can access resources.
■Set a time period when the rule applies.
■Specify attributes that enforces evaluation of request context, user session state,
and user attributes
The mechanism to add a condition is the same regardless of the type you choose. A
dialog box pops up where you define the name and type to create the condition
container. Afterward you are presented with controls to define the specifics of the
condition.
This section is divided as follows:
■Choosing a Condition Type
■Defining Identity Conditions
■Defining IP4 Range Conditions
■Defining Temporal Conditions
Note: Do not be concerned about users who are denied access under
any conditions. Users are denied access by default if none of the
conditions qualify them for access.
Defining Authorization Policy Conditions
25-44 Administrator's Guide for Oracle Access Management
■Defining Attribute Conditions
■Viewing, Editing, or Deleting Authorization Policy Conditions
25.10.1 Choosing a Condition Type
This section provides the following topics:
■About Choosing a Condition Type
■Choosing a Condition Type
25.10.1.1 About Choosing a Condition Type
You can have more than one instance of a given type of condition within a policy.
When an Administrator adds a condition to an authorization policy, a window
(Figure 25–17) appears where you enter capture the Name, Type, and optional
Description. When submitted, this information is used to create a container for
condition details that must be also specified.
Figure 25–17 Add Condition Window
Table 25–12 describes the Add Condition elements.
After the container is added it is displayed on the Condition tab as shown in
Figure 25–18. The Name, Type, and Description are displayed in the Results table at
the top of the tab. The lower panel contains the details of the condition
Table 25–12 Add Condition Window Elements
Element Description
Name A unique name for this condition.
Type Only one Type can be specified:
■Identity (See "About Identity Conditions" on page 25-46)
■IP4 Range (See "About IP4 Range Condition Types" on page 25-52)
■Temporal (See "About Temporal Conditions" on page 25-54)
■Attribute (See "About Attribute Conditions" on page 25-56)
Description Optional.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-45
Figure 25–18 Condition Containers on the Authorization Policy Page
25.10.1.2 Choosing a Condition Type
Users with valid Administrator credentials can use the following procedure to choose
a condition class for the authorization policy.
Prerequisites
The Application Domain must exist.
To choose a condition class
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the policy name to open its configuration.
3. On the individual policy page, click the Conditions tab.
4. Click the Add (+) button and (Table 25–12):
■Name: Enter a unique name.
■Type list, choose the kind of condition (Identity, for example).
■Click the Add Selected button.
5. Proceed to one of the following topics to complete your definition:
■Defining Identity Conditions
■Defining IP4 Range Conditions
■Defining Temporal Conditions
■Defining Attribute Conditions
25.10.2 Defining Identity Conditions
This section provides all information about Identity Conditions in the following topics:
■About Identity Conditions
■Specifying Identity Type Conditions
See Also: "Defining Authorization Policy Conditions" for
information and procedures
Note: You can have more than one instance of a given class of
condition in a policy.
See Also: "About Choosing a Condition Type" on page 25-44
Defining Authorization Policy Conditions
25-46 Administrator's Guide for Oracle Access Management
25.10.2.1 About Identity Conditions
When defining an Identity Condition, you must add one or more members of a user
population from one or more User Identity Stores. You can add the user population as
a list of users or groups. Alternatively, you can add LDAP search filters to be used at
runtime to identify the user population. LDAP search filters provide a simple way to
specify a target identity population without having to reorganize or create new groups
in the identity store (directory server). For details see:
■About Identity Conditions and User Populations
■About LDAP Search Filter Support in Identity Conditions
■About LDAP Search Filter Syntax
25.10.2.1.1 About Identity Conditions and User Populations After opening the condition
container, any defined user population is displayed. As with the other condition types,
the Identity type can be used in conjunction with identity and temporal conditions.
When adding an identity condition, you open the popup menu beside the Add (+)
button (labeled 1 in Figure 25–19), choose to Add Users and Groups or Add Search
Filter (2). Figure 25–19 shows the popup menu and the Add Identities window that
appears (3). After locating the desired identities, select the desired Identities and click
Add Selected (4).
Figure 25–19 Add Identities Window
Table 25–13 describes the Add Identities elements.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-47
After selecting one or more identities and clicking the Add Selected button, your
Conditions tab might look something like Figure 25–20.
Figure 25–20 Identity Condition and Details
To save these details as a condition, click the Save button in the upper-right corner of
the tab.
25.10.2.1.2 About LDAP Search Filter Support in Identity Conditions Access Manager 11g
authorization conditions accept a list of users, groups, and LDAP search filters as part
of allowed or denied identities. An LDAP filter is a text string that expresses specific
criteria for the search operation. LDAP search filters provide a simple way to specify a
target population without reorganizing or creating new groups in the identity store
(directory server).
Access Manager 11g accepts LDAP search filter data for the following conditions and
resource types:
■Identity Conditions
■Token Requestor Identity Conditions
■All resource types (HTTP, TokenServiceRP, and other custom resource types)
When a user tries to access a resource protected by a condition containing an LDAP
search filter, Access Manager performs a directory lookup (LDAP search) on the
identity domain (identity store) specified as a part of the filter. Search results are
cached to avoid repeated directory server lookups.
If you choose
Add Search Filter ...
, the controls shown in Figure 25–21 appear. You
can add more than one LDAP Search Filter in an authorization rule for evaluation at
runtime. The field where you enter your LDAP search filter is used to identify
allowed/denied users.
Table 25–13 Add identities Elements
Element Description
Store Name Select the desired LDAP store for this search from the list of registered LDAP stores.
Entity type Choose either Users, Groups, or All to define your search criteria.
Entity Name Enter information to further refine your search criteria.
Search Click this button when your search criteria are defined.
Results table Displays the results of your search.
Add Selected Click to add the selected users or groups from the results table to the Condition's
Details.
Defining Authorization Policy Conditions
25-48 Administrator's Guide for Oracle Access Management
Figure 25–21 Add Search Filter Controls
Table 25–14 describes elements associated with adding a Search Filter.
Table 25–14 Add Search Filter Elements
Element Description
Domain The Identity Domain (registered user identity store) in which
the search should be conducted during runtime. Each filter
must be associated with a specific user identity store. With
Access Manager 11g, a directory lookup (LDAP Search) is
performed only on the specified identity domain (identity
store).
Search Filter The field where you enter your LDAP search filter. For
example:
((|dept=sales)(dept=support))
See Also: "About LDAP Search Filter Syntax" on page 25-49
Test Filter This button enables you to test your LDAP Search Filter to
ensure it returns the expected result.
Test Results The results of your filter test are displayed with your own
designations for:
■Type: LDAPSearchFilter
■Identifier: Your LDAP Search Filter
Add Filter Click to Add the filter to this identity condition.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-49
Figure 25–22 shows the Identity Conditions: Details page, displayed after adding an
LDAP Search Filter.
Figure 25–22 Identity Conditions: Details
25.10.2.1.3 About LDAP Search Filter Syntax Only standard LDAP attributes can be used
when defining an LDAP search filter. Exact syntax depends on your identity store; see
your vendor documentation. Table 25–15 illustrates LDAP Search Filter examples for
Access Manager.
Cancel Click to dismiss the Add Search Filter dialog without adding a
filter.
See Also:
■"About LDAP Search Filter Syntax" on page 25-49
■"Defining Identity Conditions" on page 25-45
Table 25–15 LDAP Search Filter Examples for Access Manager
Filter Type and
Operators Description Syntax Example
Static LDAP Search
Filters
When you implement a static search filter, all search results
must match a fixed value. For example, you can restrict a
search to return only people whose directory profiles show
an organizational unit of Sales.
As an example of a simple static filter, suppose you want to
provide Selector searches for the seeAlso attribute. The filter
returns search results that show only people whose
directory profiles contain a businessCategory value of
dealership.
(attribute=value)
For example:
(businessCategory=dealership)
Static Searches Using
Wild Cards
As an example of a static filter that uses wild cards, suppose
you want only people with the word Manager in their title
to be returned on a search using the Selector. You can create
a filter that searches for the string Manager with the asterisk
(*) wildcard.
(attribute=*value*)
For example:
(title=*manager*)
Dynamic LDAP Search
Filters
A dynamic filter allows a search to return results that are
based on a user profile. A dynamic filter is a conventional
LDAP search filter with filter substitution syntax.
(attribute=$attribute$)
Table 25–14 (Cont.) Add Search Filter Elements
Element Description
Defining Authorization Policy Conditions
25-50 Administrator's Guide for Oracle Access Management
During migration to Access Manager 11g (from 10g), each LDAP Rule maps to
corresponding 11g identity domains (user identity stores) based on Oracle Access
Manager 10g directory profiles. Access Manager 11g identity domains (user identity
stores) must be associated with each LDAP search filter.
25.10.2.2 Specifying Identity Type Conditions
Users with valid Administrator credentials can use the following procedure to add
identity type conditions to an Application Domain.
Substitution syntax Substitution syntax is evaluated dynamically, according to
the person executing a task. For instance, you can enter
substitution syntax where the attribute value for the source
DN (the person logged into the application) is substituted
and evaluated against the target DN (the entry you are
trying to view).
Note: Setting a searchbase can present significant
administrative overhead. A filter-based approach
accomplished by substitution syntax can provide the same
functionality in a more scalable and simplified design.
Using substitution syntax, you can create a function that
starts searches higher in the directory structure, but filters
the search data by comparing an attribute of information
from the search initiator's record (for example, using the
substitution
$ou$
) to an attribute of data on each possible
result (for example,
ou=
). You can use substitution syntax
for attribute access control and searchbases. For example, by
placing a filter on the type attribute Login for
inetOrgPerson, the ability of a user to view any records
outside their scope is removed.
Note: For the selected searchbase, users can search only for
entries from the same
ou
as their own. This applies only to
the attribute on the person's record, not the ou of the branch
of the directory in which they reside. Additionally, users
from
ou=
people can search for entries within the selected
searchbase.
(attribute=$attribute$)
For example: The following filter finds
all those in the same organizational
unit as the person logged in to the
application:
(ou=$ou$)
Dynamic Searches Using
Wild Cards
Wildcards are supported in a dynamic filter.
For example, suppose you want to supply a contactPerson
attribute in an organizationalUnit object. The contactPerson
attribute should return people in same Zip code as the
organizationalUnit object. If the organizationalUnit profile
contains an attribute zipCode, and the Zip code is specified
at the end of a postalAddress directory attribute.
(attribute=*$attribute$)
For example:
(postalAddress=*$zipCode$)
Searches Using the Not
Operator: (!)
The Not operator is supported when constructing a filter.
The optimized algorithm causes the filter (!(sn=white)) to
not give the expected result.
((!(sn=white))(objectclass=personO
C))
See Also: "Specifying Identity Type Conditions" on page 25-50
See Also: Oracle Fusion Middleware Upgrade Guide for Oracle
Identity Management
Note: You must save each condition definition individually, before
adding or selecting another condition.
Table 25–15 (Cont.) LDAP Search Filter Examples for Access Manager
Filter Type and
Operators Description Syntax Example
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-51
Prerequisites
The Application Domain must exist.
To add identity conditions to an authorization policy
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the Conditions tab, click the Add (+) button.
3. Enter a Name, select Identity from the Type list (or Token Requestor Identity) and
click Add Selected.
4. Add Users/Groups:
■In the Condition Details section click the Add (+) button.
■Choose Add Users and Groups from the list.
■Store Name: Choose the desired name from the list of registered LDAP stores.
■Enter criteria (Identity Type and Identity Name) for the population you want
to find, and click the Search button.
■Select desired results.
■Click Add Selected.
■Repeat to add another User or Group condition.
5. Add Search Filter:
■In the Condition Details section click the Add (+) button.
■Domain Name: Choose the desired user identity store for this filter.
■Search Filter: Enter your search filter syntax (Table 25–14).
■Test: Click the Test Filter button and review the results table.
■Click the Add Selected button.
■Repeat to add another LDAP Search Filter condition.
6. Click Apply and then close the Confirmation window.
7. Close the page when you finish.
8. Verify the Conditions by logging in as different users and test access to the
resource.
25.10.3 Defining IP4 Range Conditions
This section provides the following information:
■About IP4 Range Condition Types
■Defining IP4 Range Conditions
See Also:
■"About Identity Conditions" on page 25-46
■"About LDAP Search Filter Support in Identity Conditions" on
page 25-47
Defining Authorization Policy Conditions
25-52 Administrator's Guide for Oracle Access Management
25.10.3.1 About IP4 Range Condition Types
With the IP4 Range condition type, Administrators can specify a list of IP address
ranges that will either be allowed or denied access. Like the other authorization
conditions, IP4 Range condition types can be used in conjunction with identity and
temporal conditions.
Explicit Addresses: Each IP address you specify must be an explicit, valid address
(format nnn.nnn.nnn.nnn): 192.2.2.2, for example.
IP4 Range: You define a range by entering
From
(start) and
To
(end-range) address
values. Each IP address you specify must be an explicit, valid address (format
nnn.nnn.nnn.nnn): 192.2.2.2, for example. The address specified in the
To
field should
be greater than the address specified in the
From
field. During authorization, Access
Manager checks to ensure that the client IP address falls between the
From
(start)) and
To
(end-range) addresses specified. If multiple overlapping ranges are specified, and
the client's IP address falls within even one of the ranges, the condition evaluates to
"
true
" and allows (or denies) access based on the condition that was set for the
condition.
If multiple overlapping ranges are specified, and the client's IP address falls within
any one of the ranges, the condition evaluates to "
true
" and allows (or denies) access
based on the condition.
Figure 25–23 illustrates the IP4 Range Conditions table with a sample starting and
ending IP4 Range. If you enter an invalid range, you are notified and unable to save it.
Note: Oracle Access Manager 10g accepts a wildcard as the last entry
(192.2.2.* or 192.2.*, for example). IP4 Ranges with no wildcards can be
easily ported to 11g by creating a Condition containing multiple IP4
Range values. However, 10g IP4 Ranges with wildcards are expanded
by upgrade tooling into multiple ranges relevant to the wildcard.
Note: If the
From
IP address is greater than the
To
address, the
condition cannot match any client IP address.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-53
Figure 25–23 IP4 Range Conditions
25.10.3.2 Defining IP4 Range Conditions
Users with valid Administrator credentials can use the following procedure to add IP4
Range type conditions to an Application Domain. You must save each condition
definition individually, before adding or selecting another condition.
Prerequisites
The Application Domain must exist.
To add IP4 Range type conditions to an authorization policy
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the Conditions tab, click the Add (+) button.
3. Enter a Name, select IP Range from the Type list, enter an optional Description,
and click Add Selected.
4. Add the desired IP address range (Table 25–23):
■In the Details panel, click the Add (+) button to display the Add IP Range
dialog.
■
From
: Enter the start of the range.
■
To
: Enter the end of the range.
■Click the Add button to include this range in the Condition Details section.
Note: If the user's IP address falls outside the range of denied
addresses, this by itself is not enough for authorization to be
successful. For authorization to be successful, the user must
specifically be granted access based on an Allow rule.
See Also: "About IP4 Range Condition Types" on page 25-52
Defining Authorization Policy Conditions
25-54 Administrator's Guide for Oracle Access Management
■Repeat these steps to add another range.
5. Click Apply and then close the Confirmation window.
6. Verify your IP4 Range Conditions by logging from different clients with different
IP addresses to test access to the protected resource.
25.10.4 Defining Temporal Conditions
This section provides the following topics:
■About Temporal Conditions
■Defining Temporal Conditions
25.10.4.1 About Temporal Conditions
With the Temporal condition type, Administrators must add the start and end time
and the range of days. Like the other conditions, this one can be used in conjunction
with identity and IP4 Range conditions.
By default, all days in the range are enabled (though none are checked in the form as
shown in Figure 25–24.
Figure 25–24 Temporal Condition Type Details Page
Time periods must be specified in the HH:MM:SS (hour, minute, and second) format
based on a 24-hour clock based on Greenwich Mean Time (GMT). Midnight is
specified as 00:00:00 (start). The day ends at 24:59:59.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-55
Save the details before closing this page.
25.10.4.2 Defining Temporal Conditions
Users with valid Administrator credentials can use the following procedure to add
temporal type conditions to an Application Domain.
Prerequisites
The Application Domain must exist.
To add temporal conditions to an authorization policy
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the Conditions tab, click the Add (+) button.
3. Enter a Name, select Temp or al from the Type list, enter an optional Description,
and click Add Selected.
4. In the Details panel (Table 25–16): Click the condition name in the table to open the
details panel:
■Enter the Start time.
■Enter the End time.
■Click the days of the week to which this condition applies (or leave all blank to
specify every day of the week).
■Click Save.
5. Click Apply and then close the Confirmation window.
6. Verify the Temporal Conditions by logging in at different times to validate access
to the protected resource.
25.10.5 Defining Attribute Conditions
This section provides the following topics:
■About Attribute Conditions
Table 25–16 Temporal Condition Details
Elements Description
Start Time
Notes: Time is specified using a
full 24-hour range. For instance,
midnight is specified as 00:00:00
and 11:00 PM is specified as
23:00:00.
Specifies the hour, minute, and second that this condition begins.
Notes: Time is based on Greenwich Mean Time (GMT). GMT is the
same all year with no adjustments for daylight savings time or
summer time.
End Time Specifies the hour, minute, and second that this condition concludes.
Days Specifies the days where this policy is active.
Default: All Days (even though these are not checked).
See Also: "Defining Temporal Conditions"
Note: You must save each condition definition individually, before
adding or selecting another condition.
See Also: "About Temporal Conditions" on page 25-54
Defining Authorization Policy Conditions
25-56 Administrator's Guide for Oracle Access Management
■Defining Attribute Type Conditions
25.10.5.1 About Attribute Conditions
An attribute-type condition enforces the evaluation of request context, user session
state and user attributes for Allow or Deny access pertaining to all resource types and
authorization policies in the Application Domain. With an attribute-type condition
defined, access is based on a list of name-value pairs scoped by the:
■Request context: Information on the requested resource, the client making the
request, and the policy that was matched during evaluation.
■Session: User Session details (pre-defined session attributes or a reference to an
arbitrary session attribute) when the user has an established session.
■User: User attribute information (reference to a LDAP attribute). This condition is
used to define a condition on a reference to a user's arbitrary LDAP attribute only.
However, conditions based on userID or groupID are defined using Identity
Conditions.
Attribute type conditions are required when access is based on one of the situations
described in Table 25–17.
An Administrator defining attribute type conditions enters data into fields for built-in
attributes and known attributes. The attribute name can be entered in a text field or
selected from a list of values. The condition to be executed is constructed using
"AND" or "OR" conjunctions on the condition. Figure 25–25 illustrates the Attribute
Conditions page.
Table 25–17 Access Conditions that Require Attribute-Type Conditions
When Access is based on ... Description
Session attribute A user is authorized to access the resource if the session
attribute "Authentication level" is xx and Session Attribute
"s1" = "v1" and Session Start Time = "xxxx".
See: Table 25–20, " Attribute Names for Session Built-ins"
Requested resource hostname and port number
See: Table 25–19, " Attribute Names for Request Built-ins"
User details A user is authorized to access the resource if its "Empno" =
"xxxx" (department=sales, for example)
See: Table 25–21, " Attribute Condition Data (Aggregation of
Conditions)"
Token Issuance based on a
session attribute
The Requester Partner can issue a token to the Relying Party if
the claim contains an attribute "SessionActiveTime" = "15000".
You define claims-based conditions of the Token Issuance
policy based on the assertions created using session data.
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-57
Figure 25–25 Attribute Conditions Page
Figure 25–26 shows the Add Attribute Condition dialog box. Each attribute condition
is defined by the fields described in Table 25–18.
Figure 25–26 Add Attribute Condition Dialog
See Also: "Defining Attribute Conditions"
Table 25–18 Attribute Condition Elements
Condition Description
Namespace Supported namespaces:
■Request Built-ins
■Session Built-ins
■Session (User Session)
■User (User Attributes)
Defining Authorization Policy Conditions
25-58 Administrator's Guide for Oracle Access Management
Request Built-ins
Table 25–19 identifies the list of built-in attribute names for Request Built-ins:
Session Built-ins
Table 25–20 identifies the list of attribute names for Session-based attribute-type
conditions.
Example: Attribute Condition Data (Aggregation of Conditions)
Table 25–21 illustrates sample condition data for each allowable namespace.
Name Attribute name, which can be added as follows, depending on the:
■Selected from a list if the Namespace is Request (Table 25–19) or
Session (Table 25–20)
■Entered manually into a text field if the Namespace is User
Operator Allowed operators:
■STARTS WITH
■EQUALS
■CONTAINS
■ENDS WITH
Value Literal value with no special wildcard characters.
Table 25–19 Attribute Names for Request Built-ins
Attribute Name Description
agent_id Name of the requesting agent.
client_ip IP address of the user browser.
Policy_appdomain Name of the Application Domain holding the policy matched
for the request.
Policy_res Resource host ID and URL pattern matched for the request.
policy_name Name of the specific policy matched for the request.
res_host Requested resource's hostname.
res_port Requested resource's port number.
res_type Requested resource's type.
res_url Requested resource URL.
Table 25–20 Attribute Names for Session Built-ins
Attribute Name Description
Authentication Level Current authentication level for the session.
Authentication Scheme Name of the authentication scheme executed to achieve the
current authentication level.
Session Count Session count for the user bound to this session.
Session Creation Time Session creation time.
Session Expiry Time Session expiration time.
Table 25–18 (Cont.) Attribute Condition Elements
Condition Description
Defining Authorization Policy Conditions
Managing Policies to Protect Resources and Enable SSO 25-59
25.10.5.2 Defining Attribute Type Conditions
Users with valid Administrator credentials can use the following procedure to add
attribute type conditions to an Application Domain.
Prerequisites
The Application Domain must exist.
To add attribute type conditions to an authorization policy
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the Conditions tab, click the Add (+) button.
3. Enter a Name, select Attribute from the Type list, enter an optional Description,
and click Add Selected.
4. Add Details for Attribute Condition: Click the name of the condition to expand
the details panel, and:
■Match: Click either All or Any.
■Namespace: Select from the list (Table 25–18).
■Name: Select from the list or enter manually (Table 25–19 or Table 25–20).
■Operator: Select from the list (Table 25–18).
■Value: Enter manually (Table 25–21).
■Click Save.
■Repeat as needed.
5. Click Apply and then close the Confirmation window.
6. Verify the Attribute Conditions by logging in with different scenarios.
25.10.6 Viewing, Editing, or Deleting Authorization Policy Conditions
Users with valid Administrator credentials can use the following procedure to add
identity type conditions to an Application Domain.
Prerequisites
The Application Domain and authorization policy exist.
Table 25–21 Attribute Condition Data (Aggregation of Conditions)
Namespace Name Operator Value
Request-Builtins Res_host Equals 7777
Session-Builtins Authn_level Equals 2
Session Sessionattr1 Contains Foo
User department Equals sales
Note: You must save each condition definition individually, before
adding or selecting another condition.
See Also: "About Attribute Conditions" on page 25-54
Defining Authorization Policy Rules
25-60 Administrator's Guide for Oracle Access Management
To view, edit, or delete authorization policy conditions
1. Locate the desired policy as described in "Searching for an Authorization Policy".
2. Click the Conditions tab.
3. Edit Condition Details: Click the desired condition, click the Edit button to
display the Details panel. Depending on the condition type, perhaps only the
Description can be edited.
■"Defining Identity Conditions" on page 25-45
■"Defining IP4 Range Conditions" on page 25-51
■"Defining Temporal Conditions" on page 25-54
■"Defining Attribute Conditions" on page 25-55
■True: Click the name, click the Edit button; only the Description can be edited.
4. Delete Conditions: Click the condition to remove and click the Delete button on
the Condition tab.
5. Click Apply and then close the Confirmation window.
6. Close the page when you finish.
7. Verify the Conditions by accessing the resource and evaluating the results.
25.11 Defining Authorization Policy Rules
When Allow access rules, Deny access rules, or both are specified and do not apply to
a user, the user is not qualified by the rule, and is denied access to the requested
resource by default.
To specify who is allowed or denied access to the resource, the rule can do the
following:
■Identify the users by user name, role, or an LDAP filter whose criteria the user
must satisfy.
■Stipulate the computers where users can access resources.
■Set a time period when the rule applies.
This section provides the following topics:
■About Defining Rules in an Authorization Policy
■About Expressions and Expression-Based Policy Evaluation
■Defining Rules in an Authorization Policy
25.11.1 About Defining Rules in an Authorization Policy
Rules are new constructs in the Access Manager 11g policy model. A Rule specifies of
how to combine condition evaluation outcomes. Each Rule also contains a rule effect
(ALLOW or DENY), which determines the overall policy outcome.
Authorization rules define the actions to take during evaluation of the policy,
conditions, and rules as well as what to do based on the outcome. There are three
possible outcomes:
See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40
Defining Authorization Policy Rules
Managing Policies to Protect Resources and Enable SSO 25-61
■True (Allow access): If the user meets the Allow access condition, the user qualifies
for the Allow access part of the rule.
■False (Deny access): If the user meets the Deny access condition, the user qualifies
for the Deny access part of the rule.
■Inconclusive: If the user satisfies neither the Allow access nor the Deny access
conditions, the rule is said to be unqualified for that user. You can also think of this
as the user not qualifying for the rule. If evaluation of a rule results in an
unqualified user, the user is denied access to the resource based on that rule.
In some cases, a single authorization rule is all that is required to protect the resources
of an Application Domain or a policy. You can configure a rule to identify who is
allowed access to the resources it protects, who is denied access to them, and under
what conditions these controls apply (for example, when they apply and from which
computer). An authorization rule does not need to cover all users in its Allow access
and Deny access conditions. Users who request access to a resource that is protected
by the rule but do not qualify for any of the conditions are, by default, denied access to
the resource.
For other cases, it may be necessary to configure multiple authorization conditions
into rules to protect resources. You can impose complex conditions on different users.
For example, you can define a rule that includes several authorization conditions, one
or more of which a user must meet to qualify for access to a protected resource (or to
qualify for denial of access to it). For example, you might require the user to meet two
conditions—such as belonging to one group and using a computer assigned a specific
IP address—to be granted access to the resource.
Oracle Access Management Console makes it easy for you to form expressions for an
authorization rule. Conditions are declared outside of rules and are referenced within
rules. Evaluation outcomes are combined in either Simple mode or Expression mode.
Figure 25–27 shows the Rules tab in an authorization policy.
Defining Authorization Policy Rules
25-62 Administrator's Guide for Oracle Access Management
Figure 25–27 Authorization Policy Rules Tab: Simple Mode
Table 25–22 describes the elements and controls on the Rules tab for Simple Mode
evaluations.
Table 25–22 Authorization Policy Rules Elements
Element Description
Rule Mode The method used for evaluation of conditions and rules:
■Simple: Accepts a list of condition names that are
combined using a simple algorithm:
ALLOW conditions are combined using logical AND. All
Allow conditions must be met to get access.
DENY conditions are combined using logical OR. Any
Deny condition that is true denies access. DENY always
takes precedence over ALLOW.
■Expression: Accepts a user-specified Boolean expression
to combine conditions using condition names, "(", ")", "|",
"&" and "!" special characters. Combines conditions into
complex policies.
See Also: "About Expressions and Expression-Based
Policy Evaluation" on page 25-63
■A policy in which there are one or more conditions that
are not part of either Allow rule or Deny rule is treated as
a valid policy.
Allow Rule The rule that allows access based on evaluation of your rules
and the Selected Conditions list.
Defining Authorization Policy Rules
Managing Policies to Protect Resources and Enable SSO 25-63
25.11.2 About Expressions and Expression-Based Policy Evaluation
When a user requests access to a resource that is protected by an authorization
condition and rule, information about the user is checked against the rule. If the
condition stipulates other information, such as time period or time of day the
condition applies, that, too, is checked. This process is referred to as evaluation of the
rule.
An authorization expression consists of a single rule or a group of rules combined to
express more complex conditions. For example, you can create an expression that
requires a user to meet the Allow access conditions of two rules to be granted access to
the resource. You use the Oracle Access Management Console to create these
expressions, which include the following elements:
■Authorization conditions that you select from those that are defined and available
in the authorization policy
■Operators that you use to combine rules to provide the kind of authorization
protection that you want (Table 25–24)
For expressions that contain multiple conditions, a user may qualify for none of the
expression's conditions, one of the conditions, or for the conditions of multiple rules.
In any case, it is the result of evaluation of the expression—all of its conditions and
how they are combined—not any one condition, that determines whether a user is
allowed or denied access to a resource.
About the Definitive Result of an Authorization Expression: Access Manager
evaluates the rules of an expression until it can produce a definitive result. Evaluation
of an authorization expression may produce a definitive Allow access result, a Deny
access result, or an Inconclusive result.
Figure 25–28 shows the Rules tab when you use Expression as a Rule Mode.
Deny Rule The rule that denies access based on the evaluation of your
rules and the Selected Conditions list.
Match Criteria you choose to either match All conditions in the
Selected Conditions list or Any conditions the Selected
Conditions list.
Available Conditions A list of all defined conditions for this authorization policy.
Selected Conditions A list of the specific conditions that you build by moving
items from the Available Conditions list to this list for use
during the policy evaluation process.
Arrow Controls Controls in the form of arrows enable you to add a condition
to the Selected Conditions list (or vice versa to remove a
condition from those selected).
Table 25–22 (Cont.) Authorization Policy Rules Elements
Element Description
Defining Authorization Policy Rules
25-64 Administrator's Guide for Oracle Access Management
Figure 25–28 Rules Tab: Expression Rule Mode
Table 25–23 describes the elements on the Rule tab in Expression mode.
Table 25–24 identifies the operators you can use when building an authorization
expression.
Table 25–23 Rule Tab in Expression Mode
Element Description
Rule Mode The method used for evaluation of conditions and rules:
■Expression: Accepts a user-specified Boolean expression to
combine conditions using condition names, "(", ")", "|", "&" and "!"
special characters. Combines conditions into complex policies.
■A policy in which there are one or more conditions that are not
part of either Allow rule or Deny rule is treated as a valid policy.
See Also: Table 25–24, " Operators for Expressions in Authorization
Rules"
Allow Rule The rule that allows access based on evaluation of your rules and the
Selected Conditions list.
Deny Rule The rule that denies access based on the evaluation of your rules and
the Selected Conditions list.
Conditions Provides a list of all conditions defined for this authorization policy.
Insert Condition Adds the selected Condition to the expression window.
Validate Automatically tests the validity of the expression and reports results.
Table 25–24 Operators for Expressions in Authorization Rules
Operator Description
( ) By default, two rules on either side of an AND operator compose the compound AND
condition. Rules on either side of an OR operator are alternatives. When no
parenthesis are used to enforce grouping of rules, the AND operator takes precedence
over the OR operator.
You can use parenthesis to override the default way in which the rules of an
expression are grouped. Evaluation still occurs from left to right, but the rules are
organized within the couplings and groups you create through use of parenthesis.
Defining Authorization Policy Rules
Managing Policies to Protect Resources and Enable SSO 25-65
25.11.2.1 Expression Evaluation in Authorization Rules
The result of evaluation of an authorization rule, in conjunction with other
authorization rules, if more than one is included in the expression, determines if a user
is granted access to the requested resource. Evaluation of the rule occurs as follows:
■Each authorization rule specified in the expression is evaluated from left to right.
The outcome is combined progressively with the previously evaluated rules.
■When the evaluation outcome is good enough to decide the overall policy
outcome without having to evaluate any more rules, evaluation stops and the
overall outcome is returned.
■Each evaluation outcome can be either True, False, or Inconclusive.
Authorization Success: In this case, the user succeeds in gaining access to the
requested resource. This result is associated with the Allow Access condition of
the expression.
Authorization Failure: In this case, the user fails to gain access to the requested
resource. This result is associated with the Deny Access condition of the
expression.
Authorization Inconclusive: In this case, the rules of the expression produce
conflicting results, and the user is denied access to the resource. If the match for
Identity, IP4 address, or timing condition fails then expression evaluation stops
and the result of the overall evaluation is deemed Inconclusive. However, based
on the other rules present in the expression, this result might not affect the overall
policy evaluation.
For example, the following expression:
(Rule1 AND Rule 2) OR (Rule 3 AND Rule 4)
Yields the following outcomes:
■Rule1 - INCONCLUSIVE
■Rule2 - FALSE
& The AND operator, which you use to form a compound condition which combines
authorization rules. Any number of rules can be combined using the AND operator to
implement the full scope of conditions a user must meet to satisfy the authorization
requirement. However, a user must satisfy the same kind of condition—either Allow
Access or Deny Access—of all of the rules of the AND compound condition for the
AND clause to produce a definitive result.
An authorization expression can contain more than one coupling or grouping of rules
combined using AND. For example, it may contain several AND clauses, one
connected to another by an OR operator.
| The AND operator. An authorization expression can include a complex rule
containing two or more alternative authorization conditions. Authorization rules
forming a complex condition are combined using the OR operator. Each of the
authorization rules specified by a complex OR condition stands on its own. Unlike
compound conditions using the AND operator, the user need qualify for the condition
of only one of the authorization rules connected by OR operators.
An authorization expression can contain as many authorization rules connected using
the OR operator as are required to express the authorization policy for the resources it
protects. You can use the OR operator to connect authorization rules all of which have
Deny Access conditions, all of which have Allow Access conditions, or which specify
a mix of Deny Access and Allow Access conditions. You can connect single rules to
single rules using OR, and you can connect a single rule to a clause containing rules
combined using AND.
Table 25–24 (Cont.) Operators for Expressions in Authorization Rules
Operator Description
Defining Authorization Policy Rules
25-66 Administrator's Guide for Oracle Access Management
■Rule3 - TRUE
■Rule4 - TRUE
■Overall: TRUE (Allow)
The following sample expression uses (in order of type) Identity, Temporal, IP4Range,
and Attribute conditions:
(IsEMEAemployee & IsEMEAWorkingHours & !(ConnectedOverVPN |NotReadDisclaimer))
Condition names that include spaces, tabs, or special characters (if properly escaped
when defining the expression) are properly handled
25.11.3 Defining Rules in an Authorization Policy
Users with valid Administrator credentials can use the following procedure to add
rules to an authorization policy.
Prerequisites
Defining Authorization Policy Conditions.
To define authorization policy rules
1. Locate the desired domain as described in "Searching for an Authorization Policy".
2. Click the Rules tab.
3. Expression:
a. Click Expression as the Rule Mode.
b. In the Allow Rule Expression field, build your expression by entering
operators (Table 25–24) and choosing and inserting conditions (Table 25–23).
c. Click the Validate button to confirm your expression.
d. Repeat Steps b and c for the Deny Rule.
e. Click Apply.
4. Simple Rule Mode:
a. Click Simple as the Rule Mode.
b. Allow Rule:
Click to Match either:
All selected conditions
Any of the selected conditions
Using arrows for Allow (or Deny) Rule, move desired conditions from the
Available Conditions column into the Selected Conditions column.
Click Apply.
c. Repeat step b for the Deny Rule.
5. Click Apply and then close the Confirmation window.
6. Verify the rules by accessing the resource and evaluating the results.
See Also: "About Defining Rules in an Authorization Policy"
Configuring Policy Ordering
Managing Policies to Protect Resources and Enable SSO 25-67
25.12 Configuring Policy Ordering
Previous releases of Access Manager used a policy matching algorithm to match
incoming resource URLs with the stored patterns in an Application Domain. A best
match is arrived at based on a predefined algorithm. (This algorithm can not be
changed.) If multiple patterns are matched with an incoming URL, the best match
pattern is selected and its associated policy is evaluated.
With this 11gR2 PS2 release, rather than the best match algorithm, an Administrator
manually designates the order of policies within an Application Domain. To turn on
Policy Ordering, the Administrator must first add one or more resource prefixes to the
Application Domain. Once these have been added, you can click the Enable Policy
Ordering flag. (See Figure 25–2, "Example Application Domain Summary Page".)
Figure 25–29 is a screenshot of the Resource Prefix configuration pop up.
Figure 25–29 Adding a Resource Prefix for Policy Ordering
During runtime, the incoming URL of the protected resource is checked to determine if
it starts with any resource prefix defined in the Application Domain. If the URL
matches a resource prefix, the policies in the Application Domain configured with that
resource prefix are checked (in the order defined by the Administrator) to see if any
resource in the policy matches the incoming resource. If the incoming resource
matches a particular policy, it is evaluated and the results are returned; the other
policies are not checked.
To configure Policy Ordering
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, select Create Application Domain from the
Create (+) drop-down menu
3. On the Create Application Domain page, add a unique name and an optional
description.
4. Click Add to add a Resource Prefix.
5. Tick the Enable Policy Ordering box.
Note: You may create resource prefixes and not enable policy
ordering. In this case, the resource prefixes are ignored and the best
match algorithm is used.
Introduction to Policy Responses for SSO
25-68 Administrator's Guide for Oracle Access Management
6. Select the Resource Type from the drop down list.
See Table 25–1 for definitions of the default Resource Types.
7. Add an optional host identifier.
Host identifier is mandatory for an HTTP Resource Type.
8. Add the Resource Prefix.
For example, if the policy Resource being protected is /em/**, the Resource Prefix
is /em. If the policy Resource being protected is /blog/**, the Resource Prefix is
/blog.
9. Click Add.
25.13 Introduction to Policy Responses for SSO
Each policy can optionally contain one or more authentication or authorization
responses, or both. Responses are post-processing actions (obligations) to be carried
out by the web agent.
This section provides the following information:
■About Authentication and Authorization Policy Responses for SSO
■About the Policy Response Language
■About the Namespace and Variable Names for Policy Responses
■About Constructing a Policy Response for SSO
■About Policy Response Processing
■About Assertion Claims and Processing
25.13.1 About Authentication and Authorization Policy Responses for SSO
Administrators can define responses that declare the actions that must be fulfilled after
successful authentication or authorization. Authentication and authorization data is
returned to the client (typically a Web Agent).
Policy responses enable the insertion of information into a session or application and
the ability to withdraw the information at a later time to enable SSO. For instance,
identity mappings can be inserted into the customer's application or actions can be
carried out by the Agent or the application.
Depending on the responses specified for authentication or authorization success and
failure, the user might be redirected to a specific URL, or user information might be
passed on to other applications through a header variable or a cookie value.
There are no default response provided. Figure 25–30 illustrates an Authorization
Policy Response defined by an Administrator in the Oracle Access Management
Note: There are no responses in Token Issuance Policies.
Note: Oracle Access Manager 10g provided data passage to (and
between) applications only by redirecting to URLs in a specific
sequence.
Introduction to Policy Responses for SSO
Managing Policies to Protect Resources and Enable SSO 25-69
Console. Authorization responses can operate in conjunction with authorization
conditions.
Figure 25–30 Authorization Policy Response in the Console
Each response consists of two inputs (a type and an expression) and a single output
(the value of the evaluated expression). The expression declares how the value should
be constructed when the expression is processed. The response type defines the form
of action to be taken with the value string.
■The authentication policy determines the identity of the user. Each authentication
policy requires an authentication scheme and responses (expressions).
■The authorization policy determines whether the user has the right to access the
resource. Each authorization policy requires authorization conditions and
responses (expressions).
Response Guidelines
1. Cookie, Header, and Session responses are supported.
2. URL redirection can be set.
3. Response definitions are part of each policy. Response values can be literal strings
or can contain additional embedded expressions that derive values from request,
user, and session attributes.
Administrators set Responses in the Oracle Access Management Console, as described
Table 25–25.
Table 25–25 Response Elements
Element Description
Name A unique name to distinguish this response from other responses that use the same
mechanism (type).
Introduction to Policy Responses for SSO
25-70 Administrator's Guide for Oracle Access Management
25.13.2 About the Policy Response Language
Access Manager authentication and authorization responses are defined using a very
small, domain-specific language (DSL) with two main constructs:
■Literal strings: For example:
This is a valid expression
■Variable references:
–Declared using a dollar sign prefix
$
–Scoped to a namespace: $
namespace.var_name
25.13.3 About the Namespace and Variable Names for Policy Responses
With the namespace mechanism, the following variable types are to enable single
sign-on:
Type The mechanism used to convey the response. form of the action to be taken with the
value string:
■HEADER (Header variables): Sets an HTTP request header for downstream
applications using the defined value to dictate the action to be taken (such as the
assertion of a User ID using a pre-defined HTTP header name). Another example
gets the subscriber information (realm DN and so on) for OSSO and creates a
response during the upgrade; a fresh OSSO Agent requires manual configuration.
■SESSION: Sets an attribute inside the user session by the client (to enable single
sign-on) based on the defined session variable name and value.
■COOKIE: Sets a variable name and value (typically set by Web agents) inside the
authentication session cookie to enable single sign-on.
In cookie-less mode, Web-cache is currently used to store cookies from Webgate.
However, in cookie-less mode, the end application does not have access to cookies
and cannot use them.
■Asserted Attribute: With this type, Identity Assertion must be enabled for the
policy to collect Assertion Attribute type responses when this policy is executed.
The Name list provides valid identifiers from which to choose.
Value The response expression, set as a variable.
For more information, see "About the Policy Response Language".
Identity
Assertion
Identity Assertion is required for ID propagation for any issued token from Access
Manager that represents an end user (and possibly its Access Manager session).
Security Token Service clients that are Web applications protected by Access Manager
requesting tokens to gain proxy access to a Relying Party (ID Propagation use case) are
required to pass an Access Manager Identity Assertion token that represents the end
user.
The Identity Assertion Token is generated and returned as a policy response (HTTP
HEADER named "OAM_IDENTITY_ASSERTION", value as a SAML token) after a
successful authentication.
As you add each (non-Asserted Attribute Type) Response, you might be informed that
Identity Assertion has not been enabled for this policy....
Enable Identity
Assertion to collect Assertion Attribute type responses when this policy is executed.
See Also:
■"Scenario: Identity Propagation with the Access Manager Token" on page 42-2
■"Authentication Policy Response for Identity Assertion by Webgate" on page 42-13
■Chapter 55, "Using Identity Context"
Note: Certain variables include an attribute:
$ns.name.attribute
Table 25–25 (Cont.) Response Elements
Element Description
Introduction to Policy Responses for SSO
Managing Policies to Protect Resources and Enable SSO 25-71
■Request: Information on the requested resource, the client making the request, and
the policy matched during evaluation
■Session: User session details
■User: User details (user ID, group, and attribute information)
For details of each, see:
■Table 25–26, " Namespace Request Variables for Single Sign-On"
■Table 25–27, " Namespace Session Variables for Single Sign-On"
■Table 25–28, " Namespace User Variables"
Table 25–26 Namespace Request Variables for Single Sign-On
Namespace Description
agent_id Name of the requesting agent
client_ip IP address of the user browser
policy_appdomain Name of the Application Domain holding the policy matched for the
request
policy_eval_success_conditions List of policy conditions that evaluated to true, separated by COLON or
configured response separator
policy_eval_failure_conditions List of policy conditions that evaluated to false, separated by COLON or
configured response separator
policy_res Resource host ID and URL pattern matched for the request
policy_name Name of the specific policy matched for the request
res_host Requested resource's hostname
res_port Requested resource's port number
res_type Requested resource's type
res_url Requested resource URL path
res_complete_url Requested resource URL path with query string
Table 25–27 Namespace Session Variables for Single Sign-On
Namespace Description
attr Reference to an arbitrary session attribute, the name of which is passed
to us as a variable attribute. Its value has been bound to the session by
executing a session response during a previous request.
authn_level Current authentication level for the session
authn_scheme Name of the authentication scheme executed to achieve the current
authentication level
count Session count for the user bound to this session
creation Session creation time
expiration Session expiration time
Table 25–28 Namespace User Variables
Namespace Description
attr.<attrName> Value of user attribute attrName. If attrName is multivalued, list of
values, separated by COLON or configured response separator.
groups List of user's group membership, separated by COLON or configured
response separator.
Introduction to Policy Responses for SSO
25-72 Administrator's Guide for Oracle Access Management
25.13.4 About Constructing a Policy Response for SSO
This section is divided as follows:
■Simple Responses
■Compound and Complex Responses
■Multi-Valued Responses
25.13.4.1 Simple Responses
After deciding on the response type and determining which namespace and variable,
you simply enter the response attributes in the Oracle Access Management Console. A
simple response might look like one of the several authorization responses shown in
Figure 25–31.
Figure 25–31 Simple Response Samples
Simple responses stand alone. Each is preceded with the dollar sign ($), followed by
the namespace, which is separated from the variable Value by a dot (.). For example:
$namespace1.var1
Table 25–29 illustrates several simple responses and a description of what each one
returns.
userid The user ID
user.id_domain The user's identity domain (essentially the same as the identity store)
guid A unique identifier that locates the user entry in an Identity Store
See Also: Guidelines for Authorization Responses Based on
Conditions
Table 25–29 Simple Responses and Descriptions
Name Type
Value (Simple
$Namespace.Variable) Returned Environment Variables and Values
oam_sessioncount Header $session.count HTTP_OAM_SESSIONCOUNT integer
oam_userid Header $user.userid HTTP_OAM_USERID name
oam_ipaddress Header $request.client_ip HTTP_OAM_IPADDRESS nnn.nn.nn.nnn
oam_literal Header This is a response string. HTTP_OAM_LITERAL This is a response string
Table 25–28 (Cont.) Namespace User Variables
Namespace Description
Introduction to Policy Responses for SSO
Managing Policies to Protect Resources and Enable SSO 25-73
25.13.4.2 Compound and Complex Responses
When crafting a compound or complex policy response, Administrators can combine
literals and variables arbitrarily using braces { } to construct an expression. A colon (:)
is used as a separator. For example:
${namespace1.var1}:${namespace2.var2}
Literal String (LS): ${namespace1.var1}:${namespace2.var2}
LS: ${namespace1.var1}, LS:${namespace2.var2}
Figure 25–32 illustrates several complex responses defined by an Administrator. All
are Header type responses, which set values in a header variable of an HTTP request
for consumption by a downstream application.
Figure 25–32 Complex Response Sample
Table 25–30 describes the complex responses shown in Figure 25–32.
For more information, see "About Policy Response Processing".
25.13.4.3 Multi-Valued Responses
Access Manager 11g supports responses with multiple values. These can be
multivalued user attribute responses, user's group membership responses and the like.
For multivalued responses, Access Manager uses a COLON as the separator and a
BACKSLASH as the escape character. For example, if a user attribute
genType
has the
values "Gold", "Platinum" and "Silver", the policy response for
$user.attr.genType
would be:
"Gold:Platinum:Silver"
Table 25–30 Complex Responses
Name Value Returned Environment Variables and Values
oam_resinfo Runtime resource: ${request.res_host}:${request.res_
port}${request.res_url}
HTTP_OAM_RESINFO
Runtime resource:
myhost.domain.com:1234/cgi-bin/myres3
oam_clientinfo Runtime client: Agent ID: ${request.agent_id}, Browser IP:
$request.client_ip
HTTP_OAM_CLIENTINFO
Runtime client: Agent ID: RREG_OAM, Browser
IP: 123.45.67.891
oam_userinfo ${user.userid}'s groups: ${user.groups}, description:
${user.attr.description}
HTTP_OAM_USERINFO
WebLogic's groups: Administrators, description: This
user is the default Administrator
oam_sessioninfo Session creation/expiration/count:
${session.creation}/${session.expiration}/${session.count}
HTTP_OAM_SESSIONINFO
Session creation/expiration/count: Tue O ct 23
17:47:42 PST 2011/Wed Oct 24 01:47:42 PST 2011/7
oam_app_user $user.userid HTTP_OAM_USERID name
Introduction to Policy Responses for SSO
25-74 Administrator's Guide for Oracle Access Management
If a COLON appears in any of the attribute values, it will be escaped with
BACKSLASH. For example, for a user with group memberships as "Administrators",
"Special:Users", the policy response for
$user.groups
would be
"Administrators:Special\:Users"
It is possible to change the default separator and escape character using the
configurePolicyResponses(responseSeparator, responseEscapeChar) WLST command.
Refer to the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference
for details.
25.13.5 About Policy Response Processing
Policy response processing occurs during the authorization request for which the
authentication responses are replayed. Variable references are filled with appropriate
values to ensure that all variables have a value set, and can be set consistently with
authorization values.
Processing a response expression is done through a series of steps:
■Scanner/tokenizer
■Parser
■Interpreter
During interpretation, variable references are resolved to values. The result after
processing is a simple String value, which is propagated to the Agent or saved
within the session for future use.
Authentication success responses are saved and then "replayed" along with any
authorization responses on the first applicable authorization request.
Authorization response expressions create the actions to be taken, depending on the
evaluation of the expression: success, failure, or inconclusive.
When referencing a variable, either the value is returned, or the following is returned:
■NOT FOUND is returned if the variable is not set
■NULL is returned if the variable is set to a null value
Pass Through Without Processing
A value that must be passed through without processing, can be identified using a \.
For example:
\$1000
results in the value
$1000
appearing in the returned value.
Note: Oracle Access Manager 10g exhibits the same behavior in the
"authenticating Webgate" configuration. This is also employed by
Access Manager 11g with 10g Webgates: The 10g Webgate always
redirects to the Access Manager 11g credential collector which acts like
the authenticating Webgate.
Note: Verify the Responses.
Adding and Managing Policy Responses for SSO
Managing Policies to Protect Resources and Enable SSO 25-75
25.13.6 About Assertion Claims and Processing
For details, see Chapter 55, "Using Identity Context".
25.14 Adding and Managing Policy Responses for SSO
Policies and responses enable single sign-on and can override other directives. Before
starting activities in this section, be sure to review the "Introduction to Policy
Responses for SSO" on page 25-68.
Unless explicitly stated, information in this section applies equally to authentication
and authorization responses.
■Adding a Policy Response for SSO
■Viewing, Editing, or Deleting a Policy Response for SSO
25.14.1 Adding a Policy Response for SSO
Users with valid Administrator credentials can use the following procedure to add a
policy response for authentication or authorization to the Protected Resource Policy.
For example, you can collect the DN of the realm that is created when Oracle Internet
Directory is installed. Optionally, you can also configure the global user ID of the
subscriber in Oracle Internet Directory or a subscriber name rather than the default
company as shown in Table 25–31.
Prerequisites
Analyze desired conditions before crafting authorization responses to ensure the
appropriate actions are taken by the response. You need an Application Domain with
an existing authentication or authorization policy.
To add a policy Response
1. Locate the desired domain as described in "Searching for an Authorization Policy".
2. In the individual policy page, click the Responses tab, then click the Add button
and:
■In the Name field, enter a unique name for this response.
■From the Type list, choose a response type (Session or Header or Cookie).
■In the Valu e field, enter a value for this response. For example:
$namespace1.var1
Table 25–31 Fresh OSSO Installation: Protected Policy Response (Header)
Response
Parameter
Collect Realm DN when OID
is Installed
Configure GUID of Subscriber
IN OID to Different Company
Configure GUID of Subscriber IN OID to
Default Company
Name osso-subscriber-dn (lowercase) osso-subscriber (optional) osso-subscriber-guid (optional)
Type Header Header Header
Value dc=country,dc=example,dc=com dc=country_or_region,dc=com ,dc=default_company,dc=com
Go to the subscriber DN (in Oracle Internal
Directory for example) and find the value (of
orclguid for the DN, for example).
See Also: "Introduction to Policy Responses for SSO" on page 25-68
Validating Authentication and Authorization in an Application Domain
25-76 Administrator's Guide for Oracle Access Management
■Repeat as needed.
3. Click Apply, then close the Confirmation window.
4. Close the page when you finish.
5. Verify the Responses based on your definitions.
25.14.2 Viewing, Editing, or Deleting a Policy Response for SSO
Users with valid Administrator credentials can use the following procedure to view or
edit a policy response for authentication or authorization.
Prerequisites
You must have an Application Domain with an existing authentication or
authorization policy.
To view, modify, or delete a policy response
1. Locate the desired domain as described in "Searching for an Existing Application
Domain".
2. Click the Authentication (or Authorization) Policies tab, then click the desired
policy name.
3. On the individual policy page, click the Responses tab and proceed as needed:
■Add: See "Adding a Policy Response for SSO"
■Edit: Click the desired Response Name, Type, or Value, edit as needed, and
click Apply.
■Delete: Click the desired response, then click the Delete button for the
Response table.
4. Close the Confirmation window.
5. Close the page when you finish.
6. Verify Responses based on your definitions for:
■Header
■Session
■Cookie: Use a browser plug-in tool or turn on the browser "show cookies"
settings.
■Assertion Claim
25.15 Validating Authentication and Authorization in an Application
Domain
The procedure here provides several methods for confirming that Agent registration
and authentication and authorization policies are operational. The procedures are
nearly identical for both OAM Agents and OSSO Agents (mod_osso). However, OSSO
Agents use only the authentication policy and not the authorization policy.
See Also: "About the Namespace and Variable Names for Policy
Responses" on page 25-70
See Also: "Introduction to Policy Responses for SSO" on page 25-68
Understanding Remote Policy and Application Domain Management
Managing Policies to Protect Resources and Enable SSO 25-77
Prerequisites
■Users and groups who are granted access must exist in the primary LDAP User
Identity Store that is registered with Oracle Access Management
■Agents must be registered to operate with Access Manager. After registration,
protected resources should be accessible with proper authentication without
restarting the Administration or Managed Server.
■Application domain, authentication policies, and authorization policies must be
configured.
■Logout should be configured as described in Chapter 27, "Configuring Centralized
Logout for Sessions Involving 11g WebGates"
To verify authentication and access
1. Using a Web browser, enter the URL for an application protected by the registered
Agent to confirm that the login page appears (proving that the authentication
redirect URL was specified appropriately). For example:
http://exampleWebserverHost.example.com:8100/resource1.html
2. Confirm that you are redirected to the login page.
3. On the Sign In page, enter a valid username and password when asked, and click
Sign In.
4. Confirm that you are redirected to the resource and proceed as follows:
■Success: If you authenticated successfully and were granted access to the
resource; the configuration is working properly.
■Failure: If you received an error during login or were denied access to the
resource, check the following:
–Authentication Failed: Sign in again using valid credentials.
– Access to URL ... denied: This userID is not authorized to access this
resource.
– Resource not Available: Confirm that the resource is available.
– Wrong Redirect URL: Verify the redirect URL in the Oracle Access
Management Console.
25.16 Understanding Remote Policy and Application Domain
Management
Several remote management modes enable Administrators to update, or validate, or
delete an existing agent registration. This section provides the following topics:
■About Managing Policies Remotely
■About the Create Policy Request Template
■About the Update Policy Request Template
■About Remote Policy Management and Templates
See Also: Chapter 26, "Validating Connectivity and Policies Using
the Access Tester"
Understanding Remote Policy and Application Domain Management
25-78 Administrator's Guide for Oracle Access Management
25.16.1 About Managing Policies Remotely
Access Manager provides two modes to manage Application Domains and their
policies without registering or modifying the companion agent. Remote policy and
Application Domain management supports only create and update functions. Remote
management does not support removing Application Domains or policies.
Table 25–32 describes these remote Application Domain management modes. Again,
command parameters include the mode, and an input
*Request.xml
file using a
relative path with respect to $OAM_REG_HOME, the preferred location for input
files):
./oamreg.sh <mode> <input_file> [prompt_flag] [component.oam.config_file] <mode>
value
Note: Application Domain removal is a manual task that must be
performed using the Oracle Access Management Console.
Table 25–32 Remote Policy Management Modes, Templates, and Flags
Mode and Template Description
policyCreate
$OAM_REG_HOME/input/
CreatePolicyRequest.xml
Allows Administrators to create Host Identifiers and an Application
Domain without registering an Agent.
./bin/oamreg.sh policyCreate input/myCreatePolicyRequest.xml
See Also: "About the Create Policy Request Template" on page 25-79
policyUpdate
$OAM_REG_HOME/input/
UpdatePolicyRequest.xml
Allows Administrators to update existing Host Identifiers and
Application Domain without updating an Agent.
./bin/oamreg.sh policyUpdate input/UpdatePolicyRequest.xml
See Also: "About the Update Policy Request Template" on page 25-80
Flag Optional
[prompt_flag] value: [-noprompt] When the optional -
noprompt
flag is used, oamreg can read input from
system.in by using echo and pipe to pass data.
Examples from $OAM_REG_HOME location:
(echo username; echo password; echo webgate_password;) |
./bin/oamreg.sh inband input/Request.xml -noprompt
component.oam.conf
(echo username; echo password; echo webgate_password; echo
httpscert_trust_prompt;) | ./bin/oamreg.sh inband
input/Request.xml -noprompt
(echo username; echo password; echo webgate_password; echo
cert_password;) | ./bin/oamreg.sh inband input/Request.xml
-noprompt
(echo username; echo password; echo webgate_password; echo
httpscert_trust_prompt; echo cert_password;) |
./bin/oamreg.sh inband input/Request.xml -noprompt
Understanding Remote Policy and Application Domain Management
Managing Policies to Protect Resources and Enable SSO 25-79
25.16.2 About the Create Policy Request Template
The
CreatePolicyRequest.xml
file with the remote
policyCreate
mode allows
Administrators to create Host Identifiers and an Application Domain without creating
or updating an agent registration.
■Create a Host Identifier add multiple
hostPortVariations
(host port pairs).
■Create an Application Domain.
■Add multiple protected, public, and excluded resources. Resources can be with or
without query strings, both are supported.
■Create default authentication and authorization policies for the resources that do
not require customized policies.
Many of the same parameters are found in the
CreatePolicyRequest.xml
file and the
expanded (full) Agent registration templates discussed earlier.
CreatePolicyRequest.xml
provides elements for Authentication and Authorization
Policies and resources (with no <agentName> element).
Some parameters in the
CreatePolicyRequest.xml
file are new and not included in
the full agent registration XML files, while certain elements in the original agent
registration file are used to create or update. However, some elements are The primary
differences of
CreatePolicyRequest.xml
are specific to:
component.oam.config_file Optional. Remote registration accepts a configuration file with a URI
list as an argument. component.oam.config_file defines the full path to
a file containing any number of protected or public URIs. Ensure that
the file uses the following syntax and format:
■At least one protected URI is required
■Only one product family is allowed per file
■Comments begin with '#'
■Keyword 'public_uris': list public URIs on separate lines after this
key word.
■Keyword 'protected_uris': list URIs to be protected on separate
lines after this key word
Note: You can configure the authentication scheme for a policyusing
the following format (the policy name and authentication scheme
name must be separated by a Tab character):
<Policy Name> 'tab' <Authentication Scheme Name>
For example:
########################
protected_uris
########################
protected policy1 Basic Over LDAP
/finance/protected1/**
/finance/protected2/**
protected policy2 Client Certificate
/finance/protected3/*.js,*.png,*.gif
########################
public_uris
########################
/finance/public
/finance/test1/public
Table 25–32 (Cont.) Remote Policy Management Modes, Templates, and Flags
Mode and Template Description
Understanding Remote Policy and Application Domain Management
25-80 Administrator's Guide for Oracle Access Management
■Elements for Authentication and Authorization Policies and resources are
provided
■No <agentName> element or related elements are provided
25.16.3 About the Update Policy Request Template
UpdatePolicyRequest.xml
and
CreatePolicyRequest.xml
are nearly identical. Both
provide the same elements, with the exception of the <
protectedAuthnScheme
>
element.
Using
UpdatePolicyRequest.xml
, Administrators can:
■Update a Host Identifier add multiple
hostPortVariations
(host port pairs)
■Update an Application Domain
■Add multiple protected, public, and excluded resources.(with or without query
strings).
■Update default authentication and authorization policies for the resources that do
not require customized policies
■Create customized policies that include:
■Policy display name
■Policy description
■Authentication scheme (Authentication policies only)
■A subset of resources to be associated with the policy
25.16.4 About Remote Policy Management and Templates
This section describes the unique remote management elements for Application
Domain management found in the
CreatePolicyRequest.xml
and
UpdatePolicyRequest.xml
files. These elements are described in Table 25–33.
See Also: "About Remote Policy Management and Templates" on
page 25-80
See Also: "About Remote Policy Management and Templates" on
page 25-80
See Also: Table 15–8, " Common Elements in Remote Registration
Requests" for a description of elements common to remote registration
and remote management.
Understanding Remote Policy and Application Domain Management
Managing Policies to Protect Resources and Enable SSO 25-81
Table 25–33 Remote Management Template Elements
Element Description Example
<rregAuthenticationPolicies>
<rregAuthenticationPolicy>
Specifies the name and description for
the Authentication Policy (to use when
creating a new policy or updating an
existing policy).
<rregAuthenticationPolicies>
<rregAuthenticationPolicy>
<name>AuthenticationPolicy1</name>
<description>Authentication policy
created using policyUpdate mode of
rreg tool</description>
.
.
</rregAuthenticationPolicy>
</rregAuthenticationPolicies>
<authnSchemeName>
Specifies the Authentication Scheme to
use in the Authentication Policy.
<rregAuthenticationPolicies>
.
.
authnSchemeName>LDAPScheme
</authnSchemeName>
.
.
</rregAuthenticationPolicy>
</rregAuthenticationPolicies>
<uriList> Identifies a resource that requires
authentication using the policy.
<rregAuthenticationPolicies>
.
.
<uriList>
- <uriResource>
<uri>/res1</uri>
<queryString />
</uriResource>
</uriList>
.
.
</rregAuthenticationPolicy>
</rregAuthenticationPolicies>
<rregAuthorizationPolicies>
<rregAuthorizationPolicy>
Specifies the name and description for
the Authorization Policy (to use when
creating it anew or updating an existing
policy).
<rregAuthorizationPolicies>
<rregAuthorizationPolicy>
<name>AuthorizationPolicy1</name>
<description>Authorization policy
created using policyUpdate mode of
rreg tool</description>
.
.
</rregAuthorizationPolicy>
</rregAuthorizationPolicies>
<uriList> Identifies a resource that requires
Authorization using the Authorization
Policy.
<rregAuthorizationPolicies>
.
.
<uriList>
- <uriResource>
<uri>/res1</uri>
<queryString />
</uriResource>
</uriList>
.
.
</rregAuthorizationPolicy>
</rregAuthorizationPolicies>
Managing Policies and Application Domains Remotely
25-82 Administrator's Guide for Oracle Access Management
25.17 Managing Policies and Application Domains Remotely
The following procedure describes how Administrators can create or update existing
policies remotely, without revising an agent's registration.
Prerequisites
Review About Managing Policies Remotely
To managing policies or an Application Domain remotely without an Agent
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. Copy the appropriate request template and develop your own policy-management
request (including any Application Domain revisions needed):
■Create Policy Request File
■Update Policy Request File
3. On the Agent host, run the following command with the appropriate mode and
your own *Request*.xml input file. For example:
policyCreate Mode:
./bin/oamreg.sh policyCreate input/myCreatePolicyRequest.xml
policyUpdate Mode:
./bin/oamreg.sh policyUpdate input/myUpdatePolicyRequest.xml
4. Provide the registration Administrator user name and password when asked.
5. Confirm success by reading on-screen messages, then use the Oracle Access
Management Console to manage the domain and policies:
agentUpdate process completed successfully!
Native Configuration File Location: "... created in output folder ...
"
The output folder is in the same location where RREG.tar.gz was expanded:
.../rreg/output/AgentName/
25.18 Defining an Application
Application is a new concept introduced in PS2. An Application contains:
■launch-url (that will be used by the end user of the application)
■icons, description and other meta-data that is used to display it in the Access
Portal (which is user facing)
The following Application types are supported:
■SSO Agent Application (protected by a WebGate)
■Federation Service Provider Partner Application (through Federation, launch a
third-party partner application)
■Form-Fill Application (Access Portal Application template based application)
The Application should have the configuration required to SSO enable it. However, for
PS2, only Form-Fill application and Federation SP applications have their
configuration in the Application. SSO applications have only the launch URL.
Additional functionality will be added in subsequent releases.
Defining an Application
Managing Policies to Protect Resources and Enable SSO 25-83
Note: Application registration will work only if ESSO is configured
and enabled. In order to register an Application, an ESSO IDS Profile
must be created because the Application's policy information is stored
in the ESSO directory store.
Defining an Application
25-84 Administrator's Guide for Oracle Access Management
26
Validating Connectivity and Policies Using the Access Tester 26-1
26
Validating Connectivity and Policies Using the
Access Tester
Oracle provides a portable, stand-alone Java application, Access Tester, which
simulates registered Agents connecting to OAM Servers. The scripted execution allows
for command-line processing. You can record and playback scripts and capture output
for different functions. Encrypted and multiple-server connections are supported.
IT professionals and Administrators can use the Access Tester to troubleshoot agent to
server connections in addition to on-the-fly testing of request and response semantics
and access policy designs.
This chapter introduces the Access Tester and how to use it in the following sections:
■Prerequisites
■Introduction to the Access Tester for Access Manager 11g
■Installing and Starting the Access Tester
■Introduction to the Access Tester Console and Navigation
■Testing Connectivity and Policies from the Access Tester Console
■Creating and Managing Test Cases and Scripts
■Evaluating Scripts, Log File, and Statistics
26.1 Prerequisites
Before you can perform tasks in this chapter:
■Ensure that the Oracle Access Management Console and OAM Server are running.
■Confirm the Application Domain and policies for one or more resources, as
described in Chapter 25.
26.2 Introduction to the Access Tester for Access Manager 11g
The Access Tester is a portable, stand-alone Java application that ships with Access
Manager 11g. The Access Tester provides a functional interface between an individual
IT professional or Administrator and the OAM Server.
IT professionals can use the Access Tester to verify connectivity and troubleshoot
problems with the physical deployment. Application Administrators can use the
Access Tester to perform a quick validation of policies. In this chapter, the term
"Administrator" represents any individual who is using the Access Tester.
Introduction to the Access Tester for Access Manager 11g
26-2 Administrator's Guide for Oracle Access Management
The Access Tester can be used from any computer having a network connection to the
OAM Server. Both a graphical user interface (known as the Tester Console in this
chapter) and a command-line interface are provided. Command line mode enables
complete automation of test script execution in single or multi-client mode
environments.
By appearing to be a real agent, the Access Tester helps with policy configuration
design and troubleshooting, and sometimes with troubleshooting OAM Server
responsiveness. When using the Access Tester, you must appear to be the real end
user; the Access Tester does not actually communicate with a real end user.
To use the Access Tester, you must understand and administer authentication and
authorization policies for an application or resource that is protected by Access
Manager.
The Access Tester enables you to:
■Configure a request to be sent to the OAM Server that emulates what a real agent
would send to the OAM Server in a real environment.
■Send your request to the OAM Server and receives a response that is the same as
the response that would received by a real Agent. The Access Tester uses the OAM
Access Protocol (OAP) API to send requests over the OAP channel to the OAM
Proxy running as part of the OAM Server. The OAM Server processes the request
and returns a response.
■Process and display the server response.
■Proceed in the manner a real agent would to handle the response. For example, if a
Webgate determines that a resource is protected by a certificate authentication
scheme, then it must obtain the end user's certificate from the http SSL connection.
In the case of a certificate authentication scheme, you must point the Access Tester
to a certificate to be used as the end user's credentials.
In addition to simulating the Agent while performing functions in the previous list,
the Access Tester enables you to:
■Review performance characteristics of intended policy changes
■Track the latency of authentication and authorization requests
■Stress test the OAM Server to establish low- and high-performance watermarks
relative to desired user loads, and to size back-end hardware
■Stress test the policy server by running multiple concurrent tests (multi-threaded
mode) with command-line mode only.
■Establish performance metrics and measuring on an ongoing basis to prove
desired outcomes
During basic operations, the Access Tester does not make any determination about the
Server response and whether it is a right or wrong response (for instance, whether or
not resource X is protected, or user Y is authorized to access resource X). When
operating the Access Tester, you must be aware of the policy configuration to
determine if a specific response is appropriate.
The Access Tester offers advanced functionality that enables you to group a number of
individual requests into a test script that can be sent to the OAM Server for processing.
The output of such a test run can be captured by the Access Tester and used to
compare against a similar document containing "known good" responses. In this way,
the Access Tester can be used for automated testing of policy configuration against
errant changes.
Introduction to the Access Tester for Access Manager 11g
Validating Connectivity and Policies Using the Access Tester 26-3
Additionally, the Access Tester provides a multi-threaded capability designed to stress
test the policy server. In the multi-threaded approach, you identify the number of
virtual test clients to connect to the policy server and the number of iterations that
each virtual client should execute a test script. This enables you to stress test the policy
server.
For more information, see the following topics in this chapter:
■About OAM Agent and Server Interoperability
■About Access Tester Security and Processing
■About Access Tester Modes and Administrator Interactions
26.2.1 About OAM Agent and Server Interoperability
The two primary types of actors in the OAM architecture are the policy servers (OAM
Servers) and OAM policy enforcement agents (Webgates or Access Clients). In the
security world, Agents represent the policy enforcement point (PEP), while OAM
Servers represent the policy decision point (PDP):
■The Agent plays the role of a gatekeeper to secure resources such as http-based
applications and manage all interactions with the user who is trying to access that
resource. This is accomplished according to access control policies maintained on
the policy server (OAM Server).
■The role of the OAM Server is to provide policy, identity, and session services to
the Agent to properly secure application resources, authenticate and authorize
users, and manage user sessions.
This core OAM product architecture revolves around the following exchanges, which
drive the interaction between the Agent and OAM Server. To expose inter-operability
and the key decision points, Figure 26–1 illustrates a typical OAM Agent and OAM
Server interaction during a user's request for a resource.
Introduction to the Access Tester for Access Manager 11g
26-4 Administrator's Guide for Oracle Access Management
Figure 26–1 OAM Agent (PEP) and OAM Server (PDP) Inter-operability
The following overview outlines the processing that occurs between OAM Agents and
OAM Servers. During testing, the Access Tester emulates the Agent and communicates
with the OAM Server while the Administrator emulates the end user.
Process overview: Interoperability between OAM Agents and OAM Servers
1. Establish server connectivity: The registered OAM Agent connects to the OAM
Server.
2. The user requests accesses to a resource.
3. Validate resource protection: The Agent forwards the request to the OAM Server
to determine if the resource is protected.
Protected: The OAM Server responds with the type of credentials required.
4. User credentials: Establishing the user identity enables tracking for Audit and SSO
purposes, and conveyance to the application. For this, the Agent prompts the user
for his credentials.
5. Authenticate user credentials: The Agent forwards the supplied user credentials to
the OAM Server for validation.
Authentication Success: The Agent forwards the resource request to the OAM
Server.
6. Authorize user access to a resource: The Agents must first determine if the user is
allowed to access the resource by forwarding the request for access to the OAM
Server for authorization policy evaluation.
7. The Agent grants or denies access based on the policy response.
Introduction to the Access Tester for Access Manager 11g
Validating Connectivity and Policies Using the Access Tester 26-5
26.2.2 About Access Tester Security and Processing
This topic provides information about secure communications, connections, storage,
input, logging, and Analysis.
Secure Communication: The Access Tester supports Open, Simple, or Cert connection
modes for communication with the OAM Server:
■Open mode: No security on the physical connection
■Simple mode: The physical connection is encrypted using built-in certificates. With
Simple mode, you are asked to enter the Global Pass Phrase that is configured for
the OAM Server.
■Cert mode: The physical connection is encrypted using a field-provided
certificates. Access Tester Cert Mode requires:
–Configuring the agent (either existing or new) for Cert mode communication.
–Obtaining certificates for the agent being emulated.
Access Tester Cert Mode requires two JKS key stores, created using the importcert tool
from the supplied PEM (BASE64-encoded ASCII) certificates: aaa_trust.pem, aaa_
key.pem, aaa_cert.pem:
■A Trust Store (file containing the JKS key store with the root CA certificate) is
required.
■A Key Store (file containing the JKS key store with the agent's private key and
certificate) is required.
■A Key Store Password is used to encrypt the Key Store with the agent certificates.
Connections: The Access Tester encrypts all password-type values that it saves to
configuration files and test cases. Access Tester validates whether the pool contains
valid connections. Cache flush requests are sent over an established connection (not an
out-of-band connection to delete the user session (to simulate logout) over OAP. Using
an already established connection can improve performance.
Persistent Storage: The Access Tester manages a number of data structures that
require persistent storage between Access Tester invocations. XML-file-based storage
is provided for the following types of information:
■Configuration data to minimize data entry between invocations of the application
(OamTestConfiguration)
■Test scripts consisting of captured test cases (OamTestScriptCase)
■Statistical data representing execution metric from a test run (OamTestStats)
XML Files for Input, Logging, and Analysis: The Access Tester uses a single XML
schema to define all the XML documents it generates. The following XML files are
produced when you run the Access Tester to process test scripts:
■Configuration Script: config.xml is the output file generated using the Save
Configuration command within the Access Tester. The name of this document is
See Also:
■Appendix C, "Securing Communication" for details about Simple
and Cert mode configuration for OAM Server and clients
(Webgates)
■"Introduction to the Access Tester Console and Navigation" on
page 26-12
Introduction to the Access Tester for Access Manager 11g
26-6 Administrator's Guide for Oracle Access Management
used within the input script to provide proper connection information to the
Access Tester running in command line mode. For details, see "About the Saved
Connection Configuration File" on page 26-32.
■Input Script: script.xml represents a script that is generated by the Access Tester
after capturing one or more test cases. For details, see "About the Generated Input
Test Script" on page 26-33.
■Target Output Script: oamtest_target.xml is generated by running the Access
Tester in command line mode and specifying the input script. For details, see
"About the Target Output File Containing Test Run Results" on page 26-34. For
example:
-Dscript.scriptfile="script.xml" -jar oamtest.jar
■Statistics: oamtest_stats.xml is generated together with the output script. For
details, see "About the Statistics Document" on page 26-36.
■Execution Log: lamtest_log.log is generated together with the output script. For
details, see "About the Execution Log" on page 26-38.
For more information, see "About Access Tester Modes and Administrator
Interactions".
26.2.3 About Access Tester Modes and Administrator Interactions
This topic describes modes, interactions, and the jar files needed to start and run the
Access Tester.
Console: The Access Tester provides a single window for interactions with the user.
All Access Tester operations are available in the main window, which performs as a
central dashboard where users can submit specific details for the test case and view
responses.
Command Line and Scripts: You can use the Access Tester command line and develop
test scripts, which you can run interactively or in batches for computerized execution
to maximize productivity and minimize costs and resources.
Startup and Run Time JAR Files: The Access Tester requires nap-api.jar in the same
directory as the main jar oamtest.jar, which is used to start the application.
Interactions: Regardless of the mode you choose for running the Access Tester, your
primary interactions with the Access Tester include:
■Issuing Requests and Reviewing Results
You use the Access Tester to issue requests to the OAM Server to validate resource
protection, policy configuration, user authentication, and user authorization. You
can immediately analyze test case results and also retain the data for longer-term
analysis, if needed.
■Managing Test Scripts
You can build test scripts by capturing the data generated by test execution, which
is available as stand-alone documents. You can run the test script for manual or
automated analysis. The Access Tester provides for some automated analysis after
each test run, while collecting full set of statistics to enable analysis after the fact.
■Managing OAM Server Connectivity
You can manage application settings that include server connection information.
Figure 26–2 depicts the flow of information during operations in both Console and
command-line modes. Details follow the figure. Advanced operations include building
and executing test scripts.
Introduction to the Access Tester for Access Manager 11g
Validating Connectivity and Policies Using the Access Tester 26-7
Figure 26–2 User Interactions with the Access Tester
Table 26–1 describes the process flow of information during both Tester Console mode
operations and command-line mode operations.
Note: Command-line mode enables complete automation of test
script execution in single or multi-client mode environments. The
Access Tester exposes a control mechanism to configure test runs
without having to change "known good" input test scripts which are
available in read-only mode.
Table 26–1 User Interactions: Tester Console Mode versus Command Line Mode Operations
Tester Console mode Command Line Mode
The user starts the Access Tester from the command line. The user or a shell script starts the Access Tester in command
line mode.
Cert mode for secure communication: The keystores are
specified in the OamTestConfiguration.xml file containing
previously saved configuration information.
The user opens a previously saved OamTestConfiguration.xml
file to populate the application fields and minimize data entry,
including server connection fields. Alternatively, the user can
use the Tester Console and enter data manually
The Access Tester starts processing test cases based on the
input script.
The user clicks the Connect button to open the connection with
the OAM Server.
The Access Tester opens a connection with the OAM Server
based on details in the input script.
Resource Protection: The user performs steps in a sequence to
validate resource protection, authenticate user credentials, and
authorize user access.
Resource Protection: The Access Tester starts processing test
cases based on the input script.
Installing and Starting the Access Tester
26-8 Administrator's Guide for Oracle Access Management
The following overview outlines the tasks involved with using the Access Tester, and
the topics where more information can be found in this chapter.
Task overview: Testing Access Manager connections and policies
1. Review the following topics:
■Installing and Starting the Access Tester
■Introduction to the Access Tester Console and Navigation
2. Perform and capture tests using the Access Tester Console as described in "Testing
Connectivity and Policies from the Access Tester Console"
3. Proceed to "Creating and Managing Test Cases and Scripts"
26.3 Installing and Starting the Access Tester
The Access Tester consists of two jar files that can be used from any computer, either
within or outside the WebLogic Server domain. This section describes how to install
the Access Tester, which involves copying the Access Tester jar files to a computer
from which you want to run tests. The Access Tester must be started from a command
line regardless of the mode you choose for test input: Tester Console mode or
command line mode. This section is divided into the following topics:
■Installing the Access Tester
■About Access Tester Supported System Properties
■Starting the Tester Without System Properties For Use in Tester Console Mode
■Starting the Access Tester with System Properties For Use in Command Line Mode
26.3.1 Installing the Access Tester
This topic describes how to install the Access Tester for use on any computer.
Following installation, the Access Tester is ready to use. No additional setup is
required.
To install the Access Tester
1. Ensure that the computer from which the tester will be run includes JDK/JRE 6.
For example, you can test for Java as follows:
java -version
The previous command returns the following information:
java version "1.6.0_18"
When the test completes, the Access Tester generates:
■A script with results
■A file with execution statistics including information
about mismatched responses
■A log file detailing processing flow
Once the script completes, the Access Tester generates:
■A script with results
■A file with execution statistics including information
about mismatched responses
■A log file detailing processing flow
The user repeats steps as needed to complete validation The user repeats steps as needed to complete validation.
In Cert mode, you will be prompted to identify the necessary
keystores.
In Cert mode, the keystores are specified in the XML file
containing previously saved configuration information.
Table 26–1 (Cont.) User Interactions: Tester Console Mode versus Command Line Mode Operations
Tester Console mode Command Line Mode
Installing and Starting the Access Tester
Validating Connectivity and Policies Using the Access Tester 26-9
Java(TM) SE Runtime Environment (build 1.6.0_18-b07)
Java HotSpot(TM) Client VM (build 16.0-b13, mixed mode)
2. On a computer hosting the OAM Server, locate and copy the Access Tester Jar files.
For example:
$ORACLE_HOME/oam/server/tester/oamtest.jar
$ORACLE_HOME/oam/server/tester/nap-api.jar
3. Store the jar file copies together in the same directory on any computer from
which you want to run the Access Tester.
4. Cert Mode: If the OAM Server communication mode is Cert, ensure that the
computer from which you will run the Access Tester includes the same keystores
that are defined on the agent registration page of the Oracle Access Management
Console. See Chapter 14.
5. Proceed as follows, depending on your environment and requirements:
■Starting the Tester Without System Properties For Use in Tester Console Mode
enables you to manually drive requests.
■Starting the Access Tester with System Properties For Use in Command Line
Mode
■Executing a Test Script enables you to use a test script that has been created
against a "Known Good" policy configuration and marked as "Known Good"
26.3.2 About Access Tester Supported System Properties
The Access Tester supports a number of configuration options that are used for
presentation or during certain aspects of testing. These options are specified at startup
using the Java-D mechanism, as shown in Table 26–2, which describes all supported
system properties.
Table 26–2 Access Tester Supported System Properties
Property
Access Tester
Mode Description and Command Syntax
log.traceconnfile Tester Console and
Command Line
modes
Logs connection details to the specified file
name.
-Dlog.traceconnfile="<file-name>"
display.fontname Tester Console
mode
Starts the Access Tester with the specified font.
This could be useful in compensating for
differences in display resolution.
- Ddisplay.fontname ="<font-name>"
display.fontsize Tester Console
mode
Starts the Access Tester with the specified font
size. This could be useful in compensating for
differences in display resolution.
- Ddisplay.fontsize ="<font-size>"
display.usesystem Tester Console
mode
Starts the Access Tester with the default font
name and size (Dialog font, size 10).
- Ddisplay.usesystem
script.scriptfile Command Line
mode
Runs the script <file-name> in command line
mode.
-Dscript.scriptfile="<file-name>"
Installing and Starting the Access Tester
26-10 Administrator's Guide for Oracle Access Management
26.3.3 Starting the Tester Without System Properties For Use in Tester Console Mode
To manually drive (and capture) requests and view real-time response through the
graphical user interface, start the tester in Tester Console mode. This procedure omits
all system properties, even though several can be used with Tester Console mode.
The jar file defines the class to be started by default; no class name need be specified.
Ensure that the nap-api.jar is present in the same directory as oamtest.jar.
control.configfile Command Line
mode
Overwrites script's "configfile" attribute
containing the absolute path to the
configuration XML file with the connection
information. The Access Tester uses the
configuration file to establish a connection to
the Policy Server indicated by Connection
element.
-Dcontrol.config="<file-name>"
control.testname Command Line
mode
Overwrites script's "testname" attribute of the
Control element containing a string
representing a name of the test series to be used
in naming output script, stats, and log files.
Output log files begin with <testname>_
<testnumber>.
-Dcontrol.testname="<String>"
control.testnumber Command Line
mode
Specifies the control number to be used in
naming output script, stats, and log files.
Output log files begin with <testname>_
<testnumber>.
-Dcontrol.testnumber="<String>".
Although the auto generated string is a 7 digit
number based on current local time (2 character
minutes + 2 character seconds + 3 character
hundredths), any string can be used to denote
the control number as long as it can be used in
a filename.
control.ignorecontent Command Line
mode
Overwrites script's "ignorecontent" attribute of
the Control element indicating the Access
Tester should ignore differences in Content
between the original test case and current
results.
-Dcontrol.testname="true|false"
control.displayiteration
stats
Command Line
mode
Controls whether or not to display intermediate
statistics after each iteration of the test run.
-Dcontrol.displayiterationstats="true|false"
control.loopback Command Line
mode
Runs the Access Tester in loopback mode to test
the Access Tester for internal regressions
against a known good script. Used for unit
testing the Access Tester.
-Dcontrol.loopback="true"
Table 26–2 (Cont.) Access Tester Supported System Properties
Property
Access Tester
Mode Description and Command Syntax
Installing and Starting the Access Tester
Validating Connectivity and Policies Using the Access Tester 26-11
To start the Access Tester in console mode without system properties
1. From the directory containing the Access Tester jar files, enter the following
command:
java -jar oamtest.jar
2. Use the -help option to list all the options available for the oamtest command-line
tool.
java -jar oamtest.jar -help
3. Proceed to one of the following topics for more information:
■Introduction to the Access Tester Console and Navigation
■Testing Connectivity and Policies from the Access Tester Console
■Creating and Managing Test Cases and Scripts
26.3.4 Starting the Access Tester with System Properties For Use in Command Line
Mode
This section is divided into the following topics:
■About the Access Tester Command Line Mode
■Starting the Tester Without System Properties For Use in Tester Console Mode
26.3.4.1 About the Access Tester Command Line Mode
To run a test script, or to customize Access Tester operations, you must start the tester
in command line mode and include system properties using the Java -D option.
When running in command line mode, the Access Tester returns completion codes that
can be used by shell scripts to manage test runs. When you run the Access Tester in
Console mode, you do not need to act upon codes that might be returned by the
Access Tester.
Shell scripts that wrap the Access Tester to execute specific test cases must be able to
recognize and act upon exit codes communicated by the Access Tester. In command
line mode, the Access Tester exits using System.Exit (N), where N can be one of the
following codes:
■0 indicates successful completion of all test cases with no mismatches. This also
includes a situation where no test cases are defined in the input script.
■3 indicates successful completion of all test cases with at least one mismatch.
■1 indicates that an error prevented the Access Tester from running or completing
test cases. This includes conditions such as No input script specified, Unable to
read the input script, Unable to establish server connection, Unable to generate the
target script.
See Also:
■"About Access Tester Supported System Properties"
■"Starting the Access Tester with System Properties For Use in
Command Line Mode"
See Also: "About Access Tester Supported System Properties" on
page 26-9
Introduction to the Access Tester Console and Navigation
26-12 Administrator's Guide for Oracle Access Management
These exit codes can be picked up by shell scripts ($? In Bourne shell) designed to
drive the Access Tester to execute specific test cases.
26.3.4.2 Starting the Access Tester with System Properties
Use the following procedure to start the Access Tester in command line mode and
specify any number of configuration options using the Java-D mechanism.
To start the Access Tester with system properties or for use in command line
mode
1. From the directory containing the Access Tester jar files, enter the command with
the appropriate system properties for your environment. For example:
java -Dscript.scriptfile="\tests\script.xml" -Dcontrol.ignorecontent="true"
-jar oamtest.jar
2. After startup, proceed to one of the following topics for more information:
■Testing Connectivity and Policies from the Access Tester Console
■Creating and Managing Test Cases and Scripts
26.4 Introduction to the Access Tester Console and Navigation
This section introduces the Access Tester Console, navigation, and controls.
Figure 26–3 shows the fixed-size Access Tester Console. This is the window through
which users can interact with the application if the Access Tester is started in Console
mode. The window can not be resized. Details follow the screen.
See Also: "About Access Tester Supported System Properties" on
page 26-9
Introduction to the Access Tester Console and Navigation
Validating Connectivity and Policies Using the Access Tester 26-13
Figure 26–3 Access Tester Console
At the top of the main window are the menu names within a menu bar. Under the
menu bar is the tool bar. All of the commands represented by buttons in the tool bar
are also available as menu commands.The Access Tester Console is divided into four
panels, described in Table 26–3.
Table 26–3 Access Tester Console Panels
Panel Name Description
Server Connection Provides fields for the information required to establish a connection to
the OAM Server (a single primary server and a single secondary server),
and the Connect button:
See also: "Establishing a Connection Between the Access Tester and the
OAM Server" on page 26-16.
Protected Resource URI Provides information about a resource whose protected status needs to
be validated. The Validate button is used to submit the Validate Resource
server request.
See also: "Validating Resource Protection from the Access Tester
Console" on page 26-18.
User Identity Provides information about a user whose credentials need to be
authenticated. The Authenticate button is used to submit the
Authenticate User server request.
See also: "Testing User Authentication from the Access Tester Console"
on page 26-20.
Status Messages Provides a scrollable status message area containing messages displayed
by the application in response to user gestures. The Authorize button is
used to submit the Authorize User server request.
See also: "Observing Request Latency" on page 26-24.
Introduction to the Access Tester Console and Navigation
26-14 Administrator's Guide for Oracle Access Management
Text fields support right-clicking to display the Edit menu and drag-and-drop
operations using the mouse and cursor.
There are four primary buttons through which you submit test requests to the OAM
Server. Each button acts as a trigger to initiate the named action described in
Table 26–4.
26.4.1 Access Tester Menus and Command Buttons
Table 26–5 identifies additional Access Tester Console buttons and their use. All
command buttons provide a tip when the cursor is on the button.
Table 26–4 Command Buttons in Access Tester Panels
Panel Button Description
Connect Submits connection information and initiates connecting.
Validate Submits information provided in the Protected Resource URI panel and initiates
validation of protection.
Authenticate Submits information provided in the User Identity panel and initiates
authentication confirmation.
Authorize Submits information provided in the User Identity panel and initiates
authorization confirmation.
See Also: "Access Tester Menus and Command Buttons"
Table 26–5 Additional Access Tester Buttons
Command Buttons Description
Open Folder Loads connection configuration details that were saved to an XML file
(config.xml, by default).
You can refresh the information in the Console by clicking this button.
Disk Saves connection configuration details to a file (default name,
config.xml). You can add the name of this document to the input script
to provide proper connection information to the Access Tester running
in command line mode.
The Save command button at the bottom of the Console saves the
content of the Status Message panel to a log file.
Eraser Clears fields on a panel containing the icon. Tool bar action clears all
fields except connection fields if the connection has already been
established.
Blue Up Arrows Captures the last named request to the capture queue with the
corresponding response received from the OAM Server. Together, the
request and response create a test case.
The capture queue status at the bottom of the Console is updated to
reflect the number of test cases in the queue.
You can save the contents of the capture queue to create a test script
containing multiple test cases using the Generate Script command on
the Test menu or a command button.
Paper Scroll Generates a test script that includes every test case currently in the
capture queue, and asks if the queue should be cleared. Do not clear
the queue until all your test cases have been captured and saved to a
test script.
Paper Scroll with right facing
arrow
Runs a test script against the current OAM Server. The Status message
window is populated with the execution status as the script
progresses through each test case.
Globe with right facing red arrow Imports a copied URI from the clipboard after parsing it to populate
fields in the URI panel.
Question Mark Displays a dialog showing the password in clear text
Testing Connectivity and Policies from the Access Tester Console
Validating Connectivity and Policies Using the Access Tester 26-15
The Access Tester provides the menus described in Table 26–6. All menu items have
mnemonics that are exposed by holding down the ALT key (on Windows systems).
There are also command accelerators (keyboard activation) available using the
CTRL-<KEY> combination defined for each menu command.
26.5 Testing Connectivity and Policies from the Access Tester Console
This section describes how to perform quick spot checks using the Access Tester in
Console mode with OAM Servers.
Spot checks or troubleshooting connections between the Agent and OAM Server can
help you assess whether the Agent can communicate with the OAM Server, which is
especially helpful after an upgrade or product migration. Spot checks or
troubleshooting resource protection that can be exercised by Agents and OAM Servers
can help you develop end-to-end tests of policy configuration during the application
lifecycle.
The following overview identifies the tasks and sequence to be performed and where
to locate additional information about each task.
Task overview: Performing spot checks from the Access Tester Console
1. Start the Access Tester, as described in "Installing and Starting the Access Tester"
on page 26-8.
Table 26–6 Access Tester Menus
Menu Title Menu Commands
File ■Open Configuration
■Save Configuration
■Exit
Note: To minimize the amount of data entry the Save Configuration and Open
Configuration menu (and tool bar command buttons) allow for specific Connection,
URI, and Identity information to be saved to (and read from) a file. Thus, it becomes
fairly simple to manage multiple configurations. Also, the configuration file can be
used as input to the Access Tester when you run it in command line mode and execute
a test script.
Edit Provides standard editing commands, which act on fields:
■Cut
■Copy
■Paste
■Clear all fields
■Import URI fields from a saved URL
Test ■Capture last "..." request (for example, Capture last "authorize" request)
■Save test script
■Run test script
Note: You can use functions here to capture the last request and response to create a
test case that you can save to a test script to be run at a later time.
Help The command About, which displays usage information.
Note: You can capture each request and response pair to create a test
case, and save the test cases to a script file that can be run later. For
details, see "Creating and Managing Test Cases and Scripts" on
page 26-24.
Testing Connectivity and Policies from the Access Tester Console
26-16 Administrator's Guide for Oracle Access Management
2. Add relevant details to the Server Connection panel and click Connect, as
described in "Establishing a Connection Between the Access Tester and the OAM
Server" on page 26-16.
3. Enter or import details into the Protected Resource URI pane and click Validate, as
described in "Validating Resource Protection from the Access Tester Console" on
page 26-18.
4. Add relevant details to the User Identity panel and click Authenticate, as
described in "Testing User Authentication from the Access Tester Console" on
page 26-20.
5. After successful authentication, click Authorize in the User Identity panel, as
described in "Testing User Authorization from the Access Tester Console" on
page 26-23.
6. Check the latency of requests, as described in "Observing Request Latency" on
page 26-24.
26.5.1 Establishing a Connection Between the Access Tester and the OAM Server
Before you can send a request to the OAM Server you must establish a connection
between the Access Tester and the server. This section describes how to establish that
connectivity.
■About the Connection Panel
■Connecting the Access Tester with the OAM Server
26.5.1.1 About the Connection Panel
You enter required information for the OAM Server and the Agent you are emulating
in the Access Tester Connection panel and then click the Connect button. The Tester
initiates the connection, and displays the status in the Status Messages panel. Once the
connection is established, it is used for all further operations.
Figure 26–4 illustrates the Server Connection panel and controls. This panel contains
information needed to establish a connection to the OAM Server's Proxy port.
Figure 26–4 Server Connection Panel in the Access Tester
Table 26–7 describes the information needed to establish the connection. The source of
your values is the Oracle Access Management Console, System Configuration tab.
Caution: Once the connection is established, it cannot be changed
until you restart the Access Tester Console.
Testing Connectivity and Policies from the Access Tester Console
Validating Connectivity and Policies Using the Access Tester 26-17
After entering information and establishing a connection, you can save details to a
configuration file that can be re-used later.
Table 26–7 Connection Panel Information
Fields Description
IP Address The IP Address of the Primary and Secondary OAM Proxy listens on
for this set of tests.
Note: Oracle recommends that you enter values for only the Primary
OAM Proxy. The Secondary OAM Proxy is needed only if you want to
test failover between the primary and secondary OAM Server.
However, a more practical use of the Secondary Server is reserved for
later use, when the OAP API supports load balancing between
Primary and Secondary OAM Server.
Port Enter the port number of the Primary and Secondary OAM Server.
Max Conn The maximum number of physical connection (TCP) sockets the
Access Tester will use. Access Tester emulates a single threaded Agent.
Note: Oracle recommends that you accept the default value, 1.
Min Conn The minimum number of physical connection (TCP) sockets the Access
Tester will use. The Access Tester emulates a single threaded Agent.
Note: Oracle recommends that you accept the default value, 1.
Timeout The number of milliseconds the Access Tester should wait for the
connection to be established or to receive a response from the OAM
Server.
Note: Oracle recommends that you accept the default value.
Mode The level of communication security that is designated for the Agent to
be emulated.
■Open--No special configuration needed for this mode.
■Simple--Presents a field for the global pass phrase set for the
OAM Server. See Also: "Retrieving the Global Passphrase for
Simple Mode" on page C-14.
■Cert--Presents a Configure Certs ... button that opens a dialog
asking for the following:
Trust Store (Root Store Alias): A file containing the JKS key store
with the root CA certificate.
Key Store: A file containing the JKS key store with the agent's
private key and certificate. Currently, the agent certificate is used
for encrypting the connection and not the agent identification.
Key Store Password: The password used to encrypt the Key Store
with the agent certificates.
See Also: "About Access Tester Security and Processing" on page 26-5,
and "Generating Client Keystores for OAM Tester in Cert Mode" on
page C-5.
Agent ID Enter the identity of the OAM Agent the Tester is simulating.
Agent Password Enter the password for the OAM Agent the Tester is simulating, if
there is one configured.
Question Mark Click ? beside the Agent Password field for help.
Green Check Mark The green check mark beside the Connect button indicates a "Yes"
response; the connection is made. The Status Messages panel also
indicates a "Yes" response for the connection.
X in red circle The red circle beside the Connect button indicates a "No" response; no
connection exists. The Status Messages panel also indicates a "No"
response for the connection.
See Also: "Establishing a Connection Between the Access Tester and
the OAM Server"
Testing Connectivity and Policies from the Access Tester Console
26-18 Administrator's Guide for Oracle Access Management
26.5.1.2 Connecting the Access Tester with the OAM Server
Use the following procedure to submit your connection details for the OAM Server.
Prerequisites
Installing and Starting the Access Tester
To test connectivity between the Access Tester and the OAM Server
1. Start the Access Tester, as described in "Installing and Starting the Access Tester"
on page 26-8.
2. In the Server Connection Panel (Table 26–7), enter:
■Primary and secondary OAM Proxy details
■Timeout period
■Communication encryption mode
■Agent details
3. Click the Connect button.
4. Beside the Connect button, look for the green check mark indicating the
connection is established.
5. In the Status Messages panel, verify a Yes response.
Not Successful: If there is a problem connecting to the OAM Server, ensure that
you entered all connection information correctly (IP address and port, Agent name
and password, connection mode and related certificates and passwords, as
needed).
If the connection still cannot be made, start the Access Tester Console using the
Trace Connection command mode and look for additional details in the connection
log. Also, ask the Administrator of the OAM Server to review the policy server
log.
26.5.2 Validating Resource Protection from the Access Tester Console
Before a user can access a resource, the Agent must first validate that the resource is
protected. Using the Access Tester, you can act as the Agent to have the OAM Server
validate whether or not the given URI is protected and communicate the response to
the Access Tester, as described here.
■About the Protected Resource URI Panel
■Validating Resource Protection
26.5.2.1 About the Protected Resource URI Panel
You must enter required information for the resource you want to validate in the
Access Tester Protected Resource URI panel, and then click the Validate button.
Note: Cert mode requires the presence of keystores generated as
described in Appendix C, "Securing Communication"
See Also: "About the Connection Panel"
Testing Connectivity and Policies from the Access Tester Console
Validating Connectivity and Policies Using the Access Tester 26-19
To minimize data entry, you can import long URIs that you have copied from a
browser and then click the Import URI command button. The Tester parses the URI
saved to the clipboard and populates the URI fields in the Access Tester.
Figure 26–5 illustrates the panel where you enter the URI details to validate that the
resource is protected. When combined, the URI fields follow RFC notation. For
example:
http://oam_server1:7777/index.html
.
Figure 26–5 Protected Resource URI Panel in the Access Tester
Table 26–8 describes the information needed to perform this validation.
Table 26–8 Protected Resource URI Panel Fields and Controls
Field or Control Description
Scheme Enter http or https, depending on the communication security
specified for the resource.
Note: The Access Tester supports only http or https resources.
You cannot use the Access Tester to test policies that protect
custom non-http resources.
Host Enter a valid host name for the resource.
Note: Your <host:port> combination specified in the Access
Tester must match one of the Host Identifiers defined in the
Oracle Access Management Console. If the host identifier is
not recognized, OAM cannot validate resource protection.
Port Enter a valid port for the URI.
Note: The <host:port> combination specified in the Access
Tester must match one of the Host Identifiers as defined in the
OAM Server. If the host identifier is not recognized, OAM
cannot validate resource protection.
Resource Enter the Resource component of the URI (/index.htm in the
example). This resource should match a resource defined for
an authentication and authorization policy in the Oracle
Access Management Console.
Note: If protected, the resource identifier that you provide
here must match the one specified in an authorization policy
in the Oracle Access Management Console.
Globe with red arrow Click this button to parse and import a URI that is saved on a
clipboard.
Operation Select the operational component of the URI from the list
provided in the Access Tester. The OAM Server does not
distinguish between different actions, however. Therefore,
leaving this set to Get should suffice.
Get Auth Scheme Check this box to request the OAM Server to return details
about the Authentication Scheme that is used to secure the
protected resource. If the URI is protected, this information is
displayed in the Status Messages panel.
Validate Click the Validate button to submit the request to the OAM
Server. When the response is received, the Access Tester
displays it in the Status Messages panel.
Testing Connectivity and Policies from the Access Tester Console
26-20 Administrator's Guide for Oracle Access Management
You can capture each request and response pair to create a test case, and save multiple
test cases to a script file that can be run later.
26.5.2.2 Validating Resource Protection
Use the following procedure to submit your resource information to the OAM Server
and verify responses in the Status Messages panel.
Prerequisites
Establishing a Connection Between the Access Tester and the OAM Server
To confirm that a resource is protected
1. In the Access Tester Protected Resource URI panel, enter or import your own
resource information (Table 26–8).
2. Click the Validate button to submit the request.
3. Review Access Tester output, including the relevant data about the resource such
as how the resource is protected, level of protection, and so on.
4. Beside the Validate button, look for the green check mark indicating the resource is
protected.
5. In the Status Messages panel, verify the redirect URL, authentication scheme, and
that credentials are expected.
6. Capture the request and response to create a test case for use later, as described in
"Creating and Managing Test Cases and Scripts" on page 26-24.
7. Retain the URI to minimize data entry and server processing using one of the
following methods.
8. Proceed to "Testing User Authentication from the Access Tester Console"
26.5.3 Testing User Authentication from the Access Tester Console
This topic provides the following information:
■About the User Identity Panel
Green Check Mark A green check mark appearing beside the Validate button
indicates a "Yes" response; the resource is protected. The Status
Messages panel provides the redirect URL for the resource and
that credentials are expected.
Note: If you checked the Get Auth Scheme box, the name and
level of the Authentication Scheme that protects this resource
are also provided in the Status Messages panel.
X in red circle A red circle appearing beside the Validate button indicates that
the resource is not protected. A No response will also appear
in the Status Messages.
See Also:
■"Validating Resource Protection from the Access Tester Console"
■"Creating and Managing Test Cases and Scripts" on page 26-24
See Also: "About the Protected Resource URI Panel"
Table 26–8 (Cont.) Protected Resource URI Panel Fields and Controls
Field or Control Description
Testing Connectivity and Policies from the Access Tester Console
Validating Connectivity and Policies Using the Access Tester 26-21
■Testing User Credential Authentication
26.5.3.1 About the User Identity Panel
Before a user can access a resource, the Agent must validate the user's identity based
on the defined authentication policy on the OAM Server. Using the Access Tester, you
can act as the Agent to have the OAM Server authenticate a specific userID for the
protected resource. All relevant authentication responses are considered during this
policy evaluation.
Figure 26–6 illustrates the Access Tester panel where you enter the information needed
to test authentication.
Figure 26–6 Access Tester User Identity Panel
Table 26–9 describes the information you must provide.
Table 26–9 Access Tester User Identity Panel Fields and Controls
Field or Control Description
IP Address Enter the IP Address of the user whose credentials are being validated. All
Agents communicating with the OAM Server send the IP address of the
end user.
Default: The IP address that is filled in belongs to the computer from which
the Access Tester is run.
To test a policy that requires a real user IP address, replace the default IP
address with the real IP address.
User Name Enter the userID of the individual whose credentials are being validated.
Note: The Access Tester enables or disables the username and password
fields if the resource is protected by an authentication scheme that requires
those credentials. Similarly the Access Tester enables or disables the
certificate field if the resource is protected by an authentication scheme that
requires a user's X509 certificate.
Password Enter the password of the individual whose credentials are being
validated.
? Click this button to display the password in clear text within a popup
window.
User Certificate Store The PEM format file containing the X.509 certificate of the user whose
credentials should be authenticated.
If the URI is protected by the X509 Authentication Scheme then the Tester
will use the PEM-formatted X509 certificate as a credential instead of or in
addition to the username/password. The X509 cert may also be used for
authorization if security policies are so configured on the OAM Server.
Note: For certificate-based authentication to work, the OAM Server must
be properly configured with root CA certificates and SSL keystore
certificates. See Appendix C for details about securing communication
between OAM Servers and Webgates.
... Click this button to browse the file system for the user certificate store path.
Testing Connectivity and Policies from the Access Tester Console
26-22 Administrator's Guide for Oracle Access Management
You can capture each request and response pair to create a test case, and save multiple
test cases to a script file that can be run later.
26.5.3.2 Testing User Credential Authentication
Use the following procedure to submit the end user credentials to the OAM Server and
verify authentication. All relevant authentication responses are considered during this
policy evaluation.
Prerequisites
Validating Resource Protection from the Access Tester Console with URI information
retained in the Console.
To test user credential authentication
1. In the Access Tester User Identity panel, enter information for the user to be
authenticated (Table 26–9).
2. Click the Authenticate button to submit the request.
3. Beside the Authenticate button, look for the green check mark indicating the user
is authenticated.
Authenticate Click the Authenticate button to submit the request to the OAM Server and
look for a response in the Status Messages panel.
Note: The type of credentials supplied (username/password or X.509
certificate) must match the requirements of the authentication scheme that
protects the URI.
Note: For certificate-based authentication, the OAM Server deployment
must be properly configured with certificates as described in Appendix C.
Authorize After the user's credentials are validated, you can click the Authorize
button to submit the request for the resource to the OAM Server. Check the
Status Messages panel for a response.
This request submits information collected in the URI and Identity panels
to the OAM Server to decide if the user defined on the Identity panel can
access the resource defined on the URI panel. The server returns Yes (user
can access the resource) or No (user can not access the resource). The OAM
Server might return additional information such as actions (responses) that
the real Agent would normally handle.
Green Check Mark A green check mark appearing beside the Authenticate button indicates
authentication success; The Status Messages panel also indicates "yes"
authentication was successful, and provides the user DN and session id.
A green check mark appearing beside the Authorize button indicates
authorization success; The Status Messages panel also indicates "yes"
authorization was successful, and provides Application Domain details.
X in red circle A red circle appearing beside the Authenticate button indicates
authentication failure; The Status Messages panel also indicates "no"
authentication was not successful.
A red circle appearing beside the Authorize button indicates authorization
failure; The Status Messages panel also indicates "no" authorization was
not successful.
See Also:
■"Testing User Authentication from the Access Tester Console"
■"Creating and Managing Test Cases and Scripts" on page 26-24
See Also: "About the User Identity Panel"
Table 26–9 (Cont.) Access Tester User Identity Panel Fields and Controls
Field or Control Description
Testing Connectivity and Policies from the Access Tester Console
Validating Connectivity and Policies Using the Access Tester 26-23
Not Successful: Confirm that you entered the correct userID and password and
try again. Also, check the Oracle Access Management Console for an active user
session that you might need to end, as described in Chapter 16.
4. Capture the request and response to create a test case for use later, as described in
"Creating and Managing Test Cases and Scripts" on page 26-24.
5. Retain the URI and user identity information and proceed to "Testing User
Authorization from the Access Tester Console".
26.5.4 Testing User Authorization from the Access Tester Console
Before a user can access a resource, the Agent must validate the user's permissions
based on defined policies on the OAM Server. Using the Access Tester, you can act as
the Agent to have the OAM Server validate whether or not the authenticated user
identity can be authorized to access the resource.
Use the following procedure to verify the authenticated end user's authorization for
the resource. All relevant authorization conditions and responses are considered
during this policy evaluation.
Prerequisites
Testing User Authentication from the Access Tester Console with all information
retained in the Console.
To test user authorization
1. In the Access Tester User Identity panel, confirm the user is authenticated
(Table 26–9).
2. In the Access Tester User Identity panel, click the Authorization button.
3. Beside the Authorization button, look for the green check mark indicating the user
is authorized.
Not Successful: Confirm the authorization policy using the Oracle Access
Management Console.
4. In the Status Messages panel (or execution log file), verify details about the test
run.
5. Capture the request and response to create a test case for use later, as described in
"Creating and Managing Test Cases and Scripts" on page 26-24.
6. Proceed to:
■Observing Request Latency
■Creating and Managing Test Cases and Scripts
■Evaluating Scripts, Log File, and Statistics
See Also: "About the User Identity Panel"
Note: Once the protected resource URI is confirmed and the user's
identity is authenticated from the Access Tester, no further
information is needed. You simply click the Authorize button to
submit the request. However, if the resource is changed to another you
must start the sequence anew and validate, then authenticate, and
then authorize.
Creating and Managing Test Cases and Scripts
26-24 Administrator's Guide for Oracle Access Management
26.5.5 Observing Request Latency
To understand OAM Server performance you must know how well the OAM Server
handles requests passed by the Agent. While there are many ways to expose a server's
metrics, it is sometimes useful to expose server performance from the standpoint of the
Agent. Using the Access Tester, you can do just that as described here.
Prerequisites
"Installing and Starting the Access Tester" on page 26-8
Task overview: Observing request latency includes
1. "Validating Resource Protection" on page 26-20
2. "Testing User Authentication from the Access Tester Console" on page 26-20
3. "Testing User Authorization from the Access Tester Console" on page 26-23
4. Check latency information in the execution log file as shown here, as well as in
other files generated during a test run. For example:
...
[2/3/12 11:03 PM][info] Summary statistics
[2/3/12 11:03 PM][info] Matched 4 of 4, avg latency 232ms vs 238ms
[2/3/12 11:03 PM][info] Validate: matched 2 of 2, avg latency 570ms vs 578ms
[2/3/12 11:03 PM][info] Authenticate: matched 1 of 1, avg latency 187ms vs
187ms
[2/3/12 11:03 PM][info] Authorize: matched 1 of 1, avg latency 172ms vs 188ms
...
5. Proceed to:
■Creating and Managing Test Cases and Scripts
■Evaluating Scripts, Log File, and Statistics
26.6 Creating and Managing Test Cases and Scripts
Test management refers to the creation of repeatable tests that can be executed at any
time by an individual Administrator or system. Quick spot checks are very useful and
effective in troubleshooting current issues. However, a more predictable and
repeatable approach to validating server and policy configuration is often necessary.
This approach can include testing OAM Server configuration for regressions after a
product revision, or during a policy development and QA cycle.
To be useful such tests must allow for multiple use cases to be executed as group. Once
the test scripts have been designed and validated as correct, replaying the tests against
the OAM Server helps identify regressions in a policy configuration.
This section provides the information you need to perform test management in the
following topics:
■About Test Cases and Test Scripts
■Capturing Test Cases
■Generating an Input Test Script
■Personalizing an Input Test Script
■Executing a Test Script
Creating and Managing Test Cases and Scripts
Validating Connectivity and Policies Using the Access Tester 26-25
26.6.1 About Test Cases and Test Scripts
A test case is created from the request sent to, and response data received from, the
OAM Server using the Access Tester. Among other data elements, a test case includes
request latency and other identifying information that enables analysis and
comparison of old and new test cases.
Once captured, the test case can be replayed without new input, and then new results
can be compared with old results. If the old results are marked as "known good" then
deviations from those results constitute failed test cases.
The test case workflow is illustrated by Figure 26–7.
Figure 26–7 Test Case Workflow
Task overview: Creating and managing a test case
From the Access Tester Console, you can connect to the OAM Server and manually
conduct individual tests. You can save the request to the capture queue after a request
is sent and the response is received from the OAM Server. You can continue capturing
additional test cases before generating a test script and clearing the capture queue. If
you exit the Access Tester before saving the capture queue, you are asked if the test
cases should be saved to a script before exiting. Oracle recommends that you do not
clear the queue until all your test cases have been captured.
Once you have the test script, you can run it from either the Access Tester Console or
from the command line.
26.6.2 Capturing Test Cases
You can save each test case to a capture queue after sending the request from the
Access Tester to the OAM Server and receiving the response. You can capture as many
individual test cases as you need before generating a test script that will automate
running the group of test cases. For instance, the following outlines three test cases
that must be captured individually:
■A validation request and response
■An authentication request and response
Creating and Managing Test Cases and Scripts
26-26 Administrator's Guide for Oracle Access Management
■An authorization request and response
Table 26–10 describes the location of the capture options.
If you exit the Access Tester before saving the capture queue, you are asked if the test
cases should be saved to a script before exiting. Do not clear the Access Tester capture
queue until all your test cases have been captured.
To capture one or more test cases
1. Initiate a request from the Access Tester Console, as described in "Testing
Connectivity and Policies from the Access Tester Console" on page 26-15.
2. After receiving the response, click the Capture last "..." request command button in
the tool bar (or choose it from the Test menu).
3. Confirm the capture in the Status Messages panel and note the Capture Queue test
case count at the bottom of the Console.
4. Repeat steps 1, 2, and 3 to capture in the queue each test case that you need for
your test script.
5. Proceed to "Generating an Input Test Script".
26.6.3 Generating an Input Test Script
A test script is a collection of individual test cases that were captured using the Access
Tester Console. When individual test cases are grouped together, it becomes possible
to automate test coverage to validate policy configuration for a specific application or
site.
You can create a test script to be used as input to the Access Tester and drive
automated processing of multiple test cases. The Generate Script option enables you to
create an XML file test script and clear the capture queue. If you exit the Access Tester
before saving the capture queue, you are asked if the test cases should be saved to a
script before exiting.
26.6.3.1 About Generating an Input Test Script
You can create a test script to be used as input to the Access Tester and drive
automated processing of multiple test cases. Such a script must follow these rules:
■Allows possible replay by a person or system
■Allows possible replay against different policy servers w/o changing the script, to
enable sharing of test scripts to drive different Policy Servers
Table 26–10 Access Tester Capture Request Options
Location Description
Test menu
Capture last "..." request
Select this command from the Test menu to add the last request
issued and results received to the capture queue (for inclusion
in a test script later).
Blue up arrow Select this command button from the tool bar to add the last
request issued and results received to the capture queue (for
inclusion in a test script later).
Note: Do not clear the capture queue until you have captured all the
test cases you want to include in the script.
Creating and Managing Test Cases and Scripts
Validating Connectivity and Policies Using the Access Tester 26-27
■Allows comparison of test execution results against "Known Good" results
Following are the locations of the Generate Script command.
26.6.3.2 Generating an Input Test Script
Prerequisites
Capturing Test Cases
To record a test script containing captured test cases
1. Perform and capture each request that you want in the script, as described in
"Capturing Test Cases" on page 26-25.
2. Click the Generate Script command button in the tool bar (or choose it from the
Test menu to include all captured test cases.
3. In the new dialog box, select or enter the name of your new XML script file and
then click Save.
4. Click Yes to overwrite an existing file (or No to dismiss the window and give the
file a new name).
5. In the Save Waning dialog box, click No to retain the capture queue and continue
adding test cases to your script (or click Yes to clear the queue of all test cases).
6. Confirm the location of the test script before you exit the Access Tester.
7. Personalize the test script to include details such as who, when, and why the script
was developed, as described next.
26.6.4 Personalizing an Input Test Script
This section describes how to personalize and customize a test script.
■About Customizing a Test Script
■Customizing a Test Script
26.6.4.1 About Customizing a Test Script
The control block of a test script is used to tag the script and specify information to be
used during the execution of a test. You might want to include details about who
created the script and when and why the script was created. You might also want to
customize the script using one or more control parameters.
The Access Tester provides command line "control" parameters to change processing
of the script without changing the script. (test name, test number, and so on). This
enables you to configure test runs without having to change "known good" input test
scripts. Table 26–12 describes the control elements and how to customize these.
Table 26–11 Generate Script Command
Location of the Command Description
Test menu
Generate Script
Select Generate Script from the Test menu to initiate creation of the
script containing your captured test cases.
Paper Script Scroll Select the Generate Script command button from the tool bar to
initiate creation of the script containing your captured test cases. After
you specify or select a name for your script, you are asked if the
capture queue should be cleared. Do not clear the capture queue until
all your test cases are saved to a script.
Creating and Managing Test Cases and Scripts
26-28 Administrator's Guide for Oracle Access Management
26.6.4.2 Customizing a Test Script
Prerequisites
Generating an Input Test Script
To customize a test script
1. Locate and open the test script that was generated by the Access Tester.
2. Add any details that you need to customize or personalize the script.
3. Save the file and proceed to "Executing a Test Script".
26.6.5 Executing a Test Script
Once a test script has been created against a "Known Good" policy configuration and
marked as "Known Good", it is important to drive the Access Tester using the script
rather than specifying each test manually using the Console. This section provides the
following topics:
■About Test Script Execution
■Running a Test Script
Table 26–12 Test Script Control Parameters
Control Parameter Description
i
gnorecontent=true
Ignores differences in the Content section of the use case when
comparing the original OAM Server response to the current response.
The default is to compare the Content sections. This parameter can be
overwritten by a command line property when running in the command
line mode.
Default: false (Compare Content sections).
Values: true or false
In command line mode, use ignorecontent=true to over ride the specified
value in the Control section of the input script.
testname="oamtest" Specifies a prefix to add to file names in the "results bundle" as described
in the previous section.
In command line mode, use Testname=name to over ride the specified
value in the Control section.
configfile="config.xml" Specifies the absolute path to a configuration XML file that was
previously created by the Access Tester.
In command line mode, this file is used by the Access Tester to locate
connection details to establish a server connection.
numthreads="1" Indicates the number of threads (virtual clients) that will be started by
the Access Tester to run multiple copies of the test script. Each thread
opens its own pool of connections to the policy server. This feature is
designed for stress testing the Policy Server, and is available only in
command line mode.
Default: 1
Note that when running a test script in GUI mode, the number of threads
is ignored and only one thread is started to perform a single iteration of
the test script.
numiterations="1" Indicates the number of iterations that will be performed by the Access
Tester. This feature is designed for stress testing and longevity testing the
Policy Server and is available only in command line mode.
Default: 1
Creating and Managing Test Cases and Scripts
Validating Connectivity and Policies Using the Access Tester 26-29
26.6.5.1 About Test Script Execution
You can interactively execute tests scripts from within the Access Tester Console, or
use automated test runs performed by command scripts. Automated test runs can be
scheduled by the operating system or a harness such as Apache JMeter, and executed
without manual intervention. Other than lack of human input in command line mode,
the two execution modes are identical.
Table 26–13 describes the commands to execute a test script.
The following overview describes how the Access Tester operates when running a test.
Other than lack of human input in command line mode, the two execution modes are
identical.
Process overview: Access Tester behavior when running a test script
1. The Access Tester loads the input xml file.
In command line mode, the Access Tester opens the configuration XML file
defined within the input test script's Control element.
2. The Access Tester connects to the primary and secondary OAM Proxy using
information in the Server Connection panel of the Console.
In command line mode, the Access Tester uses information in the Connection
element of the configuration XML file.
3. In command line mode, the Access Tester checks the Control elements in the input
script XML file to ensure none have been overwritten on the command line
(command line values take precedence).
4. For each original test case defined in the script, the Access Tester:
a. Creates a new target test case.
b. Sends the original request to the OAM Server and collects the response.
c. Makes the following comparisons:
Compares the new response to the original response.
Note: A script such as .bat (Windows) or .sh (Unix) executes a test
script in command line mode. Once a test script is created, it can be
executed using either the Run Script menu command or the Access
Tester command line.
Table 26–13 Run Test Script Commands
Location Description
Test menu
Run Script
Select the Run Script command from the Test menu to begin
running a saved test script against the current policy server.
The Status message panel is populated with the execution
status as the script progresses.
Paper Script Scroll with green
arrow
Select the Run Script command button from the tool bar to
begin running a saved test script against the current policy
server. The Status message panel is populated with the
execution status as the script progresses.
Command line mode A script such as .bat (Windows) or .sh (Unix) executes a test
script in command line mode. Once a test script is created, it
can be executed using either the Run Script menu command or
the Access Tester command line.
Creating and Managing Test Cases and Scripts
26-30 Administrator's Guide for Oracle Access Management
Compares response codes and marks as "mismatched" any new target test case
where response codes differ from the original test case. For instance, if the
original Validate returned "Yes", and now returns "No", a mismatch is marked.
When response codes are identical, and "the ignorecontent" control parameter
is "false", the Access Tester compares Content (the name of the Authentication
scheme or post authorization actions that are logged after each request). If
Content sections differ, the new target test case is marked "mismatched".
d. Collect new elapsed time and store it in the target use case.
e. Build a new target test case containing the full state of the last server request
and the same unique ID (UUID) as the original test case.
f. Update the internal statistics table with statistics for the target test case
(request type, elapsed time, mismatched, and so on).
5. After completing all the input test cases, the Access Tester:
a. Displays summary results.
b. Obtains and combines the testname and testnumber, and generates a name for
the "results bundle" (three files whose names start with <testname>_
<testnumber>.
Obtain testname from the command line parameter. If not specified in the
command line, use the testname element of the input script's Control block.
Obtain testnumber from the command line parameter. If not specified,
testnumber defaults to a 7-character numeric string based on the current local
time: 2 character minutes, 2 character seconds, 3 character hundredths.
c. Generates the "results bundle": three files whose names start with <testname>_
<testnumber>:
The target XML script contains the new test cases: <testname>_<testnumber_
results.xml.
The statistics XML file contains a summary and detailed statistics of the entire
test run, plus those test cases marked as "mismatched": <testname>_
<testnumber_stats.xml
The execution log file contains information from the Status Message panel:
<testname>_<testnumber_log.log.
d. When running in multi-threaded mode, only the statistics XML file and
execution log file will be generated.
e. In command line mode, the Access Tester exits with the exit code as described
in "About the Access Tester Command Line Mode" on page 26-11.
26.6.5.2 Running a Test Script
Prerequisites
Generating an Input Test Script
Note: Shell scripts can automate generating the bundle by providing
testname and testnumber command line parameters.
Evaluating Scripts, Log File, and Statistics
Validating Connectivity and Policies Using the Access Tester 26-31
To run a test script
1. Confirm the location of the saved test script before exiting the Access Tester., as
described in "Generating an Input Test Script" on page 26-26.
2. Submit the test script for processing using one of the following methods:
■From the Access Tester Console, click the Run Script command button in the
tool bar (or select Run Script from the Test menu), then follow the prompts
and observe messages in the Status Message panel as the script executes.
■From the command line, specify your test script with the desired system
properties, as described in "Starting the Access Tester with System Properties
For Use in Command Line Mode" on page 26-11.
java -Dscript.scriptfile="\tests\script.xml" -Dcontrol.ignorecontent="true"
-jar oamtest.jar
3. Review the log and output files and perform additional analysis after the Access
Tester compares newly generated results with results captured in the input script,
as described in "Evaluating Scripts, Log File, and Statistics".
26.7 Evaluating Scripts, Log File, and Statistics
This section provides the following information:
■About Evaluating Test Results
■About the Saved Connection Configuration File
■About the Generated Input Test Script
■About the Target Output File Containing Test Run Results
■About the Statistics Document
■About the Execution Log
26.7.1 About Evaluating Test Results
At the end of a test run a "results bundle" gets generated containing three documents:
■Target script: An XML document containing new test cases
■Execution log: A text file containing the messages displayed during script
execution
■Execution statistics: An XML document containing test metrics and a list of
mismatched elements
The matching pair of test cases in the original and target scripts shares the test case ID.
This ID is represented by a UUID value, which makes it possible to compare
individual test cases in the original script with those in the target script. For more
information, see "About the Generated Input Test Script" on page 26-33.
The statistics document contains the summary and detail statistics, as well as a list of
test cases that did not match. The detailed statistics can be used for further analysis or
to keep a historical trail of results. The summary statistics are the same statistics
displayed at the end of the test run and can be used to quickly assess the state of a test
Note: The target script is not created if the Access Tester is
configured to run in multi-threaded mode.
Evaluating Scripts, Log File, and Statistics
26-32 Administrator's Guide for Oracle Access Management
run. The list of mismatched test cases as created in the statistics document contains test
case IDs that have triggered mismatch and includes the reason for the mismatch, as
seen in Table 26–14.
26.7.2 About the Saved Connection Configuration File
This is the output files that is saved using the Save Configuration command on the File
menu; the default file name is config.xml. This connection configuration file includes
details that were specified in the Access Tester Console, Server Connection panel.
Example 26–1 Connection Configuration File
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oamtestconfig xmlns="http://xmlns.example.com/idm/oam/oamtest/schema"
version="1.0">
<connection timeout="30000" minnconn="1" mode="open">
<agent password="00030d05101b050c42" name="agent1"/>
<keystore rootstore="" keystore_password="" keystore=""
global_passphrase=""/>
<primary>
<server maxconn="1" port="2100" addr="oam_server1"/>
</primary>
<secondary>
<server maxconn="1" port="0" addr=""/>
</secondary>
</connection>
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
<identity>
<id>admin1</id>
<password>00030d05101b050c42</password>
<certstore></certstore>
<ipaddr>111.222.3.4</ipaddr>
</identity>
</oamtestconfig>
Table 26–14 Mismatched Results Reasons in the Statistics Document
Reason for a MisMatch Description
Result The test cases did not match because of the difference in OAM Server
response codes (Yes versus No).
Content The test cases did not match because of the differences in the specific
data values that were returned by the OAM Server. The specific values
from the last test run that have triggered the mismatch are included.
Note: An input test script file is also generated as described in the
following topic. The name of the configuration file is used in the input
test script to ensure that running the Access Tester in command line
mode picks up connection information defined in the connection file.
Evaluating Scripts, Log File, and Statistics
Validating Connectivity and Policies Using the Access Tester 26-33
26.7.3 About the Generated Input Test Script
The input test script is generated by using the Access Tester and capturing your own
test cases. The "configfile" attribute of the "Control" element is updated after creation
to specify the connection configuration file to be used in command line mode for
establishing a connection to the OAM Server.
Example 26–2 Generated Input Test Script
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oamtestscript xmlns="http://xmlns.example.com/idm/oam/oamtest/schema"
version="1.0">
<history description="Manually generated using agent 'agent1'"
createdon="2012-02-03T22:28:00.468-05:00" createdby="test_user"/>
<control numthreads="1" numiterations="1" ignorecontent="false"
testname="samplerun1" configfile="config.xml"/>
<cases numcases="4">
<case uuid="465a4fda-d814-4ab7-b81b-f3f1cd72bbc0">
<request code="Validate">
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
</request>
<response elapsed="984" code="Yes">
<comment></comment>
<status>Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)</status>
<content>
<line type="auth.scheme.id">LDAPScheme</line>
<line type="auth.scheme.level">2</line>
<line type="auth.scheme.required.creds">2</line>
<line
type="auth.scheme.redirect.url">http://emerald.uk.example.com:14100/oam/server/</l
ine>
</content>
</response>
</case>
<case uuid="009b44e3-1a94-4bfc-a0c3-84a38a9e0f2a">
<request code="Authenticate">
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
<identity>
<id>weblogic</id>
<password>00030d05101b050c42</password>
<certstore></certstore>
<ipaddr>192.168.1.8</ipaddr>
</identity>
</request>
<response elapsed="187" code="Yes">
<comment></comment>
<status>Major code: 10(CredentialsAccepted) Minor code:
Evaluating Scripts, Log File, and Statistics
26-34 Administrator's Guide for Oracle Access Management
2(NoCode)</status>
<content>
<line
type="user.dn">cn=weblogic,dc=uk,dc=example,dc=com</line>
</content>
</response>
</case>
<case uuid="84fe9b06-86d1-47df-a399-6311990743c3">
<request code="Authorize">
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
<identity>
<id>weblogic</id>
<password>00030d05101b050c42</password>
<certstore></certstore>
<ipaddr>192.168.1.8</ipaddr>
</identity>
</request>
<response elapsed="188" code="Yes">
<comment></comment>
<status>Major code: 8(Allow) Minor code: 2(NoCode)</status>
<content/>
</response>
</case>
<case uuid="61579e47-5532-42c3-bbc7-a00828256bf4">
<request code="Validate">
<uri getauthscheme="false">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
</request>
<response elapsed="172" code="Yes">
<comment></comment>
<status>Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)</status>
<content/>
</response>
</case>
</cases>
</oamtestscript>
26.7.4 About the Target Output File Containing Test Run Results
This example was generated by running the Access Tester in command line mode and
specifying the script.xml file as input to execute the 4 captured test cases:
Dscript.scriptfile="script.xml" -jar oamtest.jar
Notice the various sections in Example 26–3. As shown in the execution log, this test
run found no mismatches, and shows that 4 out of 4 requests matched.
Evaluating Scripts, Log File, and Statistics
Validating Connectivity and Policies Using the Access Tester 26-35
Example 26–3 Output File Generated During a Test Run
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oamtestscript xmlns="http://xmlns.example.com/idm/oam/oamtest/schema"
version="1.0">
<history description="Generated from script 'script.xml' using agent 'agent1'"
createdon="2012-02-03T23:03:02.171-05:00" createdby="test_user"/>
<control numthreads="1" numiterations="1" ignorecontent="false"
testname="oamtest" configfile=""/>
<cases numcases="4">
<case uuid="465a4fda-d814-4ab7-b81b-f3f1cd72bbc0">
<request code="Validate">
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
</request>
<response elapsed="969" code="Yes">
<comment></comment>
<status>Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)</status>
<content>
<line type="auth.scheme.id">LDAPScheme</line>
<line type="auth.scheme.level">2</line>
<line type="auth.scheme.required.creds">2</line>
<line
type="auth.scheme.redirect.url">http://emerald.uk.example.com:14100/oam/server/
</line>
</content>
</response>
</case>
<case uuid="009b44e3-1a94-4bfc-a0c3-84a38a9e0f2a">
<request code="Authenticate">
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
<identity>
<id>weblogic</id>
<password>00030d05101b050c42</password>
<certstore></certstore>
<ipaddr>111.222.3.4</ipaddr>
</identity>
</request>
<response elapsed="187" code="Yes">
<comment></comment>
<status>Major code: 10(CredentialsAccepted) Minor code:
2(NoCode)</status>
<content>
<line type="user.dn">cn=weblogic,dc=us,dc=oracle,dc=com</line>
</content>
</response>
</case>
<case uuid="84fe9b06-86d1-47df-a399-6311990743c3">
<request code="Authorize">
Evaluating Scripts, Log File, and Statistics
26-36 Administrator's Guide for Oracle Access Management
<uri getauthscheme="true">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
<identity>
<id>weblogic</id>
<password>00030d05101b050c42</password>
<certstore></certstore>
<ipaddr>111.222.3.4</ipaddr>
</identity>
</request>
<response elapsed="172" code="Yes">
<comment></comment>
<status>Major code: 8(Allow) Minor code: 2(NoCode)</status>
<content/>
</response>
</case>
<case uuid="61579e47-5532-42c3-bbc7-a00828256bf4">
<request code="Validate">
<uri getauthscheme="false">
<scheme>http</scheme>
<host>oam_server1</host>
<port>7777</port>
<resource>/index.html</resource>
<operation>Get</operation>
</uri>
</request>
<response elapsed="171" code="Yes">
<comment></comment>
<status>Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)</status>
<content/>
</response>
</case>
</cases>
</oamtestscript>
26.7.5 About the Statistics Document
The statistics file (_stats.xml) is generated together with the target output script during
the test run identified in the Execution log. The script.xml file was used as input to
execute the 4 captured test cases. The test run found no mismatches, and shows that 4
out of 4 requests matched.
A sample statistics document is shown in Example 26–4. The various sections that
provide statistics for this run, which you can compare against statistics for an earlier
"known good" run.
Example 26–4 Sample Statistics Document
A sample statistics document is shown here. Notice,
<oamteststats xmlns="http://xmlns.example.com/idm/oam/oamtest/schema"
version="1.0">
<history description="Generated from script 'script.xml' using agent
'agent1'" createdon="2012-02-03T23:03:02.171-05:00" createdby="test_user"/>
<summary>
Evaluating Scripts, Log File, and Statistics
Validating Connectivity and Policies Using the Access Tester 26-37
<total>
<nummatched>4</nummatched>
<numtotal>4</numtotal>
<avgelapsedsource>238</avgelapsedsource
<avgelapsedtarget>232</avgelapsedtarget>
</total>
<validate>
<nummatched>2</nummatched>
<numtotal>2</numtotal>
<avgelapsedsource>578</avgelapsedsource>
<avgelapsedtarget>570</avgelapsedtarget>
</validate>
<authenticate>
<nummatched>1</nummatched>
<numtotal>1</numtotal>
<avgelapsedsource>187</avgelapsedsource>
<avgelapsedtarget>187</avgelapsedtarget>
</authenticate>
<authorize>
<nummatched>1</nummatched>
<numtotal>1</numtotal>
<avgelapsedsource>188</avgelapsedsource>
<avgelapsedtarget>172</avgelapsedtarget>
</authorize>
<summary>
<detail>
<source>
<validate>
<yes>2</yes>
<no>0</no>
<error>0</error>
<mismatch>0</mismatch>
<elapsed>1156</elapsed>
</validate>
<authenticate>
<yes>1</yes>
<no>0</no>
<error>0</error>
<mismatch>0</mismatch>
<elapsed>187</elapsed>
</authenticate>
<authorize>
<yes>1</yes>
<no>0</no>
<error>0</error>
<mismatch>0</mismatch>
<elapsed>188</elapsed>
</authorize>
</source>
<target>
<validate>
<yes>2</yes>
<no>0</no>
<error>0</error>
<mismatch>0</mismatch>
<elapsed>1140</elapsed>
</validate>
<authenticate>
<yes>1</yes>
<no>0</no>
Evaluating Scripts, Log File, and Statistics
26-38 Administrator's Guide for Oracle Access Management
<error>0</error>
<mismatch>0</mismatch>
<elapsed>187</elapsed>
</authenticate>
<authorize>
<yes>1</yes>
<no>0</no>
<error>0</error>
<mismatch>0</mismatch>
<elapsed>172</elapsed>
</authorize>
<target>
</detail>
<mismatch numcases="0"/>
</oamteststats>
26.7.6 About the Execution Log
This sample execution log was generated together with the target output script during
a test run using script.xml to execute 4 test cases. The test run found no mismatches,
and shows that 4 out of 4 requests matched.
As you review this example, notice the information provided which is the same as the
information you see in the Status Messages panel of the Access Tester. Notice the test
cases, test name, connection configuration file, agent name, connection status, request
validation status, authentication scheme, redirect URL, credentials expected,
authentication status and user DN, session ID, authorization status, validation status,
and summary statistics. Also notice that the target script and statistics document were
generated by this run.
Example 26–5 Execution Log
[2/3/12 11:02 PM][info] Setting up to run script 'script.xml'
[2/3/12 11:02 PM][info] Loading test cases and control parameters from script
[2/3/12 11:02 PM][info] Loaded 4 cases
[2/3/12 11:02 PM][info] Control data for this test run:
[2/3/12 11:02 PM][info] Test name : 'samplerun1'
[2/3/12 11:02 PM][info] Configuration file : 'config.xml'
[2/3/12 11:02 PM][info] Ignore content : 'false'
[2/3/12 11:02 PM][info] Loading server configuration from file
[2/3/12 11:02 PM][info] Loaded server configuration
[2/3/12 11:02 PM][info] Connecting to server as agent 'oam_agent1'
[2/3/12 11:03 PM][info][request] Connect : Yes
...
[2/3/12 11:03 PM][info] Test 'samplerun1' will process 4 cases
[2/3/12 11:03 PM][info][request] Validate : Yes
[2/3/12 11:03 PM][info] Authentication scheme : LDAPScheme, level : 2
[2/3/12 11:03 PM][info] Redirect URL :
http://oam_server1.uk.example.com:2100/server/
[2/3/12 11:03 PM][info] Credentials expected: 0x01 (password)
[2/3/12 11:03 PM][info][request] Authenticate : Yes
[2/3/12 11:03 PM][info] User DN : cn=admin1,dc=us,dc=company,dc=com
[2/3/12 11:03 PM][info] Session ID : -1
[2/3/12 11:03 PM][info][request] Authorize : Yes
[2/3/12 11:03 PM][info][request] Validate : Yes
[2/3/12 11:03 PM][info] Summary statistics
[2/3/12 11:03 PM][info] Matched 4 of 4, avg latency 232ms vs 238ms
[2/3/12 11:03 PM][info] Validate: matched 2 of 2, avg latency 570ms vs 578ms
[2/3/12 11:03 PM][info] Authenticate: matched 1 of 1, avg latency 187ms vs 187ms
Evaluating Scripts, Log File, and Statistics
Validating Connectivity and Policies Using the Access Tester 26-39
[2/3/12 11:03 PM][info] Authorize: matched 1 of 1, avg latency 172ms vs 188ms
[2/3/12 11:03 PM][info] Generated target script 'samplerun1_0302171__target.xml'
[2/3/12 11:03 PM][info] Generated statistics log 'samplerun1_0302171__stats.xml'
Evaluating Scripts, Log File, and Statistics
26-40 Administrator's Guide for Oracle Access Management
27
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-1
27
Configuring Centralized Logout for Sessions
Involving 11g WebGates
[22]
This chapter describes Access Manager single logout (also known as global logout) for
sessions involving 11g WebGates. With Access Manager, single logout refers to the
process of terminating an active session. Oracle recommends using the logout
mechanism provided by Access Manager in the manner described in this chapter (not
custom logout scripts).
This chapter provides the following sections:
■Prerequisites
■Introduction to Centralized Logout for Access Manager 11g
■Configuring Centralized Logout for 11g WebGates
■Validating Global Sign-On and Centralized Logout
27.1 Prerequisites
Before you can perform tasks in this chapter:
■The application must be deployed on the Web server where the agent is
configured and registered with Access Manager
■One OAM Agent, on any supported Web server and platform, must be running
and registered with Access Manager 11g (Chapter 15)
■Policies must be configured to protect the resource in an Access Manager 11g
Application Domain (Chapter 25)
27.2 Introduction to Centralized Logout for Access Manager 11g
Unless explicitly stated, information in this chapter applies to OAM 11g WebGate
Agents using the default embedded credential collector (ECC).
This section provides the following topics:
■About Centralized Logout for 11g WebGates
■About Logout Parameters for 11g WebGates
See Also: Different agents require different logout implementation
steps described as follows:
■10g Webgate logout Chapter 30
■OSSO Agent (mod_osso) logout Chapter 29
Introduction to Centralized Logout for Access Manager 11g
27-2 Administrator's Guide for Oracle Access Management
27.2.1 About Centralized Logout for 11g WebGates
Access Manager provides centralized logout (also known as global log out) for
sessions. Centralized logout refers to the process of terminating an active session,
which means that:
■Applications must not provide their own logout page for use in an SSO
environment.
■Applications must make their logout links configurable with a value that points to
the logout URL specified by the WebGate Administrator.
Unlike partner applications, external applications (Yahoo! Mail, for example), do not
delegate authentication to OAM and do not cede logout control to the OAM single
sign-on server. It is the user's responsibility to log out of each of these applications.
Table 27–1 describes the circumstances under which centralized logout occurs. When
the logout URL is encountered and the cookie is removed (OAMAuthnCookie for 11g
Webgates; ObSSOcookie for 10g Webgates). Webgate logs out the user and requires
user re-authentication.
27.2.2 About Logout Parameters for 11g WebGates
Generally speaking, during centralized logout, the SSO Engine receives a
user-session-exists
request. The Session Management Engine looks up the session
and responds with
the-session-exists
response. The SSO engine sends a
Clear
Session
request. The Session management engine clears the token and session context.
The SSO engine then sends a
Session Cleared
response.
Clearing the user token and the session context clears the server-side state, which
includes clearing the OAM_ID cookie set on the server side. When the agent is
notified, the agent clears the client-side state of the application.
Configuring 11g WebGates for logout against OAM Servers requires a
Logout
Callback URL
(Table 15–3). Centralized logout for 11g agents sets the cookie from
Note: Oracle strongly recommends that applications use the ADF
Authentication servlet, which interfaces with OPSS where a
domain-wide configuration parameter can be used to specify the
logout URL. This way applications need not be modified or
redeployed to change logout configuration.
Table 27–1 Centralized Logout Circumstances
Circumstance Description
Explicitly The client state is invalidated and the session ends. If a new attempt is
made to access the resource, the client must re-authenticate.
When the user logs out.
When the Administrator terminates the session
When the session is terminated based on changes on the identity side
Implicitly When no user activity occurs within the defined session timeout period,
the user is logged out automatically and redirected back to the partner
with a new session ID and a new prompt for credentials. This occurs if
no lower-level authentication is configured for the resource.
With Access Manager, the user is not logged out if 10g Webgate simply
encounters a logout URL unless the logout.html provides an explicit
redirection to the Server logout. The Webgate redirects the user to the
Server logout.
Introduction to Centralized Logout for Access Manager 11g
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-3
loggedout
to
empty
and expires OAMAuthnCookie_<host:port>_<random number> to
explicitly clear it during logout, (rather than leaving behind an empty or logged out
cookie).
11g WebGates differ only slightly from 10g Webgates, and match only the URI part of
Logout Callback URL
.
The SSO Engine supports the central logout page on the OAM Server and:
■Calls back to
Logout Callback URL
of 11g Webgates during logout
The WebGate parameter
Logout Callback URL
can be configured using a URI
format (recommended), without host:port. OAM Server dynamically constructs the
full URL based on the host:port in the original request and calls back on it. This can
also be a full URL format with a host:port, where OAM Server calls back directly
without reconstructing callback URL.
■Lands on
end_url
(passed in as query parameter) after logout
Several elements in the 11g Webgate registration page enable centralized logout for 11g
WebGates. After registration, the ObAccessClient.xml file is populated with the
information in Table 27–2.
Table 27–2 Logout Details After Registration (ObAccessClient.xml)
Element Description
Logout URL
10g and 11g WebGates
The Logout URL triggers the logout handler, which removes the cookie (ObSSOCookie for 10g
Webgates; OAMAuthnCookie for 11g WebGates) and requires the user to re-authenticate the next
time he accesses a resource protected by Access Manager.
■If there is a match, the WebGate logout handler is triggered.
■If Logout URL is not configured the request URL is checked for "
logout.
" and, if found
(except "
logout.gif
" and "
logout.jpg
"), also triggers the logout handler.
Default = [] (not set)
Note: This is the standard 10g WebGate configuration parameter used to trigger initial logout
through a customized local logout page as described in "Configuring Centralized Logout for 10g
WebGate with 11g OAM Servers" on page 30-22.
Additional Logout for 11g
WebGate Only
For 11g WebGate single sign-off behavior, the following elements and values automate the redirect
to a central logout URL, callback URL, and end URL. This replaces 10g WebGate single sign-off
only through a customized local logout page.
Configuring Centralized Logout for 11g WebGates
27-4 Administrator's Guide for Oracle Access Management
27.3 Configuring Centralized Logout for 11g WebGates
This section provides the following topics:
■Configuring Centralized Logout for 11g WebGates When the ECC is Used
■Configuring Logout When Using Detached Credential Collector-Enabled WebGate
Logout Callback URL The URL to
oam_logout_success
, which clears cookies during the call back. This can be a URI
format without host:port (recommended), where the OAM Server calls back on the host:port of the
original resource request. For example:
Default = /oam_logout_success
This can also be a full URL format with a host:port, where OAM Server calls back directly without
reconstructing callback URL.
When the request URL matches the Logout Callback URL, Webgate clear its cookies and streams an
image .gif in the response. This is similar to OSSO agent behavior.
When Webgate redirects to the server logout page, it records an "end" URL as a query parameter
(
end_url=http://host:port/..."
), which becomes the landing page that the OAM Server
redirects back to after logout.
Note: In the remote registration template this parameter is named logoutCallbackUrl (Table 15–10).
Other Oracle Access Management services support the central logout page on the server. The end_
url relies on the target URL query parameter passed from OPSS integrated applications. See Also:
"Configuring Centralized Logout for Oracle ADF-Coded Applications" on page A-7.
Logout Redirect URL This parameter is automatically populated after agent registration completes. By default, this is
based on the OAM Server host name with a default port of 14200. For example:
Default = http://OAMServer_host:14200/oam/server/logout
The Logout URL triggers the logout handler, which removes the OAMAuthnCookie_<host:port>_
<random number> and requires the user to re-authenticate the next time he accesses a resource
protected by Access Manager.
■When Webgate logout handler is triggered, it redirects to the central logout page specified by
the Logout Redirect URL parameter if it is configured.
■If this is explicitly cleared (and not configured), then 10g behavior is triggered. The local
logout page can have a customized script to redirect to the central logout page and can clear
additional 3rd party cookies if desired.
Logout Target URL The value for this is name for the query parameter that the OPSS applications passes to Webgate
during logout. This query parameter specifies the target URL of the landing page after logout.
Default: end_url
Note: The end_url value is configured using param.logout.targeturl in jps-config.xml.
■If Logout Target URL is configured, Webgate searches for the value passed in the logout
request's query parameter and passes it as end_url query parameter in the redirect URL to
OAM Server.
■If Logout Target URL is not configured, Webgate searches for the default name "end_url" and
passes that end_url query parameter along.
See Also:
■"Configuring Centralized Logout for 10g WebGate with 11g OAM
Servers" on page 30-22
■"Configuring Logout for OSSO Agents with Access Manager
11.1.2" on page 29-16
■"Configuring Centralized Logout for Oracle ADF-Coded
Applications" on page A-7
Table 27–2 (Cont.) Logout Details After Registration (ObAccessClient.xml)
Element Description
Configuring Centralized Logout for 11g WebGates
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-5
27.3.1 Configuring Centralized Logout for 11g WebGates When the ECC is Used
During 11g Resource WebGate registration or editing, you configure the logout
parameters as described here.
To configure centralized logout for 11g WebGates
1. Choose your method for registration described in Chapter 15, "Registering and
Managing OAM 11g Agents"
2. When creating or editing an agent registration, include appropriate logout values
for your environment (Table 27–2):
■Logout URL
■Logout Callback URL
■Logout Redirect URL
■Logout Target URL
3. Finish and save your agent registration, as usual.
4. Multiple DNS Domains: Perform the following steps if you have multiple DNS
domains configured for Access Manager 11g SSO.
a. Configure the
Logout Callback URL
as the second value in the
logOutUrls
parameter on each resource WebGate.
Logout Callback URL
is the location on WebGate that the request must be sent
to, for clearing the SSO Cookie in that domain. The
Logout Callback URL
cannot be logout.html.
b. Ensure that a file physically exists on each Web server at the
Logout Callback
URL
location (usually, at the same location as logout.html).
For example, if you configure a file named logout.png in the same location as
logout.html, then the
Logout Callback URL
of logout.png would be:
/oamsso/logout.png
5. Perform steps in "Validating Global Sign-On and Centralized Logout" on
page 27-6.
Note: If the
LogOutUrl
parameter is already configured for the 11g
WebGate (with a value other than
/oamsso/logout.html
), then ensure
that is also present as part of the
LogOutUrl
parameter.
See Also: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate" on page 27-6
Note: The
Logout Callback URL
can be unique for each WebGate;
however, to construct the
Logout Callback URL
for each WebGate, it
is sufficient for the OAM Server to know the host and port of each
WebGate from each domain. The file that the
Logout Callback URL
points to must differ from the logout.html script in the WebGate
installation directory.
Validating Global Sign-On and Centralized Logout
27-6 Administrator's Guide for Oracle Access Management
27.3.2 Configuring Logout When Using Detached Credential Collector-Enabled
WebGate
When the DCC receives a logout request from the Agent, the DCC:
■Decrypts the logout request, if needed
■Retrieves the
end_url
, constructs the full URL with the Agent's host:port if needed
■Clears the DCC cookie (DCCCtxCookie)
■Sends the logout request across the back channel to terminate the session
■
Logout Callback URLLogout Callback URLs
Gets a logout page containing links
to all visited agent from OAM Sever (which has this information), or get only a list
of the visited from OAM Sever to construct a logout page locally, and redirect user
to this page on DCC.
■Returns to the
end_url
after logout completes
To configure logout for Resource Webgates separate from DCC
1. Confirm that the Perl scripts for DCC logout include the actual location of the Perl
executable on the Webgate host
$WEBGATE_HOME/oamsso-bin/*pl
.
2. Resource Webgate: Modify the Logout Redirect URL to point to DCC's logout.pl:
a. Find the Resource Webgate Registration: See "Searching for an OAM Agent
Registration".
b. Modify the
Logout Redirect URL to
point to the DCC's logout.pl. For
example:
http://DCCWGhost:port/oamsso-bin/logout.pl
3. Perform steps in "Validating Global Sign-On and Centralized Logout" on
page 27-6.
27.4 Validating Global Sign-On and Centralized Logout
This section provides the following topics:
■Confirming Global Sign-On
■Validating Global Sign-On with Mixed Agent Types
■Observing Centralized Logout
27.4.1 Confirming Global Sign-On
Use the following procedure to observe single sign-on global login.
Prerequisites
■Agents and Servers must be registered with Access Manager and running
Note: The DCC ignores the
Logout Redirect URL
parameter in the
Webgate registration page. However, if the Resource Webgate
Logout
Redirect URL
is anything other than
logout.*
, then that URL must be
defined in DCC
Logout URLs
. See Table 24–3, " Specifying Credential
Collectors and Related Forms for Authentication"
Validating Global Sign-On and Centralized Logout
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-7
■Resources and policies controlling SSO must be defined within Access Manager
Application Domains
To observe global sign-on
1. From a browser, enter the URL to a protected resource.
2. On the login page, sign in using proper credentials.
3. Verify that the resource is presented; do not log out.
4. In the same browser window, enter the URL to another protected resource and
confirm that the resource is presented without having to re-authenticate.
27.4.2 Validating Global Sign-On with Mixed Agent Types
Use the following procedure to observe single sign-on global login with different
applications and agents that have the same authentication level.
For example, suppose you have:
■OSSO Partner at
http://host1.example.com:7777/private/index.html
protected using mod_osso
■Webgate Partner at
http://host2.example.com:8888/mydomain/finance/index.html
protected using
OAM Agent
Within the same browser session, you can access all applications protected by either
agent with only a single sign in.
Prerequisites
■Agents and Servers must be registered with Access Manager and running
■Resources and policies must be defined within Access Manager Application
Domains
■Both partners must be protected at the same authentication level
■Single sign-on must be configured as described in this chapter
To observe global sign-on with mixed agent types
1. OSSO Agent Protected Application:
a. From a browser, enter the URL of the OSSO-protected resource
b. Confirm that the login page appears and sign in using proper credentials.
c. Confirm that the protected resource is served.
d. Remain in the same browser session and proceed to Step 2.
2. Same Browser Session, OAM Agent Protected Application:
a. In the same browser session as Step 1, enter the URL of the OAM
Agent-protected resource.
b. Confirm that the protected resource is served and that no login page appears.
3. Log out of the browser session.
4. Fresh Browser Session, OAM Agent Protected Application:
a. In a fresh browser session, enter the URL of the OAM-protected resource.
b. Confirm that the login page appears and sign in using proper credentials.
Validating Global Sign-On and Centralized Logout
27-8 Administrator's Guide for Oracle Access Management
c. Confirm that the protected resource is served.
d. Remain in the same browser session and proceed to Step 5.
5. Same Browser Session, OSSO Agent Protected Application:
a. In the same browser session as Step 4, enter the URL of the OSSO
Agent-protected resource.
b. Confirm that the protected resource is served and that no login page appears.
27.4.3 Observing Centralized Logout
Use the following procedure to observe centralized logout:
■With OAM Agents, the logout URL redirects to the server and cookies are cleared
and invalidated so that a subsequent request cannot locate the cookie.
■With mod_osso, each agent destroys its own cookies. The logout URL redirects to
the global logout page on the server and each partner sends cookies to the server.
Prerequisites
■Agents must be registered and running
■Resources must be protected by Access Manager Application Domains
■Single sign-on must be configured with authentication and authorization policies
and responses in Access Manager Application Domains
To observe centralized logout
1. Single Application:
a. From a browser, enter the URL of the protected resource.
b. Confirm that the login page appears and sign in using proper credentials.
c. Confirm that the protected resource is served.
d. Open a new browser tab or window and access the same resource to confirm
that the second attempt does not require another login.
e. Logout from one tab.
f. Access the resource again to confirm that a login page appears.
2. Two Applications:
a. From a browser, enter the URL of the protected resource.
b. Confirm that the login page appears and sign in using proper credentials.
c. In a new tab or window, access another protected application and confirm that
the second application does not require another login.
d. Log out of the first application.
e. Access the second application and confirm that the login page appears.
Part VII
Par t VII
Registering and Using Agents with Access
Manager
When your enterprise includes Web server types other than Oracle HTTP Server, you
can install 10g WebGates to use with Access Manager.
Part VI contains the following chapters:
■Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
■Chapter 29, "Registering and Managing Legacy OSSO Agents"
■Chapter 30, "Registering and Managing 10g WebGates with Access Manager 11g"
■Chapter 31, "Configuring Apache, OHS, IHS for 10g WebGates"
■Chapter 32, "Configuring the ISA Server for 10g WebGates"
■Chapter 33, "Configuring the IIS Web Server for 10g WebGates"
■Chapter 34, "Configuring Lotus Domino Web Servers for 10g WebGates"
28
Registering and Managing Legacy OpenSSO Agents 28-1
28
Registering and Managing Legacy OpenSSO
Agents
[23]
If OpenSSO is already in place as the enterprise solution for your existing Oracle
deployment, Oracle Fusion Middleware continues to support this as a solution.
Additionally, you can register existing OpenSSO agents for use with Access Manager.
This chapter explains how to register or manage legacy OpenSSO agents for use with
Access Manager 11.1.2 and provides the following sections:
■Introduction to OpenSSO, Agents, Migration and Co-existence
■Runtime Processing Between OpenSSO Agents and Access Manager
■Understanding OpenSSO Agent Registration Parameters
■Registering and Managing OpenSSO Agents Using the Console
■Performing Remote Registration for OpenSSO Agents
■Updating Registered OpenSSO Agents Remotely
■Locating Other OpenSSO Agent Information
28.1 Introduction to OpenSSO, Agents, Migration and Co-existence
OpenSSO is the open source version of the Sun Access Management, Federation
Management, and Web Services Security product. Each OpenSSO Agent is a filter that
is plugged into a container (Oracle WebLogic Server, JBoss, Apache, and so on) that
hosts applications.
OpenSSO Agents can co-exist together with Webgates, Access Clients, or OSSO
Agents. Oracle provides OpenSSO Assessment and OpenSSO Migration tools that you
can use to transition existing OpenSSO agents, profiles, and policies in to Access
Manager.
Each OpenSSO Agent provides restricted access to applications by intercepting
requests to these applications. After provisioning, OpenSSO Agents use OAM Server
instead of the OpenSSO Server.
See Also: Oracle Fusion Middleware Upgrade Guide for Oracle
Identity and Access Management for details about Oracle-provided
tools and processes to assess and transition OpenSSO agents, profiles,
and policies in to Access Manager.
Introduction to OpenSSO, Agents, Migration and Co-existence
28-2 Administrator's Guide for Oracle Access Management
After provisioning, OpenSSO Agents use OAM Server instead of the OpenSSO Server.
Restricted access to applications is provided by intercepting requests to these
applications. OAM Server provides an OpenSSO Proxy that enables communication
between the agent and OAM Server and facilitates SSO to the agent-protected
application.
OAM Server provides an OpenSSO Proxy that enables communication between the
agent and OAM Server and facilitates SSO to the agent-protected application. Using
registered OpenSSO Agents, Access Manager provides the features outlined in
Table 28–1 (authentication features and a subset of authorization features).
For more information, see:
■About Migration and Co-existence Between OpenSSO and Access Manager
■About OpenSSO Agent Reliance on Access Manager
■Runtime Processing Between OpenSSO Agents and Access Manager
28.1.1 About Migration and Co-existence Between OpenSSO and Access Manager
Access Manager supports co-existence with an existing OpenSSO Server deployment
that has been migrated using the OpenSSO to Access Manager upgrade tool.
The OpenSSO to Access Manager Upgrade makes use of OpenSSO Discovery Agents
and Policy mapping logic, which fulfills requirements described in following topics:
■OpenSSO Policy Migration
■Application Domain Creation During OpenSSO Migration
■OpenSSO Authentication Policy Migration
■Host Identifier Creation in Access Manager
For System Requirements and Supported Platforms for Access Manager and
OpenSSO, see the Oracle Identity and Access Management matrix on the following
site:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
Note: OpenSSO Agents must be registered with Access Manager to
use OAM Server instead of the OpenSSO Server.
Table 28–1 Features: OpenSSO Agents with Access Manager
Agent Authentication User Authentication
User Single-Sign-On User Single Logout
SSO in mixed agents case (between OpenSSO agent
and WebGate agent)
User Authorization
Self and Sub-tree mode search Policy Conditions (Identity, LDAP filter, Session
attribute, IP Range, Temporal)
User profile attributes retrieval Centralized Agent configuration with REST request
or response
Migration of Agent profiles, Policies, User Stores,
Authentication Stores
Migration Assessment tool
Introduction to OpenSSO, Agents, Migration and Co-existence
Registering and Managing Legacy OpenSSO Agents 28-3
OpenSSO Policy Migration
The OpenSSO policy is mapped to Access Manager authentication and authorization
policies based on available artifacts in the OpenSSO deployment. Table 28–2 table
outlines the mapping that occurs between OpenSSO and Access Manager during
Policy migration.
Application Domain Creation During OpenSSO Migration
If an existing Access Manager Application Domain and policies do not match an
OpenSSO policy domain, a new Application Domain is created in Access Manager.
The created Application Domain corresponds to an OpenSSO Realm. With respect to
each Realm, (OpenSSO Top-level and Sub -level Realms), an Application Domain is
created in Access Manager.
All existing Application Domains are compared against OpenSSO Policy Domains.
The policy name is checked against all existing policies. If a policy of the same name
exists, an error occurs. Otherwise, a new policy is created in Access Manager.
OpenSSO Authentication Policy Migration
An OpenSSO policy containing valid rules and conditions is migrated to an Access
Manager Authentication Policy: either a new policy to be created or an existing policy
to be updated. During policy creation, the OpenSSO policy rule host:port information is
used to create the host identifier and exact resource URL (or URI) to the Application
Domain.
A policy with conditions is valid for OpenSSO. However, these are migrated based on
the default Authentication Policy for Access Manager. Such policies with IP or
Temporal conditions can be migrated to Access Manager Authorization Policy
conditions.
See Also: Oracle Fusion Middleware Upgrade Guide for Oracle Identity
and Access Management
See Also: "Migrated Artifacts: OpenSSO" on page D-13
Table 28–2 OpenSSO Policy Migration
Serian OpenSSO Access Manager
1 Policy Realm Policy Domain
2 Policy Authentication and Authorization Policies
3 Resources Resources plus Host Identifier
4 Actions Not specified (By default only "GET")
5 Subject Identity Conditions in Authorization Policies
6 Conditions Authentication Scheme plus Authorization Conditions
7 Response Providers Policy Responses
Note: An OpenSSO policy referral policy is not migrated.
Note: An OpenSSO policy containing artifacts with no rules is not a
valid policy.
Introduction to OpenSSO, Agents, Migration and Co-existence
28-4 Administrator's Guide for Oracle Access Management
If the OpenSSO policy is a non-referral policy, an Access Manager Authentication
Policy is created containing an authentication scheme with the corresponding
authentication module from OpenSSO, host identifier, and resources from OpenSSO
policy. In the Access Manager Authorization policy, corresponding OpenSSO
constraints and subjects are set.
Limitation: Authentication policy creation exception if the resource already exists (in
one of the policy in same Application Domain or Realm. If the resource is already
protected by another policy (already exists under the host identifier), new policy
creation for the same resource causes an exception. This new policy is not created. The
errors are logged in a log file and also displayed in the Oracle Access Management
Console.
Host Identifier Creation in Access Manager
One Host Identifier is created within Access Manager for each unique host:port
combination from OpenSSO. Need to retrieve all the host:port from each policy rules in
each realm and will create the number of hostIdentifiers = number of unique host:port
combinations.
Top Realm: By default, OpenSSO has only one top-level realm (/). All other realms
can be created under this top-level realm. Ideally, the top-level realm will contain all
the host:port combinations for which Host Identifiers are created in Access Manager.
Sub Realm: host:port combinations in policy rules within sub realms depend on the
host:port in the Referral policy created under the top realm. The host:port in referral
policy is not necessarily from any of the host:port in other non-referral policies in top
realm (also referral policy is not applicable for migration). Hence, the host:port in sub
realm's policies can be different from the host:port in top realm's policies which are
applicable for migration.The host:port from each realm's policies is checked.
Limitation: In OpenSSO, if there are 2 (or more) policies with same rule yet with
different authentication schemes to protect the same resource, then only one (the first
one in occurrence) can be migrated to Access Manager; the others are ignored and are
not created in Access Manager. There are rare chances for such an occurrence.
28.1.2 About OpenSSO Agent Reliance on Access Manager
Access Manager supports OpenSSO Agents and processing as outlined in Table 28–3.
Introduction to OpenSSO, Agents, Migration and Co-existence
Registering and Managing Legacy OpenSSO Agents 28-5
Table 28–3 OpenSSO Reliance on Access Manager
Component Description
OpenSSO Agent OpenSSO agents must be registered with Access Manager to establish trust by authenticating
themselves. The OAM Server:
■Authenticates the agents with the credentials provided.
■Creates a session for the agent.
■Stores this information in the cache so that any server in the group/cluster can service the next
request from the agent.
■Passes the session identifier to the agent so that it can present this to OAM Server during
subsequent interactions.
This agent session does not expire, which enables the Agent to maintain trust continuity with the
OAM Server.
The agent registration can be enabled or disabled. When disabled, the Agent does not respond.
Multiple OpenSSO agents can share same centralized configuration (if required and if registered in
centralized configuration mode). Even so, each agent has its own unique session and session ID. The
agent registration can be configured for the "maximum number of agent sessions allowed" per
registration.
It might have a session timeout property that defines whether the agent's session should expire or
not.
See Also:
"Registering and Managing OpenSSO Agents Using the Console" on page 28-19
"Understanding Credential Collection and Login"
OpenSSO Proxy This Oracle-provided proxy is bundled and installed with Access Manager 11.1.2. OpenSSO Proxy
enables communication between the OpenSSO Agent and OAM Server. OpenSSO Proxy serves all
OpenSSO Agent requests and responses for Authentication, Authorization, and SSO. OpenSSO
Proxy provides protocol binding and message (request or response) conversion functionality.
See Also: "Runtime Processing Between OpenSSO Agents and Access Manager" on page 28-6
Protocol Binding Layer This Oracle-provided framework is responsible for agent-specific protocol handling and mapping
authentication protocol messages. This framework also unmarshals incoming protocol-specific
requests to protocol agnostic requests and marshals back protocol-agnostic responses to
protocol-specific responses.
Partner and Trust Store Stores OpenSSO Agent centralized configuration. The Access Manager Partner and Trust Store also
supports Agent authentication by providing GET APIs for the Agent ID and Agent Password.
OpenSSO Application
Domain
This can be generated automatically by using the Auto Create Policies option during OpenSSO
Agent registration.
Cookies The end user has the following valid cookies:
■OAM_ID cookie (represents the end session after agent authentication); see
■OpenSSO cookie (the agent finds this cookie after the OpenSSO Proxy triggers session
validation). The default name of the OpenSSO cookie is:
iPlanetDirectoryPro
Authorization Policy for
Protected Resources
Set up the Authorization policy with
■An IP Range Condition that allows access to only the specified range of IP Addresses.
■A Temporal Condition that allows access to only during the specified time period.
■An Identity Condition that allows only the configured Identity (user or group) to access the
protected resource.
■An LDAP Filter condition that allows access only if the filter condition is satisfied.
■A Session attribute condition that allows access only if the session has the configured session
attribute with required value
■An attribute condition for namespaces Request, User, and Session that allows access only if the
attribute has been configured with required values
SSO Controller Fulfills protocol requests by invoking functional components (SSO Engine, Authentication Engine,
and so on):
SSO Engine Provides enterprise and same domain Sign-on and Single logout (SLO) during an online session.
Manages the session lifecycle. Facilitates Global logout by orchestrating logout across all Relying
Parties in the valid session. Communicates with the Token Processing Engine to create a valid session
and persist the user.
Runtime Processing Between OpenSSO Agents and Access Manager
28-6 Administrator's Guide for Oracle Access Management
28.2 Runtime Processing Between OpenSSO Agents and Access
Manager
The OAM Server includes an OpenSSO Proxy to handle communication with the
OpenSSO Agent and facilitate interoperability with the OpenSSO server. Single Sign
On (SSO) and Single Logout (SLO) between OpenSSO policy agents and the OAM
Server, for instance. Interoperability is accomplished by honoring HTML/HTTP
Authentication requests for end-user authentication (as an HTTP redirect) and
XML/HTTP SSO requests for end-user session validation.
Session Management
Engine
Manages session and token context information with support for user- and Administrator-initiated
and time-out based events. The SSO Engine uses Session Management Engine capabilities for session
management:
■Create Session
■Read Session
■Update Session
■Delete Session
■Validate Session
■Get Session Id
■Set/Get creation instant
■Set/Get expiry instant
■Set/Get Last access time
■Set/Get Session state
■Purge Sessions
Note: There is no support for viewing or managing OpenSSO agent sessions using the Oracle Access
Management Console. The OpenSSO engine controller layer invokes the appropriate session
management interfaces as required. Session manager invokes the agent session cache manager
internally to manage the distributed cache for the agent session.
A unique session is created for each registered OpenSSO agent, which becomes the trust mechanism
between the Agent and the OAM Server. The unique session ID accompanies all XML/HTTP
requests for session validation, user authorization, and so on, as the agent token that must be
validated by the OAM Server before it can serve any user requests.
By default, the agent session does not expire. Agent sessions are stored within the in-memory session
cache. Agent sessions are not required to be persisted if the OAM Server restarts.
The agent session resides on the OAM Server and the unique agent session ID is passed back to
Agent in a form it can use. The agent session supports two states: Invalid (unauthenticated), and
Valid (authenticated). The OAM Server can successfully communicate with only an agent with a
Valid session state.
Token Processing Engine Responsible for token generation and token validation in response to token issuance and validation
protocol requests. Default capability manages (issues, validates, renews, cancels) Username, SAML,
and X509 tokens. This can also be extended to handle custom tokens beyond out-of-box/default
supported security token types.
Oracle Access
Management Console
Administrators use the console to:
■Provision/register OpenSSO Agents
■Manage an Application Domain and authentication and authorization policies for protected
resources.
Remote registration
utility
Administrators can use the remote registration utility to provision the agent and generate
configuration files to be consumed by the agent in Centralized mode. The agent has a copy of all
required configuration information and does not contact the OAM Server for this.
Note: If you are migrating an OpenSSO agent profile to Access Manager, both localized and
centralized modes are supported.
WLST commands Administrators can use WLST commands to:
■Migrate OpenSSO Agents to the OAM Server
See Also: "Migrated Artifacts: OpenSSO" on page D-13.
Table 28–3 (Cont.) OpenSSO Reliance on Access Manager
Component Description
Runtime Processing Between OpenSSO Agents and Access Manager
Registering and Managing Legacy OpenSSO Agents 28-7
Figure 28–1 shows a deployment that includes OpenSSO and Access Manager. The
OpenSSO Agent resides with the Web/Java EE container and the protected resource.
The OpenSSO Server resides on a different host.
Figure 28–1 Typical Deployment with OpenSSO and Access Manager
Table 28–4 describes SSO processing between Access Manager and OpenSSO Agents.
Runtime Processing Between OpenSSO Agents and Access Manager
28-8 Administrator's Guide for Oracle Access Management
Table 28–4 Access Manager Processing with OpenSSO
Functionality Description
OpenSSO Agent
Authentication
OpenSSO agents are authenticated and a valid agent session is established before user
authentication.
The OpenSSO agent authenticates itself to the OAM Server through the OpenSSO Proxy.
OpenSSO Agent Authentication (Agent authenticating itself to the OpenSSO Proxy occurs based
on the Agent type:
J2EE Agents: Upon Agent container startup.
Web Agents: With the first user authentication request to the Web Server.
1. End user sends a request to access an application or resource protected by the OpenSSO
agent.
2. OpenSSO agent redirects this un-authenticated user to the OAM Server for authentication
as follows:
J2EE Agents: Upon Agent container startup.
Web Agents: With the first user authentication request to the Web Server.
3. Agent sends the naming request to the proxy to fetch all the other service URLs
(Authentication service, Session Service, and so on).
4. Agent sends the xml Authentication request to the Proxy with its credentials on the
Authentication service endpoint (obtained from the naming request in Step 3).
5. Proxy authenticates the Agent against an Agent authentication module and creates a
non-expiry session in the proxy layer itself.
6. Proxy sends the Authentication xml Response with the agent session details to the agent
over http.
Once the agent is authenticated, a valid agent session is created. The key that is generated
following agent authentication is stored in the Partner and Trust store.
SSO User Login and
Authentication
After the agent is authenticated by the OAM Server, the user request is authenticated by the
OAM Server. SSO is then provided to the authenticated user accessing resources protected by the
agent.
After the OpenSSO agent is authenticated and logged in, the gent verifies whether the user has
an OpenSSO cookie. If not, the user authentication request is initiated from the OpenSSO agent.
User Login
1. OpenSSO agent intercepts the request to protected application. OpenSSO agent checks if the
user has an OpenSSO cookie. If not, OpenSSO agent redirects the user to the OpenSSO
Proxy for authentication service. OpenSSO Proxy fetches the requested resource URL and
the agent ID.
2. The OpenSSO Login event in the OpenSSO proxy wraps this request in a way that the core
login events can understand. The OpenSSO login event passes the resource URL and the
agent ID to the core login event.
3. Core Login events are performed, which checks if the request object contains an OAM_ID
cookie. If yes, OAM Server checks if the session represented by the OAM_ID cookie is a
valid session.
4. If the session represented by the OAM_ID cookie is valid, core login event returns the Login
response event, which is wrapped by the OpenSSO Login event and is passed on to the
OpenSSO login response handler. Core login event returns the identifier of the validated
session.
5. OpenSSO login response handler (part of OpenSSO proxy) creates an OpenSSO session
identifier in the format that the OpenSSO agent understands and extends this identifier
with the OAM session identifier. OpenSSO cookie is created, which contains the OpenSSO
session identifier and this cookie is set in the user's browser.
Runtime Processing Between OpenSSO Agents and Access Manager
Registering and Managing Legacy OpenSSO Agents 28-9
End User Session Validation OpenSSO agents intercept the request to the protected application.
End user Session Validation
1. OpenSSO agent intercepts the request to the protected application and finds an OpenSSO
cookie.
2. OpenSSO agent constructs an XML/HTTP request to validate this OpenSSO cookie. Here
XML request would have Application / Agent token ID and session ID. This request
reaches the OpenSSO proxy layer.
3. OpenSSO Proxy gets the Application Token associated with the request and validates the
Application Token with the OAM Server.
4. OAM Server validates the token and sends the response to the OpenSSO Proxy
5. If the Application Token is invalid, the OpenSSO proxy communicates that to the OpenSSO
agent and OpenSSO agent starts the agent authentication flow to obtain that valid
Application Token.
6. If the Application Token is valid, OpenSSO proxy decrypts the OpenSSO cookie, fetches the
OpenSSO session ID and gets the OAM session ID which is stored as the extension in the
OpenSSO session ID.
7. The OpenSSO Proxy triggers the session validation flow.
8. If the session represented by the OAM session ID valid, the OpenSSO proxy communicates
that to the Agent and the protected application is displayed to the user. This session
validation returns the session data (session attributes and values) to the proxy layer as the
output of session validation event response.
9. If the session is invalid, authentication flow is initiated by the OAM Server, where the OAM
Server collects the user credentials and validates the user.
User profile attributes
retrieval for Web Agent types
OpenSSO agents can request user profile attributes once the user is successfully logged in and a
valid session is created, by providing the session ID. The OpenSSO proxy layer must receive
these requests and fetch the OAM session ID from the OpenSSO session ID extension. OpenSSO
Web agents use the Policy service URL for these requests.
OpenSSO proxy then fetches these attributes and passes the session ID to the OAM Server
(which uses the responses framework to fetch the User Profile attributes and return the data to
the OpenSSO Proxy).
User profile attributes
retrieval for J2EE Agent types
OpenSSO J2EE agents use jax-rpc calls to retrieve user profile attributes. The flow is similar as
the one for Web agents types to retrieve these properties.
User Single Logout 1. The OpenSSO Proxy receives a User logout request and forwards the user to the OAM
logout URL
2. OpenSSO Proxy decrypts the OpenSSO cookie, fetches the OpenSSO session identifier and,
from that, fetches the OAM session ID. OpenSSO proxy sends the logout request to
controller through the OpenSSO logout event with the OAM session ID.
3. Core logout events are performed, which includes the controller calls to the SSO engine to
confirm the session exists. If the session exists, the OAM_ID cookie is deleted, and global
logout is performed.
4. The SSO engine returns the response to the controller indicating the session has been
cleared.
5. The controller sends a request to the proxy to clear tokens.
6. The Proxy sends the request to the agent to clear tokens through the OpenSSO Logout
response handler.
Table 28–4 (Cont.) Access Manager Processing with OpenSSO
Functionality Description
Understanding OpenSSO Agent Registration Parameters
28-10 Administrator's Guide for Oracle Access Management
28.3 Understanding OpenSSO Agent Registration Parameters
Whether you migrate existing OpenSSO Agents to Access Manager or register a fresh
OpenSSO Agent, the Oracle Access Management Console provides centralized
registration and management of OpenSSO Agents.
■About OpenSSO Agent Registration Parameters
■About the Expanded OpenSSO Agent Page and Parameters
28.3.1 About OpenSSO Agent Registration Parameters
Figure 28–2 shows the New OpenSSO Agent page where Administrators enter
information during new OpenSSO agent registration.
SSO Agent Logout Access Manager handles single logout requests originating from the OpenSSO agents.
Note: The user must be logged out from resources protected by other agents (WebGate and
MOD_OSSO, for instance). Agent logout is not required other than in the multi-domain
environment.
1. The OpenSSO Agent requests logout to OpenSSO Proxy.
2. The Proxy fetches the Application token from the request and verifies that the request is
initiated by an authenticated agent.
3. Opensso Agent Logout is handled within the proxy as the session is created in an
independent Agent Session Management Module.
4. The decrypted token is returned to the OpenSSO Proxy. If there is no OpenSSO token
present, steps 2 and 3 are absent.
5. The OpenSSO Login event in the OpenSSO proxy wraps this request in a way that the core
login events can understand.
6. Core Login events are performed, which includes forwarding the request to the SSO Engine
through the controller and authenticating the user. A new session is created for the
authenticated user.
7. Core login event returns the Login response event, which is wrapped by the OpenSSO
Login event and is passed on to the OpenSSO login response handler.
8. OpenSSO login response handler sends the response to the OpenSSO agent.
Token Generati on for
OpenSSO Agents
Access Manager processes the tokens generated for, and to be consumed by the OpenSSO agents.
Logging Enables you to track events during end user access enforcement for following events, using the
OAM Server log component:
■Login success and login failure events
■Logout success and logout failure events
■Log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE),
each of which indicates severity in descending order.
Auditing Using the OAM Server audit component to:
■Audit Login events
■Audit Logout success events
Polling Polling is not Supported. Only Session Destroy notifications are supported by the OpenSSO
Proxy.
Table 28–4 (Cont.) Access Manager Processing with OpenSSO
Functionality Description
Understanding OpenSSO Agent Registration Parameters
Registering and Managing Legacy OpenSSO Agents 28-11
Figure 28–2 Create OpenSSO Agent Page
Table 28–5 describes the elements on the New OpenSSO Agent page.
Table 28–5 Elements on the New OpenSSO Agent Page
Element Description
Agent Type OpenSSO agent types can be either:
■Web: Use with Web resources and Web resource URLs.
■J2EE: Default agent type. Use J2EE type agents for Java EE resources and
applications.
For the J2EE Agent, Filter modes must be set by choosing either:
SSO_ONLY (Access Manager Authentication Only): Enables the least
restrictive mode of operation for the filter; the agent simply ensures that all
users who try to access protected web resources are authenticated.
URL_Policy (Access Manager Authentication and Authorization): Enables
the agent filter to enforce URL policies. By default, with Web Agents,
.com.sun.identity.agents.config.sso.onlyattribute is set to "false".
Note: Both agent types provide access protection when you also choose SSO
only.
Agent Name Unique name for this agent.
Password
Re-enter Password
A required, unique password for this OpenSSO agent, which can be assigned
during this registration process. The entry will appear in obfuscated format in
the console, in oam-config.xml, and in OpenSSOAgentBootstrap.properties.
When a registered agent connects to an OAM Server, the user is prompted for
the password. The password is used for authentication to prevent unauthorized
agents from connecting and obtaining policy information.
Host Identifier A name that identifies the host and port for the OpenSSO agent.
Default: Agent Name
See Also: "About Virtual Web Hosting" on page 22-10.
Base URL The protocol, host, and port of the computer on which the OpenSSO agent is
installed.
For example, http://host.example.domain.com:port or
https://example.domain.com:port.
Understanding OpenSSO Agent Registration Parameters
28-12 Administrator's Guide for Oracle Access Management
OpenSSO Agent Properties
OpenSSO Agent properties are stored in the following files, which are updated during
agent registration and configuration changes and consumed during run time:
■OpenSSOAgentBootstrap.properties
■OpenSSOAgentConfiguration.properties
These files are stored on the console host (AdminServer) and must be relocated to the
OpenSSO Agent /config directory as shown in Table 28–6.
For details about the generated Application Domain for an Open SSO Agent, see
"Generated Artifacts: OpenSSO" on page D-10.
28.3.2 About the Expanded OpenSSO Agent Page and Parameters
This topic describes expanded OpenSSO Agent page that is available when managing
the agent using the Oracle Access Management Console.
During registration, only a small subset of available parameters is displayed to
streamline the process. Whether you registered the agent using the Oracle Access
Management Console or the remote registration utility, you can view the full agent
configuration page in the console. Default values populate the page after initial
registration and are displayed when you open the Agent's page, as shown in
Figure 28–3.
Auto Create Policies During agent registration, you can have authentication and authorization
policies created automatically. This option is checked (enabled) by default. The
agent name is used as the Application Domain name by default.
Default: Enabled
See Also: "Generated Artifacts: OpenSSO" on page D-10.
Notes: An Application Domain in Access Manager corresponds to a Realm in
OpenSSO. If you already have an Application Domain and policies, you can
simply add new resources to it. If you clear this option (no check), no
Application Domain or policies are generated automatically.
Table 28–6 Relocating OpenSSO Artifacts
From AdminServer . . . To OpenSSO Agent /config Directory
$<MW_HOME>/Oracle_
IDM1/oam/server/rreg/client/rreg/output
$Policy-Agent-base/AgentInstance-Dir/config/
Table 28–5 (Cont.) Elements on the New OpenSSO Agent Page
Element Description
Understanding OpenSSO Agent Registration Parameters
Registering and Managing Legacy OpenSSO Agents 28-13
Figure 28–3 Expanded OpenSSO Web Agent Registration Page
Information on the J2EE Agent registration page is nearly the same as details for Web
Agents. The J2EE Agent registration page is shown in Figure 28–4.
Understanding OpenSSO Agent Registration Parameters
28-14 Administrator's Guide for Oracle Access Management
Figure 28–4 Expanded OpenSSO J2EE Agent Registration Page
Table 28–7 describes all elements on expanded OpenSSO Agent registration pages.
Understanding OpenSSO Agent Registration Parameters
Registering and Managing Legacy OpenSSO Agents 28-15
Table 28–7 Expanded OpenSSO Agent Registration Elements
Element Description
Status The state of this agent registration: Enabled or Disabled.
Default: Enabled
See Also: Table 28–5, " Elements on the New OpenSSO Agent Page"
Filter mode
J2EE Agent Type
only
The Agent filter is installed within the protected application. It facilitates the enforcement of security
policies, governing the access to all resources within the protected application. Every application
protected by the J2EE Agent must have its deployment descriptors changed to reflect that it is configured
to use the agent filter. Applications that do not have this setting are not protected by J2EE the Agent and
might malfunction or become unusable if deployed on a deployment container where the Agent realm is
installed.
Filter modes must be set for the J2EE Agent by choosing one of the following options: SSO_ONLY or
URL_Policy.
Default: URL_Policy
■SSO_ONLY (Access Manager Authentication Only): Enables the least restrictive mode of operation
for the filter; the agent simply ensures that all users who try to access protected web resources are
authenticated.
■URL_Policy (Access Manager Authentication and Authorization): Enables the agent filter to enforce
URL policies. By default, with Web Agents, .com.sun.identity.agents.config.sso.onlyattribute is set to
"false".
Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)
1. End user requests access to an application or resource protected by OpenSSO Agent.
2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.
3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource
with OpenSSO session ID set in the response cookie.
4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by
OpenSSO Agent.
5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy
and enables SSO for the end user.
6. End user gets access to the protected application or resource.
Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode
1. End user requests access to an application or resource protected by OpenSSO agent.
2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.
3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource
with OpenSSO session ID set in the response cookie.
4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by
OpenSSO Agent.
5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy.
6. OpenSSO Agent sends Policy requests to OAM Server through the OpenSSO Proxy to ensure the
authenticated user is authorized to access the resource.
7. OpenSSO Proxy evaluates the Policies for the protected resource (using OAM Policy Engine) and
sends the Policy decision to the Agent:
Allow
or
Deny
.
8. End user gets access if the Policy decision is
Allow
.
Note: The following Filter Modes are not supported: NONE, J2EE_Policy, All.
See Also: "Understanding OpenSSO Agent Registration Parameters" on page 28-10.
Session Timeout in
seconds (User)
Click the arrows to specify the period, after which the session times out and the user must
re-authenticate. You must set "Max Sessions" to a non-zero value to enable this setting.
Default: 0
Max Sessions Maximum number of sessions allowed per user.
Default: 0
Cookie Name The default name of the OpenSSO cookie is:
Default: iPlanetDirectoryPro
Cookie Separator Defines the character to be used as a separator when multiple values of the same attribute are being set as
a cookie. For example, the pipe symbol "|", can be used.
Default:
Understanding OpenSSO Agent Registration Parameters
28-16 Administrator's Guide for Oracle Access Management
Enable Cookie
Encoding
J2EE-type Agent
Only
Identifies whether cookie encoding is enabled or not.
Default: Enabled
SSO Only
Web-type Agent
Only
Enables OpenSSO Agent to bootstrap and authenticate with the OAM Server using the OpenSSO proxy
provided by Access Manager:
The end user accesses the application or resource protected by the OpenSSO Agent, which redirects the
unauthenticated user to the OAM Server for authentication.
After successful authentication, the OpenSSO proxy redirects the user back to the protected application or
resource and sets the OpenSSO Session ID in the response cookie.
The authenticated user with a valid OpenSSO session accesses the application or resource protected by
the OpenSSO Agent, which validates the session against the OAM Server using the OpenSSO Proxy.
The end user gets access based on Access Manager authorization policy.
Urls
Login URLs Enter the login URL, which must include the appropriate protocol (HTTP or HTTPS), host, domain, and
port in the following form:
http://example.domain.com:port
Default:
http://oamhost:port/opensso/UI/Login
Note: The port number is optional.
Logout URLs The Logout URL triggers the logout handler, which requires the user to re-authenticate the next time he
accesses a resource protected by Access Manager.
When yo enter the Logout URL, it must include the appropriate protocol (HTTP or HTTPS), host,
domain, and port. For example:
http://example.domain.com:port/opensso/UI/Logout
Default: http://oamhost:port/opensso/UI/Logout
Note: The port number is optional. The user must be logged out from resources protected by other agents
(WebGate and MOD_OSSO, for instance). Agent logout is not required other than in the multi-domain
environment.
Not enforced URLs
Web-type Agent
Only
The URLs you enter in this list have no policy enforcement. These equate to Public URLs, with no
protection and access is allowed by all.
Access Denied URI The URI to which the user is directed if access to the requested resource is denied. This is available for
both Web and J2EE Agents, each with its own format requirements:
Web Agent (full URL): http://host:port/context/accessDeniedURL.html
J2EE Agent (relative URI): /context/accessDeniedURL.htm
Default: (blank)
Audit
Debug Level
J2EE-type Agent
Only
When set, the OAM Server logs messages for:
■Login success and login failure events
■Logout success and logout failure events
■Log messages at different logging levels (ERROR, WARNING, MESSAGE, each of which indicates
severity in descending order.
Default: Error
See Also: Chapter 7, "Logging Component Event Messages"
Debug Directory
J2EE-type Agent
Only
The filesystem directory path for audit logs from the OAM Server:
■Audit Login events
■Audit Logout success events
See Also: Chapter 8, "Auditing Administrative and Run-time Events"
Debug File
Web-type Agent
Only
Defines the filesystem directory path to the local component event logging file.
Default:
Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element Description
Understanding OpenSSO Agent Registration Parameters
Registering and Managing Legacy OpenSSO Agents 28-17
Local Log File Defines the filesystem directory path to the local component event logging file.
Default:
User Mapping
Mapping Mode ■HTTP_HEADER
■USER_ID
■PROFILE_ATTRIBUTE
■SESSION_PROPERTY
Default: User_ID
User Identity Default: User ID
User Attribute
Name
Default:
Attribute Mapping Attribute retrieval fetches and sets user attributes in the HTTP request for consumption by the
applications.
The following Attribute Mapping panels are available:
■Profile Attributes
■Response Attributes
■Session Attributes
Fetch Mode: Certain applications rely on the presence of user-specific profile information in some form to
process user requests appropriately. The agent can make these attributes from the user's profile available
in various forms. when you specify a Fetch Mode for Profile, Response, or Session Attributes:
■NONE: No attributes are fetched.
■HTTP_HEADER: When the agent is configured to provide the LDAP attributes as HTTP headers,
these attributes can be retrieved.
■REQUEST_ATTRIBUTE: When the agent is configured to provide the LDAP attributes as request
attributes, the agent populates these attribute values into HttpServletRequest as attributes that can
later be used by the application as necessary. For example, fetch profile attributes, assign a mode to
the profile attribute property, and map the profile attributes to be populated under specific names
for the currently authenticated user.
■HTTP_COOKIE: When the agent is configured to provide the LDAP attributes as cookies, the
necessary values are set as server specific cookies by the agent with the path specified as "/."
Multi-valued attributes are set as a single cookie value such that all values of the attribute are
concatenated into a single string using a separator character that can be specified by the property
labeled Cookie Separator.
Default: None
Profile Attributes User profile information can be populated under specific names for the currently authenticated user. For
example:
Fetch Mode: REQUEST_ATTRIBUTE
Name (Map key): cn
Value: CUSTOM-Common-Name
Name (Map key): mail
Value: CUSTOM-Email
Default: No data
Response Attributes Obtains user-specific information by fetching policy response attributes, assigns a mode to the policy
response attribute property, and maps the policy response attributes to be populated under specific
names for the currently authenticated user.
Fetch Mode: REQUEST_ATTRIBUTE
Name (Map key): cn
Value: CUSTOM-Common-Name
Name (Map key): mail
Value: CUSTOM-Email_Addr
Default: No data
Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element Description
Understanding OpenSSO Agent Registration Parameters
28-18 Administrator's Guide for Oracle Access Management
Session Attributes The attributes in the session object maintained by the OAM Server. These are sent as part of a session
validation response to the Agents.
Fetch Mode: REQUEST_ATTRIBUTE
Name (Map key): UserToken
Value: CUSTOM-userid
Default: No data
Miscellaneous Most agent properties are hot-swap enabled. Changing configuration properties can have unexpected
results. Hot-swappable properties take effect immediately. Therefore, mistakes are instantly
implemented.
Most agent properties are presented in a format that is most useful for configuring using Oracle Access
Management Console. However, this format is not used in the OpenSSOAgentBootstrap.properties file.
List Properties: Certain properties are specified as lists composed of a key that represents the property
name; a positive number (starting from 0) that increments by 1 for every value specified in the list; and a
value. For example:
com.sun.identity.agents.config.notenforced.uri[0]=/agentsample/public/*
com.sun.identity.agents.config.notenforced.uri[1]=/agentsample/images/*
com.sun.identity.agents.config.notenforced.uri[2]=/agentsample/index.html
Map Constructs: Certain properties are specified as map constructs composed of a key that represents the
property name; a name string that forms the lookup key as available in the map; and the value associated
with the name in the map. For example:
com.sun.identity.agents.config.filter.mode[app1]=ALL
com.sun.identity.agents.config.filter.mode[app2]=SSO_ONLY
Note: For a given name, there can only be one entry in the configuration for a given configuration key. If
multiple entries with the same <name> for a given configuration key are present only one of the values
will be loaded in the system and the other values are discarded.
Application-Specific Properties: Certain properties can be configured for specific applications. Thee
agent can use different values of the same property for different applications as defined in the
configuration file. Application Specific configuration properties must follow the rules and syntax of the
map construct. The following settings for a single property serve as an example which illustrates that for
applications other than the ones deployed on the root context and the context /Portal, the value of the
property defaults to value3.
com.sun.identity.agents.config.example[Portal] = value1
com.sun.identity.agents.config.example[DefaultWebApp] = value2
com.sun.identity.agents.config.example = value3
Global Properties: Properties that are not configured for specific applications apply to all the applications
on that deployment container. Such properties are called global properties.
Serial number: Assigned automatically
Name: Select from one of the following
Valu e: Enter the appropriate value for the Name you chose.
Note: To enable OpenSSO Agent configuration hotswap, make sure the opensso agents have the
following properties in the Miscellaneous properties section of their profile in the OpenSSO Proxy on
OAM Server, and the agent servers are restarted:
J2ee Agents:
com.sun.identity.client.notification.url =http://
<
AGENT_SERVER_HOST
>:<
AGENT_
SERVER_PORT
>
/agentapp/notification
Web Agents:
com.sun.identity.client.notification.url =http://AGENT_SERVER_HOST
:
AGENT_SERVER_
PORT
/
UpdateAgentCacheServlet?shortcircuit=false
Not Supported, Web Agents:
com.sun.identity.agents.config.change.notification.enable = true
See Also: "Reviewing OpenSSO Bootstrap Configuration Mappings"
Element Description
Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element Description
Registering and Managing OpenSSO Agents Using the Console
Registering and Managing Legacy OpenSSO Agents 28-19
28.4 Registering and Managing OpenSSO Agents Using the Console
This topic provides the following topics:
■Registering an OpenSSO Agent using the Oracle Access Management Console
■Configuring and Managing Registered OpenSSO Agents Using the Console
See Also: Table 28–5, " Elements on the New OpenSSO Agent Page"
Status The state of this agent registration: Enabled or Disabled.
Default: Enabled
Filter mode
J2EE Agent Type
only
The Agent filter is installed within the protected application. It facilitates the enforcement of security
policies, governing the access to all resources within the protected application. Every application
protected by the J2EE Agent must have its deployment descriptors changed to reflect that it is configured
to use the agent filter. Applications that do not have this setting are not protected by J2EE the Agent and
might malfunction or become unusable if deployed on a deployment container where the Agent realm is
installed.
Filter modes must be set for the J2EE Agent by choosing one of the following options: SSO_ONLY or
URL_Policy.
Default: URL_Policy
■SSO_ONLY (Access Manager Authentication Only): Enables the least restrictive mode of operation
for the filter; the agent simply ensures that all users who try to access protected web resources are
authenticated.
■URL_Policy (Access Manager Authentication and Authorization): Enables the agent filter to enforce
URL policies. By default, with Web Agents, .com.sun.identity.agents.config.sso.onlyattribute is set to
"false".
Process overview: Authentication Only (SSO_ONLY J2EE Filter Mode)
1. End user requests access to an application or resource protected by OpenSSO Agent.
2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.
3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource
with OpenSSO session ID set in the response cookie.
4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by
OpenSSO Agent.
5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy
and enables SSO for the end user.
6. End user gets access to the protected application or resource.
Process overview: Authentication and Authorization with URL_Policy J2EE Filter Mode
1. End user requests access to an application or resource protected by OpenSSO agent.
2. OpenSSO Agent redirects this un-authenticated user to OAM Server for authentication.
3. After successful authentication, OpenSSO Proxy redirects the user back to the protected resource
with OpenSSO session ID set in the response cookie.
4. Authenticated end user with valid OpenSSO session, accesses application or resource protected by
OpenSSO Agent.
5. OpenSSO Agent validates the OpenSSO Session against OAM Server through the OpenSSO Proxy.
6. OpenSSO Agent sends Policy requests to OAM Server through the OpenSSO Proxy to ensure the
authenticated user is authorized to access the resource.
7. OpenSSO Proxy evaluates the Policies for the protected resource (using OAM Policy Engine) and
sends the Policy decision to the Agent:
Allow
or
Deny
.
8. End user gets access if the Policy decision is
Allow
.
Note: The following Filter Modes are not supported: NONE, J2EE_Policy, All.
See Also: "Understanding OpenSSO Agent Registration Parameters" on page 28-10.
Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element Description
Registering and Managing OpenSSO Agents Using the Console
28-20 Administrator's Guide for Oracle Access Management
28.4.1 Registering an OpenSSO Agent using the Oracle Access Management Console
Users with Oracle Access Management Administrator credentials can either use
Oracle-provided tools to analyze and migrate an OpenSSO environment or use the
Oracle Access Management Console, as described here, to manually provision
OpenSSO Agents.
Registration steps are the same regardless of the OpenSSO agent type you choose: Web
or J2EE. You can register an OpenSSO agent before you deploy it. Users with valid
Administrator credentials can perform the following task to register an OpenSSO
agent using the Oracle Access Management Console.
After agent registration, you can change the communication mode of the OAM Server
if needed. Communication between the agent and server continues to work as long as
the Agent uses SSO Only filter mode.
Prerequisites
Confirm that at least one OAM Server is running in the same mode as the agent to be
registered. Install the Agent, as described in:
■Oracle Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents
■Oracle Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents
To register an OpenSSO agent using the console
1. In the Oracle Access Management Console, click Application Security at the top of
the window.
2. In the Application Security Console, select Create OpenSSO Agent from the
Create (+) menu in the Agents section.
3. On the Create OpenSSO Agent page, enter required details (with an *)
(Table 28–5).
4. Confirm that the Auto Create Policies box is checked (or clear the box to disable
this function if you do not need a new Application Domain).
5. Click Apply to submit the registration (or close the page without submitting it):
6. Check the Confirmation window for the location of generated artifacts and then
close the window.
7. In the navigation tree, confirm the Agent name is listed.
8. Copy OpenSSO Agent bootstrap and configuration files from the console host
(AdminServer) to the Agent host Web server:
Note: Only centralized configuration mode is supported for new
OpenSSO Agent creation.
See Also: "Understanding OpenSSO Agent Registration Parameters"
OpenSSO Properties Files From ... Path ...
From the AdminServer (Console) host $DOMAIN_HOME/output/$Agent_Name/
■OpenSSOAgentBootstrap.properties
■OpenSSOAgentConfiguration.properties
Registering and Managing OpenSSO Agents Using the Console
Registering and Managing Legacy OpenSSO Agents 28-21
9. Restart the OAM Server hosting the Agent.
10. Proceed to the following topics, as needed:
■"Configuring and Managing Registered OpenSSO Agents Using the Console"
■Part VI, "Managing Access Manager SSO, Policies, and Testing"
28.4.2 Configuring and Managing Registered OpenSSO Agents Using the Console
Steps in this procedure are the same whether you are editing (view, modify, or delete)
a J2EE or Web type OpenSSO agent. Users with valid Administrator credentials can
change any setting for a registered agent using the Oracle Access Management
Console.
After changes, updated details are propagated through a runtime configuration
update process. There is usually no need to copy the artifacts over to OpenSSO agent
configuration area. Artifacts need only be copied to the OpenSSO agent directory path
if the agent name, password, or security mode is changed.
Prerequisites
The agent must be registered and the registration visible in the Oracle Access
Management Console. The AdminServer and one OAM Server must be running.
To view or modify registration details (or delete a registration)
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
a. In the Application Security console, click Agents to display the Agents Search
page.
b. Find a Registration: Fill in the form (Agent Name or Agent Type or both) or
simply click the Search button.
c. Open a Registration: Click the Agent name in the results table to open the
page.
2. Modify Existing Details:
a. Add or modify agent details as desired (Table 28–5).
b. Click Apply to submit changes, then dismiss the Confirmation window.
To the OpenSSO Agent host Web server $OHS_
dir/config.
For example:
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/
Note: Deleting an agent registration removes only the registration
(not the associated host identifier, Application Domain, resources, or
the agent instance itself), which prevents registering the same agent
again if required. However, deleting the Application Domain and its
content removes all referenced objects including the Agent
registration, as described in "Deleting an Application Domain and Its
Contents" on page 25-13.
See Also: "About the Expanded OpenSSO Agent Page and
Parameters" on page 28-12
OpenSSO Properties Files From ... Path ...
Performing Remote Registration for OpenSSO Agents
28-22 Administrator's Guide for Oracle Access Management
c. Copy OpenSSO Agent configuration files only if the Agent name, password,
or security mode was changed.
3. Delete OpenSSO Agent Registration: This does not remove the Agent instance
itself, only the registration page from the console.
a. Close the agent's registration page if it is open.
b. Click the desired agent's name, click the Delete button in the tool bar, and
confirm the removal in the Confirmation window.
c. Confirm the Agent name is absent in the navigation tree.
4. Restart the OAM Server hosting the Agent.
5. Proceed to Part VI, "Managing Access Manager SSO, Policies, and Testing".
28.5 Performing Remote Registration for OpenSSO Agents
This section provides a brief review of remote registration using the Oracle-provided
tool: oamreg. this section provides the following topics:
■Understanding Request Templates for OpenSSO Agent Remote Registration
■Reviewing OpenSSO Bootstrap Configuration Mappings
■Performing In-Band Remote Registration with OpenSSO Agents
■Performing Out-of-Band Remote Registration with OpenSSO Agents
28.5.1 Understanding Request Templates for OpenSSO Agent Remote Registration
Each OpenSSO Agent provides restricted access to applications by intercepting
requests to these applications. OpenSSO Agent provisioning is the process of
registering an OpenSSO agent to use Access Manager.
Both
inband
and
outofband
remote registration modes require a request file with the
input argument, as listed in Table 28–8
Remote OpenSSO Agent registration automatically:
Table 28–8 OpenSSO Request Files for Remote Registration
Templates for . . . Description
Register OpenSSO Agents $OAM_REG_HOME/input/OpenSSORequest.xml
$OAM_REG_HOME/input/OpenSSORequest_short.xml
When you run oamreg with the short request, default values are
applied automatically for elements found only in the extended
request.
Other Templates
Update Agent: $OAM_REG_HOME/input/OpenSSOUpdateAgentRequest.xml
See Also: "Updating Agents Remotely" on page 15-38
Create Policies:
Create New Host Identifiers and
an Application Domain without
Registering an Agent
$OAM_REG_HOME/input/CreatePolicyRequest.xml
See Also: "Managing Policies and Application Domains Remotely" on
page 25-82
Update Policies:
Existing Host Identifiers and
Application Domain (not
associated with an Agent
Registration)
$OAM_REG_HOME/input/UpdatePolicyRequest.xml
See Also: "Managing Policies and Application Domains Remotely" on
page 25-82
Performing Remote Registration for OpenSSO Agents
Registering and Managing Legacy OpenSSO Agents 28-23
■Creates the agent page for the Oracle Access Management Console
■Creates an Application Domain and basic policies to protect applications
■Produces OpenSSO properties files on the client to be consumed by the agent at
run time
Table 28–9 identifies the elements in OpenSSO Agent request templates. Unless
explicitly stated, all elements are found in both the short and the extended request
files.
Table 28–9 OpenSSO Agent Remote Registration Request
Element Description Example
<serverAddress>
<agentName>
<hostIdentifier>
<agentBaseUrl>
<autoCreatePolicy>
<applicationDomain>
<virtualhost>
Elements common to all remote
registration request templates.
See Table 15–8, " Common
Elements in Remote Registration
Requests"
<agentType> Choose between J2EE or Web type
OpenSSO agents.
<agentType>WEB</agentType>
Password
Re-enter Password
A required, unique password for this
OpenSSO agent, which can be assigned
during this registration process. The
entry will appear in obfuscated format
in the console, in oam-config.xml, and
in OpenSSOAgentBootstrap.properties.
When a registered agent connects to an
OAM SServer, the user is prompted for
the password. The password is used
for authentication to prevent
unauthorized agents from connecting
and obtaining policy information.
You are asked to supply a
password during remote
registration. This does not appear
in the template.
Extended OpenSSO Template
Only
<agentDebugDir> With <debug> set to true, you can
configure the directory path for logged
agent messages.
Default: None
See Also: Chapter 7, "Logging
Component Event Messages"
<agentDebugDir>/scratch/debug
</agentDebugDir>
<agentAuditDir> Defines the directory path for audit
logs from the OAM Server:
■Audit Login events
■Audit Logout success events
See Also: Chapter 8, "Auditing
Administrative and Run-time Events"
<agentAuditDir>/scratch/audit
</agentAuditDir>
<agentAuditFileName> Defines the audit log file name.
<agentAuditFileName>audit.log
</agentAuditFileName>
Performing Remote Registration for OpenSSO Agents
28-24 Administrator's Guide for Oracle Access Management
28.5.2 Reviewing OpenSSO Bootstrap Configuration Mappings
This section describes the bootstrap configuration mappings of an OpenSSO Agent.
■Table 28–10, " J2EE Request File Mappings to the Properties File"
■Table 28–11, " Mapping the Web Request File to the Properties File"
<debug> When set to
true
, the OAM Server logs
messages for:
■Login success and login failure
events
■Logout success and logout failure
events
■Log messages at different logging
levels (FATAL, ERROR,
WARNING, DEBUG, TRACE),
each of which indicates severity in
descending order.
Default: false
See Also: Chapter 7, "Logging
Component Event Messages"
<debug>false</debug>
<cookieName> The name of the cookie, which the
agent finds this cookie after the
OpenSSO Proxy triggers session
validation
The end user has the following valid
cookies:
■OAM_ID cookie (represents the
end user session after agent
authentication)
■OpenSSO cookie
<cookieName>iPlanetDirectoryP
ro</cookieName>
<accessDeniedUrl> If access is denied, the user is
redirected to this URL.
<accessDeniedUrl></accessDeni
edUrl>
<protectedAuthnScheme> Specifies the Authentication Scheme to
use in the Authentication Policy.
In an upgraded environment, use
SSOCoExistMigrateScheme for the
Protected Resource Policy for any new
OSSO Agents you register.
<protectedAuthnScheme></prote
ctedAuthnScheme>
Table 28–10 J2EE Request File Mappings to the Properties File
Property Name Default Value Sample Value
com.iplanet.am.naming.url from input xml as
<serverAddress>/opensso/nami
ngservice
http://example.com:7575/opensso/nami
ngservice
com.sun.identity.agents.app.username from input xml as <agentName> <Agent registration ID>
com.iplanet.am.service.secret from input xml as
<agentPassword>
Note: This is not collected as part
of the input XML file but is
prompted for by the remote
registration tool.
<Encrypted Agent registration ID
password>
com.iplanet.services.debug.directory from input xml as
<agentDebugDir>
/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/debug
Table 28–9 (Cont.) OpenSSO Agent Remote Registration Request
Element Description Example
Performing Remote Registration for OpenSSO Agents
Registering and Managing Legacy OpenSSO Agents 28-25
Table 28–11 shows the mappings between a Web Agent request file and properties file.
28.5.3 Performing In-Band Remote Registration with OpenSSO Agents
This is a brief summary of tasks required to perform in-band remote registration for
your OpenSSO agent. Full details are provided in other chapters, as described here.
Prerequisites
"Introduction to Remote Registration" on page 14-8
com.sun.identity.agents.config.local.logfile from input xml as
<agentAuditDir>/<agentAuditFil
eName>
/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/audit/amAgent_
example_com_7676.log
com.sun.identity.agents.config.organization.name from input xml as <realmName>
Note: This is the <hostIdentifier>
value collected from the input
xml file. By default it is taken as
the <agentName> unless
explicitly provided.
com.sun.identity.agents.config.profilename from input xml as <agentName> <Agent registration ID>
Not included in the remote registration file ...
com.iplanet.am.naming.url N/A N/A
com.sun.identity.agents.config.service.resolver N/A N/A
com.sun.services.debug.mergeall N/A
N/A
com.sun.identity.agents.config.lock.enable FALSE
N/A N/A
am.encryption.pwd N/A N/A
Table 28–11 Mapping the Web Request File to the Properties File
Property Name Default Value Sample Value
com.iplanet.am.naming.url from input xml as
<serverAddress>/<serverAddres
s>/opensso/namingservice
http://example.com:7575/opensso/nami
ngservice
com.sun.identity.agents.config.username from input xml as <agentName> <Agent profile ID>
com.sun.identity.agents.config.password from input xml as
<agentPassword>
Note: This is not collected as part
of the input XML file but is
prompted for by the remote
registration tool.
<Encrypted Agent registration ID
password>
com.iplanet.services.debug.directory from input xml as
<agentDebugDir>
/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/debug
com.sun.identity.agents.config.local.logfile from input xml as
<agentAuditDir>/<agentAuditFil
eName>
/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/audit/amAgent_
redsky_red_iplanet_com_7676.log
com.sun.identity.agents.config.organization.name from input xml as <realmName>
Note: It is the <hostIdentifier>
value collected from the input
xml. Status: Open Fixed or Closed
com.sun.identity.agents.config.profilename from input xml as <agentName>
Table 28–10 (Cont.) J2EE Request File Mappings to the Properties File
Property Name Default Value Sample Value
Performing Remote Registration for OpenSSO Agents
28-26 Administrator's Guide for Oracle Access Management
Task overview: In-band Administrators performing remote registration
1. Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
2. Create your input file with unique values for the agent and Application Domain as
described in "Creating Your Remote Registration Request" on page 15-34.
From: OpenSSORequest.xml
To: myopenssoagent_request.xml
3. Run the registration tool to configure the Agent, create a default Application
Domain for the resources, and copy the updated agent configuration file as
described in "Performing In-Band Remote Registration" on page 15-34.
From the console host (AdminServer):
/rreg/output/Agent_Name/
■OpenSSOAgentBootstrap.properties
■OpenSSOAgentConfiguration.properties
To the OpenSSO Agent host Web server $OHS_dir/config. For example:
$WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/
4. Validate the configuration as described in "Validating Remote Registration and
Resource Protection" on page 15-40.
5. Perform access checks to validate that the configuration is working, as described
in "Verifying Authentication and Access After Remote Registration" on page 15-40.
28.5.4 Performing Out-of-Band Remote Registration with OpenSSO Agents
This is a brief summary of tasks required to perform out-of-band remote registration
for your OpenSSO agent. Full details are provided in other chapters, as described here.
Prerequisites
"Introduction to Remote Registration" on page 14-8
Task overview: Out-of-band remote registration (Agent is outside the network)
1. Out-of-band Administrator: Creates a starting request input file containing
specific application and agent details and submits it to the in-band Administrator.
■Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
■Copy and edit a template to input unique values for the agent and Application
Domain as described in "Creating Your Remote Registration Request" on
page 15-34.
$OAM_REG_HOME/input/OpenSSORequest.xml
■Submit the starting request input file to the in-band Administrator using a
method you choose (email or file transfer).
2. In-band Administrator:
Updating Registered OpenSSO Agents Remotely
Registering and Managing Legacy OpenSSO Agents 28-27
■Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
■Use the out-of-band starting request with the registration tool to register the
agent and create the response and native agent configuration files to return to
the out-of-band Administrator. See "Performing Out-of-Band Remote
Registration" on page 15-35:
–opensso_Response.xml is generated for the out of band Administrator to
use in Step 3.
–OpenSSO properties files are modified for the out-of-band Administrator
to bootstrap the OSSO module.
3. Out-of-band Administrator: Use the registration tool with the response file and
copy artifacts to the appropriate file system directory.
–opensso_Response.xml.
–opensso....properties files
4. In-band Administrator: Validates the configuration as described in "Validating
Remote Registration and Resource Protection" on page 15-40.
5. Out-of-band Administrator: Performs several access checks to validate that the
configuration is working, as described in "Verifying Authentication and Access
After Remote Registration" on page 15-40.
28.6 Updating Registered OpenSSO Agents Remotely
This section describes how to update, validate, and delete OSSO Agents using remote
registration templates and modes described in "Introduction to Updating Agents
Remotely" on page 15-37.
The update request file passes specific values to the remote registration tool, oamreg.
The primary differences between the update template and the original registration
template is that the update template.
Table 28–12 Delta: OpenSSO Remote Registration versus Remote Updates
Delta Element
Adds <startDate>yyyy_mm_dd</startDate> element to track changes
Adds <homeUrl> element that specifies the agent_base_url_port
Omits <hostidentifier>
Omits <agentbaseURL>
See Also:
■Table 28–7, " Expanded OpenSSO Agent Registration Elements"
■Updating OpenSSO Agents Remotely
Locating Other OpenSSO Agent Information
28-28 Administrator's Guide for Oracle Access Management
28.6.1 Updating OpenSSO Agents Remotely
To remotely update OAM 10g Agent registration
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. Update Agent:
a. Create your update request using the
OAMUpdateAgentRequest.xml
template.
b. On the computer hosting the Agent, run the following command with
agentUpdate
mode specify your own *Request*.xml as the input file. For
example:
./bin/oamreg.sh agentUpdate input/OpenSSOUpdateAgentRequest.xml
c. Provide the registration Administrator user name and password when asked.
d. Confirm success with on-screen messages.
e. Relocate to the agent host OpenSSOAgentBootstrap and
OpenSSOAgentConfiguration.properties files:
From the AdminServer (Console) host: /rreg/output/Agent_Name/
To the OpenSSO Agent host Web server $OHS_dir/config. For example:
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/*.properties
f. Restart the OAM Server that is hosting this agent
3. Validating Agent:
a. On the Agent host, run the following command in
agentValidate
mode. For
example:
./bin/oamreg.sh agentValidate agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
4. Deleting an Agent:
a. On the computer hosting the Agent, run the following
agentDelete
command.
For example:
./bin/oamreg.sh agentDelete agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
Success: On-screen message confirms
AgentDelete process completed successfully
!
28.7 Locating Other OpenSSO Agent Information
See Table 28–13 for additional information on legacy OpenSSO agents with Access
Manager.
Locating Other OpenSSO Agent Information
Registering and Managing Legacy OpenSSO Agents 28-29
Table 28–13 Other OpenSSO Information in this Guide
Topic Location
Component Loggers Table 7–3, " Oracle Access Management Server-Side Component
Loggers"
OpenSSO Metrics in the DMS
Console
"Monitoring OpenSSO Proxy Metrics" on page 11-12
Sessions and Session Management Chapter 16, "Maintaining Access Manager Sessions"
Artifacts "Generated Artifacts: OpenSSO" on page D-10
"Migrated Artifacts: OpenSSO" on page D-13
Locating Other OpenSSO Agent Information
28-30 Administrator's Guide for Oracle Access Management
29
Registering and Managing Legacy OSSO Agents 29-1
29
Registering and Managing Legacy OSSO
Agents
[24]
If legacy OracleAS SSO 10g is already in place as the enterprise solution for an existing
deployment, Oracle Fusion Middleware continues to support this as a solution.
Additionally, you can register existing OSSO 10g mod_osso modules as agents for
Access Manager as described in Chapter 14.
This chapter explains how to register or manage legacy OSSO agents for use with
Access Manager 11.1.2 and provides the following sections:
■Understanding OSSO Agents with Access Manager
■Registering OSSO Agents Using Oracle Access Management Console
■Configuring and Managing Registered OSSO Agents Using the Console
■Performing Remote Registration for OSSO Agents
■Updating Registered OSSO Agents Remotely
■Configuring Logout for OSSO Agents with Access Manager 11.1.2
■Locating Other OSSO Agent Information
29.1 Understanding OSSO Agents with Access Manager
This section provides the following topics:
■About OSSO Agents with Access Manager
■Comparing Access Manager 11g SSO versus OSSO 10g
29.1.1 About OSSO Agents with Access Manager
The mod_osso module is an Oracle HTTP Server module that simplifies the
authentication process by serving as the sole application to the single sign-on server. In
this way, mod_osso renders authentication transparent to OracleAS applications. It
enables applications protected by OracleAS Single Sign-On to accept HTTP headers in
lieu of a user name and password once the user has logged in. The values for these
headers are stored in a mod_osso cookie.
The Administrator for these applications is spared the burden of integrating them with
an SDK. After authenticating a user, mod_osso transmits the simple header values that
applications may use to authorize the user:
■User name
■User GUID (global user identity)
Understanding OSSO Agents with Access Manager
29-2 Administrator's Guide for Oracle Access Management
■Language and territory
After registration with Access Manager, OSSO 10g Agents can communicate directly
with Access Manager 11g services through the OSSO proxy. The OSSO proxy supports
existing OSSO agents when upgrading to Access Manager. The proxy handles requests
from OSSO Agents and translates the OSSO protocol into a protocol for Access
Manager 11g authentication services.
The OSSO Proxy supports inter-operability between Access Manager and OSSO agents
(using an OSSO agent to access a valid SSO session created for a Webgate or Access
Client and vice versa).
After registering 10g mod_osso as an agent, Access Manager gives mod_osso the
redirect URL for the user based on the authentication scheme associated with the
OAM policy defined for the resource (Table 29–1).
29.1.2 Comparing Access Manager 11g SSO versus OSSO 10g
This topic introduces key components for implementing and enforcing Access
Manager 11g single sign-on policies as compared to OSSO 10g. Access Manager 11g
default behavior is to deny access when a resource is not protected by a policy that
explicitly allows access. OracleAS SSO 10g provides only authentication. Table 29–2
summarizes the differences.
OSSO Proxy Supports Description
SSO login From an OSSO Agent to the OAM Server (and OSSO-specific tokens)
SSO logout From the OSSO Agent to the OAM Server
OSSO Agent requests
and protocols
OSSO Proxy translates the OSSO protocol into a protocol for Access Manager.
Table 29–1 OSSO Agents with Access Manager
Checks for an existing valid Oracle HTTP Server
cookie
Redirects to the OAM Server if needed to contact the
directory during authentication
Decrypts the encrypted user identity populated by
the OSSO server
Sets the headers with user attributes
Understanding OSSO Agents with Access Manager
Registering and Managing Legacy OSSO Agents 29-3
Table 29–2 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description 11g Access Manager OSSO 10g
Oracle Identity Management
Infrastructure
Enables secure, central management of
enterprise identities.
Enables secure, central management of
enterprise identities.
Agents
Resides with the relying parties and
delegate authentication and authorization
tasks to OAM Servers.
■11g OAM Agents
■10g OAM Agents
■10g OSSO Agents (mod_osso)
■OpenSSO Agents
Note: Nine Administrator languages are
supported.
■mod_osso (partner)
Note: The mod_osso module is an
Oracle HTTP Server module that
provides authentication to OracleAS
applications.
Servers
Notes: Administrative users access the
console home page by typing the URL:
https://host:port/oamconsole.
Non-administrative users first gain access
to the single sign-on server by entering
the URL of an application, which returns
the SSO login page.
■OAM Server
■Oracle Access Management Console
(installed on the WebLogic
Administration Server)
See Also:
"Understanding the Oracle Access
Management Console"
"Understanding Credential Collection
and Login"
■OracleAS SSO server (OSSO server)
See Also: Oracle Application Server Single
Sign-On Administrator's Guide.
Proxy
Provides support for legacy systems:
■OAM Proxy supports legacy Access
Manager implementations by acting
as a legacy Access Server.
■OSSO Proxy supports OSSO Agents
by acting as the legacy OSSO Server.
■Oracle-provided OpenSSO Proxy
handles requests for resources
protected by OpenSSO Agents
■OSSO Proxy supports legacy SSO
implementations by acting as the
legacy OSSO Server.
Console Oracle Access Management Console No console equivalent before Access
Manager 11g.
Protocols that secure information
exchange on the Internet
Front channel protocols exchanged
between Agent and Server:
HTTP/HTTPS.
11g Webgate secures information
exchange using the Agent key.
-See Also: Cryptographic keys.
N/A
Policy Store Database mod_osso and partner application
Applications An application that delegates
authentication and authorization to
Access Manager and accepts headers
from a registered Agent.
Note: External applications do not
delegate authentication. Instead, these
display HTML login forms that ask for
application user names and passwords.
For example, Yahoo! Mail is an external
application that uses HTML login forms.
An application that delegates
authentication to mod_osso and the
OracleAS Single Sign-On server.
Note: After registering mod_osso with
Access Manager 11g, mod_osso delegates
authentication to OAM.
The mod_osso module enables the
applications to accept authenticated user
information once the user is logged in. Re
authenticating is avoided by accepting
headers from the registered OSSO Agent.
The application is responsible for
determining whether the authenticated
user is authorized to use the application.
Understanding OSSO Agents with Access Manager
29-4 Administrator's Guide for Oracle Access Management
SSO Engine Manages the session lifecycle, facilitates
global logout across all relying parties in
the valid session, and provides consistent
service across multiple protocols.
Uses Agents registered with Access
Manager 11g:
■Authentication (credential
collection) occurs across the HTTP
(HTTPS) channel
■Authorization occurs across the
Oracle Access Protocol (OAP)
channel
■mod_osso delegates authentication
only and communicates exclusively
through the HTTP channel.
Cryptographic keys ■During 11g agent registration, a key
is generated for the agent and also
shared with the OAM Server
The key is used for encrypting and
decrypting SSO cookies
■During 10g agent registration, a
global shared secret key is generated
across all of Access Manager 11g (all
Agents and OAM Servers).
■During OSSO agent registration,
One key per partner shared between
mod_osso and OSSO server.
■OpenSSO Agent: Host- or
Domain-based key stored locally in
bootstrap file on Agent host.
■During OAM Server installation,
one OAM Server key is generated
Note: One key is generated and used per
registered mod_osso Agent. However,
one single key is generated for all 10g
Webgates.
■One key per partner shared between
mod_osso and OSSO server
■OSSO server's own key
■One global key per OSSO setup for
the GITO domain cookie
Keys storage ■Agent side: A per-agent key is
stored locally in the Oracle Secret
Store in a wallet file
■OAM Server side: A per- agent key,
and server key, are stored in the
credential store on the server side
■Security Token Service
■mod_osso side: partner keys and
GITO global key stored locally in
obfuscated configuration file
■OSSO server side: partner keys,
GITO global key, and server key are
all stored in the directory server
Cookies
See Also: Table 21–6
and
"About Single Sign-On Cookies During
User Login"
Host-based authentication cookie:
■11g Webgate, One per agent:
OAMAuthnCookie_<host:port>_
<random number>
■10g Webgate, One ObSSOCookie for
all 10g Webgates.
■One for the OAM Server: OAM_ID
(Table 21– 6)
■Host-based authentication cookie:
one per partner: OHS-host-port
one for OSSO server: (not with
Access Manager 11g)
■Domain-level session cookie for
global inactivity timeout (GITO) if
enabled
Policies Registered agents rely on Access
Manager authentication, authorization,
and token issuance policies to determine
who gets access to protected applications
(defined resources).
mod_osso uses only Access Manager 11g
authentication policies to determine who
gets access to defined resources.
mod_osso provides authentication only.
Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description 11g Access Manager OSSO 10g
Understanding OSSO Agents with Access Manager
Registering and Managing Legacy OSSO Agents 29-5
Client IP ■Maintain this Client IP, and include
it in the host- based
OAMAuthnCookie.
■Include the original client IP inside
the host cookie.
In later authentication requests,
when the cookie is presented, the
original client IP is compared with
the presenter's IP.
Rejection occurs if there is no match
Encryption / Decryption (converting
encrypted data back into original form)
Introduces client-side cryptography and
ensures that cryptography is performed
at both the agent and server ends:
1. Webgate encrypts obrareq.cgi using
the agent key.
Note: obrareq.cgi is the
authentication request in the form of
a query string redirected from
Webgate to OAM Server.
2. OAM Server decrypts the request,
authenticates, creates the session,
and sets the server cookie.
3. OAM Server also generates the
authentication token for the agent
(encrypted using the agent key),
packs it in obrar.cgi with a session
token (if using cookie-based session
management), authentication token
and other parameters, then encrypts
obrar.cgi using the agent key.
Note: obrar.cgi is the authentication
response string redirected from the
OAM Server to Webgate.
4. Webgate decrypts obrar.cgi, extracts
the authentication token, and sets a
host-based cookie.
Cryptography is performed at both mod_
osso and OSSO server:
1. site2pstore token (request from
mod_osso to server) is encrypted
using the partner key locally at
mod_osso.
2. OSSO server decrypts site2pstore
token, authenticates, and generates
its own cookie.
3. urlc token (the response from OSSO
server to mod_osso) is encrypted
using the partner key at the server.
4. mod_osso decrypts the urlc token
locally and re-encrypts using its
own format to set in a host-based
cookie.
Session Management ■Session idle timeout behavior is
supported through the 11g Session
Management Engine (SME).
■Single domain supported through a
domain-level cookie for global
inactivity timeout (GITO).
Multi-domain SSO: After a user
logs in to one domain, and then goes
to a different domain, he is
considered idle from the first
domain. When the idle times out on
the original domain, the user must
re-authenticate on the original
domain.
Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description 11g Access Manager OSSO 10g
Registering OSSO Agents Using Oracle Access Management Console
29-6 Administrator's Guide for Oracle Access Management
29.2 Registering OSSO Agents Using Oracle Access Management
Console
This section describes how to manage OSSO Agent registrations (mod_osso) using the
Oracle Access Management Console. For details, see:
■Understanding the Create OSSO Agent Registration Page and Parameters
■Registering an OSSO Agent (mod_osso) Using the Console
29.2.1 Understanding the Create OSSO Agent Registration Page and Parameters
This topic describes OSSO Agent registration using the Oracle Access Management
Console.
Figure 29–3 shows a Create OSSO Agent page, under the System Configuration tab in
the Oracle Access Management Console.
Response token replay prevention ■Include RequestTime (the timestamp
just before redirect) in obrareq.cgi
and copy it to obrar.cgi to prevent
response token replay.
■Include RequestTime (timestamp
just before redirect) in the
site2pstore token and copy it to the
urlc token to prevent token replay.
Multiple network domain support Access Manager 11g supports
cross-network-domain single sign-on out
of the box.
Oracle recommends you use Oracle
Federation for this situation.
N/A
Centralized log-out ■The
logOutUrls
(10g Webgate
configuration parameter) is
preserved. 10g logout.html requires
specific details for Access Manager
11g.
■11g Webgate parameters are new:
Logout Redirect URL
Logout Callback URL
Logout Target URL
See Chapter 27.
There is no change required for Access
Manager 11g with mod_osso (OSSO
Agents).
Applications that use dynamic directives
require no entry in mod_osso.conf.
Instead, protection is written into the
application as one or more dynamic
directives.
See Chapter 27.
See Also: "Understanding Credential Collection and Login"
Note: Before you register an OSSO Agent, ensure that the Oracle
HTTP Server is installed on the client computer and that the Web
server is configured for mod_osso.
Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description 11g Access Manager OSSO 10g
Registering OSSO Agents Using Oracle Access Management Console
Registering and Managing Legacy OSSO Agents 29-7
Figure 29–1 Create OSSO Agent Page
On the Create OSSO Agent page, required information is identified by the asterisk (*).
Table 29–3 describes the required and optional details that you can specify when you
register a new agent.
To help streamline Agent registration, several elements are concealed and default
values are used during registration with the console. When you view an agent's
registration page in the Oracle Access Management Console, all elements and values
are revealed as described in "Understanding the Expanded OSSO Agent Page in the
Console" on page 29-9.
OSSO Agent Configuration File
The OSSO Agent configuration file, osso.conf, is updated during agent registration
and configuration changes. It is stored on the console host (AdminServer). Following
Table 29–3 Create OSSO Agent Page Elements
Element Description
Name The identifying name for this mod_osso Agent.
Token Version The default version of the token is 3.0; the following options are available:
■1.2
■1.4
■3.0
Base URL
Required for OSSO
agents.
The required protocol, host, and port of the computer on which the Web server for
the agent is installed. For example, http://host.example.domain.com:port or
https://example.domain.com:port.
Note: The host and port are used as defaults for the expanded registration. See
Table 29–5.
Admin ID Optional Administrator log in ID for this mod_osso instance. For example,
SiteAdmin.
Admin Info Optional Administrator details for this mod_osso instance. For example, Application
Administrator.
Host Identifier The host identifier is filled in automatically based on the Agent name.
Auto Create Policies During agent registration, you can have authentication and authorization policies
created automatically. This option is checked (enabled) by default.
The OSSO Proxy requires an Application Domain that includes a resource with the
generic URL (/**) protected by a policy based on the LDAP scheme (default). This is
why a generic URL is used at the server side.
Default: Enabled
Notes: If you already have a domain and policies registered, you can simply add
new resources to it. If you clear (uncheck) this option, no Application Domain or
policies are generated automatically.
In an upgraded deployment, you must change the Authentication Scheme in your
Authentication Policy to use SSOCoExistMigrateScheme.
Registering OSSO Agents Using Oracle Access Management Console
29-8 Administrator's Guide for Oracle Access Management
registration or configuration updates, you must relocate the artifacts to the mod_osso
directory path on the Agent host as shown in Table 29–4.
29.2.2 Registering an OSSO Agent (mod_osso) Using the Console
Users with Oracle Access Management Administrator credentials can perform the
following procedure to register an OSSO Agent using the Oracle Access Management
Console.
Prerequisites
Ensure that the Oracle HTTP Server is installed and running on the client computer,
and is configured for mod_osso.
To register an OSSO Agent
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, select Create OSSO Agent from the Create (+)
drop-down list in the Agents section.
3. On the Create OSSO Agent page, enter required details, as shown in Table 29–3:
■Name
■Base URL
4. Select the desired Token Version, and enter optional details as desired (Table 29–3).
5. Click Apply to submit the registration (or close the page without applying
changes).
6. In the Confirmation window, check the path to generated artifacts and then close
the window. For example:
Artifacts are generated in following location : /.../base_domain/output/$Agent_
Name
7. Copy the
osso.conf
file from the console host (AdminServer) to the Agent host
Web server. For example:
8. In an upgraded deployment, change the Authentication Scheme in the Protected
Resources Policy to use SSOCoExistMigrateScheme.
9. Restart the OAM Server hosting the Agent.
Table 29–4 Relocating OSSO Artifacts
From AdminServer . . . To OHS_dir/osso.conf
$DOMAIN_HOME/output/$Agent_Name/ $WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/osso
See Also: Understanding the Create OSSO Agent Registration Page
and Parameters
osso.conf From ... Path ...
From the AdminServer (Console) host $DOMAIN_HOME/output/$Agent_Name/
To the mod_osso directory path on the Agent
host Web server: $OHS_dir/osso.conf.
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/oss
o.conf
Configuring and Managing Registered OSSO Agents Using the Console
Registering and Managing Legacy OSSO Agents 29-9
10. Proceed as needed:
■"Configuring and Managing Registered OSSO Agents Using the Console"
■Part VI, "Managing Access Manager SSO, Policies, and Testing"
29.3 Configuring and Managing Registered OSSO Agents Using the
Console
This section describes how to manage OSSO Agent registrations (mod_osso) using the
Oracle Access Management Console. For details, see:
■Understanding the Expanded OSSO Agent Page in the Console
■Searching for an OSSO Agent (mod_osso) Registration
■Viewing or Editing OSSO Agent (mod_osso) Registration
■Deleting an OSSO Agent (mod_osso) Registration
29.3.1 Understanding the Expanded OSSO Agent Page in the Console
During registration, only a subset of available parameters is displayed to streamline
the registration process. Whether you registered the agent using the Oracle Access
Management Console or the remote registration utility, you can view the full agent
configuration page in the console after registration. Default values populate
previously concealed elements, which are visible when you open the Agent's page, as
shown in Figure 29–2. The Confirmation window is still visible.
Figure 29–2 OSSO Agent Page and Confirmation Window
Table 29–5 summarizes the expanded elements and defaults that are used by the OSSO
Agent.
Table 29–5 Expanded OSSO Agent Elements
Element Description
Site Token The Application Token used by the partner when requesting authentication. This
cannot be edited.
Success URL The redirect URL to be used upon successful authentication. By default, osso_login_
success on the fully qualified host and port specified with the Base URL are used. For
example:
Default: https://example.domain.com:7001/osso_login_success
Configuring and Managing Registered OSSO Agents Using the Console
29-10 Administrator's Guide for Oracle Access Management
29.3.2 Searching for an OSSO Agent (mod_osso) Registration
When you first open the OSSO Agents node, the Search form appears. The Results
table lists all OSSO Agents. If there are too many to quickly locate the one you want,
you can use the controls to refine your search.
There are only two element on which you can refine an OSSO Agent search: The Agent
Name that assigned during registration or the Agent ID assigned by the system.
Prerequisites
The OSSO Agent must be registered to be available in the Oracle Access Management
Console.
To search for an OSSO Agent registration
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Agents.
3. In the Name field, enter criteria for your search (with or without including the
wild card (*)). For example:
my*
4. Click the Search button.
5. In the Search Results table:
■Crreate: Click the Create OSSO Agent button at the top of the Search page.
■Edt or View: Click the Edit command button in the tool bar to display the
configuration page.
■Delete: Proceed to "Deleting an OSSO Agent (mod_osso) Registration" on
page 29-11.
■Detach: Click Detach in the tool bar to expand the table to a full page.
■Reconfigure Table: Select a View menu item to alter the appearance of the
results table.
6. Apply any changes (or dismiss the page) when finished.
Failure URL The redirect URL to be used if authentication fails.By default, osso_login_failure on
the fully qualified host and port specified with the Agent Base URL are used:
Default: https://example.domain.com:7001/osso_login_failure
Start Date First month, day, and year for which log in to the application is allowed by the server.
Default: The date the Agent was registered.
Home URL The redirect URL to be used for the Home page after authentication. By default, the
fully qualified host and port specified with the Agent Base URL are used:
Default: https://example.domain.com:7001
Logout URL The redirect URL to be used when logging out. This redirects the user to the global
logout page on the server: osso_logout_success. By default, the fully qualified host
and port specified with the Agent Base URL are used:
Default: https://example.domain.com:7001/osso_logout_success
See Also: "Introduction to Centralized Logout for Access Manager 11g" on page 27-1.
Table 29–5 (Cont.) Expanded OSSO Agent Elements
Element Description
Configuring and Managing Registered OSSO Agents Using the Console
Registering and Managing Legacy OSSO Agents 29-11
29.3.3 Viewing or Editing OSSO Agent (mod_osso) Registration
Users with valid Administrator credentials can change any setting for a registered
OSSO Agent using the Oracle Access Management Console, as described in the
following procedure. For example, you might want to revise the end date or add
Administrator information.
Prerequisites
Ensure that the Oracle HTTP Server is installed and running on the client computer,
and is configured for mod_osso.
To view or modify an OSSO Agent registration
1. Find the Agent: See "Searching for an OSSO Agent (mod_osso) Registration".
2. View or Modify: On the registration page, view or modify details as needed
(Table 29–3 and Table 29–5).
3. Click Apply to submit the changes (or close the page without applying changes),
and close the Confirmation window.
4. Copy the
osso.conf
file from the console host (AdminServer) to the Agent host
Web server. For example:
5. Restart the OAM Server hosting the Agent.
6. Proceed to Part VI, "Managing Access Manager SSO, Policies, and Testing".
29.3.4 Deleting an OSSO Agent (mod_osso) Registration
Users with valid Administrator credentials can perform the following procedure to
delete a registered OSSO Agent from the Oracle Access Management Console.
Prerequisites
Evaluate the Application Domain, resources, and policies associated with this agent
and ensure that these are configured to use another agent or that they can be removed.
See Also:
■Understanding the Expanded OSSO Agent Page in the Console
osso.conf From ... Path ...
From the AdminServer (Console) host $DOMAIN_HOME/output/$Agent_Name/
To the mod_osso directory path on the Agent
host Web server: $OHS_dir/osso.conf.
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/oss
o.conf
Note: Deleting an agent registration removes only the registration
(not the associated host identifier, Application Domain, resources, or
the agent instance itself), which prevents registering the same agent
again if required. However, deleting the Application Domain and its
content removes all referenced objects including the Agent
registration, as described in "Deleting an Application Domain and Its
Contents" on page 25-13.
See Also: Searching for an OSSO Agent (mod_osso) Registration
Performing Remote Registration for OSSO Agents
29-12 Administrator's Guide for Oracle Access Management
To delete an OSSO Agent registration
1. Find the Agent: See "Searching for an OSSO Agent (mod_osso) Registration".
2. In the list of search results, select the desired agent and click Delete in the toolbar;
confirm the deletion when prompted.
29.4 Performing Remote Registration for OSSO Agents
This section provides a brief review of remote registration using the Oracle-provided
tool (oamreg) with OSSO Agents.
This section provides the following topics:
■Understanding Request Templates for OSSO Remote Registration
■Performing In-Band Remote Registration of OSSO Agents
■Performing Out-of-Band Remote Registration for OSSO Agents
29.4.1 Understanding Request Templates for OSSO Remote Registration
This topic provides the OSSO Registration Request for use with the remote registration
tool oamreg.sh (Linux) or oamreg.bat (Windows). The information highlighted in bold
must be modified for a mod_osso agent. However, all other fields can use the default
values.
Both
inband
and
outofband
remote registration modes require a request file with the
input argument, as listed in Table 29–6.
Table 29–7 describes elements in the OSSO request file: OSSORequest.xml.
Table 29–6 OpenSSO Request Files for Remote Registration
Templates for . . . Description
Register OSSO Agents (mod_
osso)
$OAM_REG_HOME/input/OSSORequest.xml
Other Templates
Update Agent: $OAM_REG_HOME/input/OSSOUpdateAgentRequest.xml
See Also: "Updating Agents Remotely" on page 15-38
Create Policies:
Create New Host Identifiers and
an Application Domain without
Registering an Agent
$OAM_REG_HOME/input/CreatePolicyRequest.xml
See Also: "Managing Policies and Application Domains Remotely" on
page 25-82
Update Policies:
Existing Host Identifiers and
Application Domain (not
associated with an Agent
Registration)
$OAM_REG_HOME/input/UpdatePolicyRequest.xml
See Also: "Managing Policies and Application Domains Remotely" on
page 25-82
Performing Remote Registration for OSSO Agents
Registering and Managing Legacy OSSO Agents 29-13
Remote OSSO Agent registration automatically:
■Creates the agent page for the Oracle Access Management Console
■Creates an Application Domain and basic policies to protect applications
■Updates the OSSO configuration file on the client to be consumed by the agent at
run time
29.4.2 Performing In-Band Remote Registration of OSSO Agents
This is a brief summary of tasks required to perform in-band remote registration for
your OSSO agent. Full details are provided in Chapter 15.
Table 29–7 OSSO-Specific Elements in a Remote Registration Request
Elements Description Example
<serverAddress>
<agentName>
<hostIdentifier>
<agentBaseUrl>
<autoCreatePolicy>
<applicationDomain>
<virtualhost>
Elements common to all remote registration request
templates.
See Table 15–8, " Common Elements in
Remote Registration Requests"
<ssoServerVersion> SSO Token version values:
■v3.0: Most secure token using AES encryption
standard for encrypting tokens exchanged between
OAM Server and mod_osso. This is the default
value. This was supported by OSSO 10.1.4.3 patch
set.
■v1.4: This is supported by OSSO 10g prior to OSSO
10.1.4.3 patch set. Uses DES encryption standard.
■v1.2: This used to be version of tokens exchanged
between OSSO partners prior to OSSO 10.1.4.0.1.
Uses DES.
<ssoServerVersion>
>...</ssoServerVersion> >
<OracleHomePath> The absolute file system directory path to the mod_osso
agent.
<oracleHomePath>
$ORACLE_HOME
</oracleHomePath>
<updateMode> Default: None specified
<updateMode></updateMode>
<adminInfo> Optional.
Administrator details for this mod_osso instance. For
example, Application Administrator.
Default: None specified
<adminInfo></adminInfo>
<adminId> Optional.
Administrator log in ID for this mod_osso instance. For
example, SiteAdmin.
Default: None specified
<adminId></adminId>
<logoutUrl> Include the Logout URLs for consumption during
remote registration.
Default: None specified
<logoutUrl>logout1.html</logoutUrl>
<failureUrl> Include the Failure URLs for consumption during remote
registration.
Default: None specified
<failureUrl>failure1.html</failureUrl>
Performing Remote Registration for OSSO Agents
29-14 Administrator's Guide for Oracle Access Management
Prerequisites
Introduction to Remote Registration on page 14-8
Task overview: In-band Administrators performing remote registration
1. Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
2. Create your input file with unique values for the agent and Application Domain as
described in "Creating Your Remote Registration Request" on page 15-34.
From: OSSORequest.xml
To: myossoagent_request.xml
3. Run the registration tool to configure the Agent, create a default Application
Domain for the resources, and copy the updated agent configuration file as
described in "Performing In-Band Remote Registration" on page 29-13.
From AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/osso.conf
To: mod_osso directory path on the Agent host: $OHS_dir/osso.conf. For example:
$WebTier_MW_HOME/Oracle_WT1/instances1/config/OHS/ohs1/config/
osso.conf
4. Validate the configuration as described in "Validating Remote Registration and
Resource Protection" on page 15-40.
5. Perform access checks to validate that the configuration is working, as described
in "Verifying Authentication and Access After Remote Registration" on page 15-40.
29.4.3 Performing Out-of-Band Remote Registration for OSSO Agents
The term out-of-band registration refers to manual registration that involves
coordination and actions by both the in-band Administrator and the out-of-band
Administrator.
In
outofband
mode, the in-band Administrator uses the starting request file submitted
by the out-of-band Administrator, and returns a generated response file to the
out-of-band Administrator for additional processing. The out-of-band Administrator
runs the remote registration tool with the response file as input to update the agent
configuration file.
This is a brief summary of tasks required to perform out-of-band remote registration
for your OSSO agent. Full details are provided in other chapters, as described here.
Prerequisites
"Introduction to Remote Registration" on page 14-8
Task overview: Out-of-band remote registration (Agent is outside the network)
1. Out-of-band Administrator: Creates a starting request input file containing
specific application and agent details and submits it to the in-band Administrator.
■Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
Updating Registered OSSO Agents Remotely
Registering and Managing Legacy OSSO Agents 29-15
■Copy and edit a template to input unique values for the agent and Application
Domain as described in "Creating Your Remote Registration Request" on
page 15-34.
$OAM_REG_HOME/input/OSSORequest.xml
■Submit the starting request input file to the in-band Administrator using a
method you choose (email or file transfer).
2. In-band Administrator:
■Acquire the registration tool and set environment variables as described in
"Acquiring and Setting Up the Remote Registration Tool" on page 15-33.
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
■Use the out-of-band starting request with the registration tool to register the
agent and create the response and native agent configuration files to return to
the out-of-band Administrator. See "Performing Out-of-Band Remote
Registration" on page 15-35:
–osso_Response.xml is generated for the out of band Administrator to use
in Step 3.
–osso.conf is modified for the out-of-band Administrator to bootstrap the
OSSO module.
3. Out-of-band Administrator: Use the registration tool with the response file and
copy artifacts to the appropriate file system directory.
–osso_Response.xml.
–osso.conf
4. In-band Administrator: Validates the configuration as described in "Validating
Remote Registration and Resource Protection" on page 15-40.
5. Out-of-band Administrator: Performs several access checks to validate that the
configuration is working, as described in "Verifying Authentication and Access
After Remote Registration" on page 15-40.
29.5 Updating Registered OSSO Agents Remotely
This section describes how to update, validate, and delete OSSO Agents using remote
registration templates and modes described in "Introduction to Updating Agents
Remotely" on page 15-37.
The update request file passes specific values to the remote registration tool, oamreg.
The primary differences between the update template and the original registration
template is that the update template.
Table 29–8 Delta: OSSO Remote Registration versus Remote Updates
Delta Element
Adds <startDate>yyyy_mm_dd</startDate> element to track changes
<homeUrl> element that specifies the agent_base_url_port
Omits <hostidentifier>
Omits <agentbaseURL>
Configuring Logout for OSSO Agents with Access Manager 11.1.2
29-16 Administrator's Guide for Oracle Access Management
To remotely update OSSO Agent registration
1. Set up the registration tool as described in, "Acquiring and Setting Up the Remote
Registration Tool" on page 15-33.
2. Update Agent:
a. Create your update request using the
OSSOUpdateAgentRequest.xml
template.
b. On the computer hosting the Agent, run the following command with
agentUpdate
mode specify your own *Request*.xml as the input file. For
example:
./bin/oamreg.sh agentUpdate input/*OSSOUpdateAgentRequest.xml
c. Provide the registration Administrator user name and password when asked.
d. Confirm success with on-screen messages.
e. Relocate to the agent host osso.conf:
From the AdminServer (Console) host: /rreg/output/Agent_Name/
To the mod_osso directory path (Agent host Web server $OHS_dir/osso.conf):
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/osso.conf
f. Restart the OAM Server that is hosting this agent
3. Validating Agent:
a. On the Agent host, run the following command in
agentValidate
mode. For
example:
./bin/oamreg.sh agentValidate agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
4. Deleting an Agent:
a. On the computer hosting the Agent, run the following
agentDelete
command.
For example:
./bin/oamreg.sh agentDelete agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
Success: On-screen message confirms
AgentDelete process completed successfully
!
29.6 Configuring Logout for OSSO Agents with Access Manager 11.1.2
This section provides the following topics:
■About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager
■Removing Custom mod_osso Cookies on Logout
Configuring Logout for OSSO Agents with Access Manager 11.1.2
Registering and Managing Legacy OSSO Agents 29-17
29.6.1 About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager
With OSSO Agents (mod_osso 10g), partner applications also cede logout control to
the OAM Server (single sign-on server). When the user logs out of one application, she
is automatically logged out of all other applications.
Process overview: Centralized logout with mod_osso
1. Clicking Logout in an application takes the user to the page where logout occurs
2. When a user has signed off successfully, each of the applications listed on the
centralized logout page has a check mark beside the application name.
3. A broken image beside an application name identifies an unsuccessful logout.
4. Once all of the application names activated in a session have a check mark, you
can click Return to go to the application from which you initiated logout.
5. Delete the custom mod_osso agent cookies on logout.
29.6.2 Removing Custom mod_osso Cookies on Logout
The OSSO server cookie includes a list of partner IDs.
Process overview: When a user logs off from one partner application
1. OSSO server pulls a list of the logout URLs.
2. OSSO server clears its own cookie.
3. OSSO server redirects to a customized JSP page (hosted on the OSSO server), and
passes the list of logout URLs in the request.
4. The JSP page loads those logout URLs that contains some image tags of check
marks, and as a result of the loading, the cookies for those mod_osso instances are
cleared
However, on user logout, some custom cookies set by OAM Server through
authentication response settings might not get deleted. However, you can edit
oam-config.xml to configure the OAM Server to delete custom cookies set during
authentication when a user logs out of OAM. For instance, when integrating with
Oracle E-Business Suite, the ORASSO_AUTH_HINT cookie is set by the application
and should be included in the
CookieNames
list (or the UCM cookie, for example).
Syntax (beneath
PluginClass" Type=
...):
<Setting Name="CookieDelMap" Type="htf:map">
<Setting Name="CookieNames" Type="xsd:string">COOKIE_NAME</Setting>
</Setting>
The following procedure guides as you edit the
CookieDelMap
element and add
CookieNames as a single value or a comma-separated list of custom cookies to delete
when a user logs out. This procedure also explains how to increment the
oam-config.xml file version to propagate your change to all managed servers without
restarting.
Note: No change is needed in the logout URL configuration of
existing applications that use the OSSO Agent.
Locating Other OSSO Agent Information
29-18 Administrator's Guide for Oracle Access Management
To delete custom mod_osso cookies on logout
1. Back up $DOMAIN_HOME/config/fmwconfig/oam-config.xml.
2. In oam-config.xml, add (or edit) the
CookieDelMap
element and
CookieNames
. For
example:
<Setting Name="ResponsePluginSetting" Type="htf:map">
<Setting Name="PluginClass" Type=... </Settings>
<Setting Name="CookieDelMap" Type="htf:map">
<Setting Name="CookieNames" Type="xsd:string">ORASSO_AUTH_HINT
</Setting>
</Setting>
</Setting>
3. Configuration Version: Increment the
Version xsd:integer
as shown in the next
to last line of this example (existing value (25, here) + 1):
Example:
<Setting Name="Version" Type="xsd:integer">
<Setting xmlns="http://www.w3.org/2001/XMLSchema"
Name="NGAMConfiguration" Type="htf:map:>
<Setting Name="ProductRelease" Type="xsd:string">11.1.1.3</Setting>
<Setting Name="Version" Type="xsd:integer">25</Setting>
</Setting>
4. Save the file.
29.7 Locating Other OSSO Agent Information
See Table 29–9 for additional information on legacy OSSO agents with Access
Manager.
Caution: Work carefully. In general, Oracle recommends that you do
not edit the oam-config.xml file. This, however, is a rare exception.
Table 29–9 Other OSSO Information in this Guide
Topic Location
Component Loggers Table 7–3, " Oracle Access Management Server-Side Component
Loggers"
OSSO Metrics in the DMS
Console
"Reviewing OSSO Agent Metrics" on page 11-8
Sessions and Session Management Chapter 16, "Maintaining Access Manager Sessions"
30
Registering and Managing 10g WebGates with Access Manager 11g 30-1
30
Registering and Managing 10g WebGates with
Access Manager 11g
The Oracle Fusion Middleware Installation Guide for Oracle Identity and Access
Management describes initial deployment of Access Manager 11g with the Oracle
HTTP Server. However, when your enterprise includes Web server types other than
Oracle HTTP Server you might want to use existing 10g WebGates or install fresh 10g
WebGates for use with Access Manager. Also, you might want to switch from using
the pre-registered IAMSuiteAgent to using a 10g WebGate to protect Oracle Identity
Management Consoles.
The following sections describe how to install fresh instances of 10g WebGates for use
with Access Manager:
■Prerequisites
■Introduction to 10g OAM Agents for Access Manager 11g
■Comparing Access Manager 11.1.2 and 10g
■Configuring Centralized Logout for IAMSuiteAgent
■Registering a 10g WebGate with Access Manager 11g Remotely
■Managing 10g OAM Agents Remotely
■Locating and Installing the Latest 10g WebGate for Access Manager 11g
■Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
■Removing a 10g WebGate from the Access Manager 11g Deployment
30.1 Prerequisites
Review the latest certification matrix from Oracle Technology Network to locate the
latest WebGates for your deployment:
http://www.oracle.com/technetwork/middleware/id-mgmt/fusion-certification-
100350.html
Ensure that your Oracle Access Management Console is running and get familiar with:
■Introduction to Policy Enforcement Agents on page 14-1
■Introduction to 10g OAM Agents for Access Manager 11g in this chapter
Introduction to 10g OAM Agents for Access Manager 11g
30-2 Administrator's Guide for Oracle Access Management
30.2 Introduction to 10g OAM Agents for Access Manager 11g
This section provides the following topics:
■About IAMSuiteAgent: A Pre-Configured 10g WebGate Registered with Access
Manager
■About Legacy Oracle Access Manager 10g Deployments and WebGates
■About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2
■About Centralized Logout with 10g OAM Agents and 11g OAM Servers
30.2.1 About IAMSuiteAgent: A Pre-Configured 10g WebGate Registered with Access
Manager
IAMSuiteAgent is a Java agent filter that is pre-registered with Access Manager 11.1.2
out of the box. This agent and the companion Application Domain are installed
pre-configured with Access Manager.
The IAMSuiteAgent is a domain-wide agent:
■Once Access Manager is deployed, the IAMSuiteAgent is installed on every server
in the domain
■Unless disabled, every request coming into the WebLogic Application Server is
evaluated and processed by the IAMSuiteAgent
■Certain IAMSuiteAgent configuration elements are available in the WebLogic
Administration Console (in the Security Provider section) and others in the Oracle
Access Management Console.
IAMSuiteAgent and related policies provide SSO protection for the IDM
Administration Console, Oracle Identity Console, Oracle Access Management
Console, and specific resources in the Identity Management domain.
You can replace the IAMSuiteAgent with a 10g WebGate to protect Oracle Identity
Management Consoles and resources in the Identity Management domain, if you
choose.
30.2.2 About Legacy Oracle Access Manager 10g Deployments and WebGates
11g OAM Servers support 10g WebGates that are registered to operate with Access
Manager 11.1.2. Such WebGates might include:
■Legacy 10g WebGates currently operating with Oracle Access Manager 10g.
■Legacy 10g WebGates configured as the Identity Assertion Provider (IAP) for SSO
(for applications using IAP WebLogic container-based security with Oracle Access
Manager 10g, as described in the Oracle Fusion Middleware Application Security
Guide).
■Legacy 10g WebGates currently operating with Web Applications coded for Oracle
ADF Security and the OPSS SSO Framework
See Also:
■Section 30.4, "Configuring Centralized Logout for
IAMSuiteAgent"
■Section 15.11, "Replacing the IAMSuiteAgent with an 11g
WebGate"
■Section D.1, "Bundled 10g IAMSuiteAgent Artifacts"
Introduction to 10g OAM Agents for Access Manager 11g
Registering and Managing 10g WebGates with Access Manager 11g 30-3
You can register these agents to use Access Manager SSO using either the Oracle
Access Management Console or the remote registration tool. After registration, 10g
WebGates directly communicate with Access Manager through a Java-based OAM
Proxy that acts as a bridge.
The following overview outlines the tasks that must be performed to set up an existing
10g WebGate to operate with Access Manager.
Task overview: Setting up a legacy 10g WebGate to operate with Access
Manager
1. Registering a 10g WebGate with Access Manager 11g Remotely
2. Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
3. Optional: Deploying Applications in a WebLogic Container as described in the
Oracle Fusion Middleware Application Security Guide.
30.2.3 About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2
You can install fresh 10g WebGates for use with Access Manager 11g as described in
this chapter. 10g WebGates are available for a number of Web server platforms.
After installation and registration, 10g WebGates directly communicate with Access
Manager through a Java-based OAM proxy that acts as a bridge.
There are several differences between installing a 10g WebGate to operate in an 11g
Access Manager deployment versus installing the 10g WebGate in an 10g Oracle
Access Manager deployment. Table 30–1 outlines these differences.
See Also:
■Table 1–2
■Appendix A, "Integrating Oracle ADF Applications with Access
Manager SSO"
Note: When installing fresh 10g WebGates for Access Manager,
Oracle recommends that you use the latest WebGates. Oracle also
recommends that you install multiple WebGates for failover and load
balancing.
Introduction to 10g OAM Agents for Access Manager 11g
30-4 Administrator's Guide for Oracle Access Management
The following overview lists the topics in this chapter that describe 10g WebGate
installation and registration tasks for Access Manager 11g in detail. You must complete
all procedures for successful operation with Access Manager 11g.
Task overview: Registering and installing a 10g WebGate for Access
Manager 11g
1. Registering a 10g WebGate:
2. Locating and Downloading 10g WebGates for Use with Access Manager 11g
3. Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
4. Optional: Deploying Applications in a WebLogic Container as described in Oracle
Fusion Middleware Application Security Guide.
30.2.4 About Centralized Logout with 10g OAM Agents and 11g OAM Servers
Logout is initiated when an application causes the invocation of the logout.html file
configured for any registered 10g WebGate.
Generally speaking, during centralized logout with 10g WebGates the SSO Engine
receives a user-session-exists request. The Session Management Engine looks up the
session and responds that the session exists. The SSO engine sends a Clear Session
request. The Session management engine clears the token and session context. The
SSO engine sends a Session Cleared response.
Table 30–1 Installation Comparison with 10g WebGates
10g WebGates in 11g Deployments 10g WebGates in 10g Deployments
1. Packages: 10g WebGate installation packages are found on
media and virtual media that is separate from the core
components.
2. Provisioning: Before installation, provision WebGate with
Access Manager 11g as described in "Registering a 10g
WebGate with Access Manager 11g Remotely" on
page 30-11.
3. Associating with OAM Server: Occurs during WebGate
registration (task 2 of this sequence).
4. Installing: Install the 10g WebGate in front of the
application (or for Fusion Middleware, in front of the
WebLogic Server).
5. Language Packs: 10g WebGate Language Packs are
supported with Access Manager.
6. Web Server Configuration: Copy Access Manager
generated files to the WebGate installation directory path
to update the Web server configuration.
7. Certificate Installation: Copy files to the WebGate
installation directory path.
8. Forms: 10g forms provided with 10g WebGates cannot be
used with 11g OAM Servers.
Using 10g WebGates with 11g OAM Servers is similar in
operation and scope to a resource WebGate (one that
redirects in contrast to the Authentication WebGate). With
a 10g WebGate and 11g OAM Server, the 10g WebGate
always redirects to the 11g credential collector which acts
like the authenticating WebGate.
9. Single Log Out: Configure using information in
Chapter 27, "Configuring Centralized Logout for Sessions
Involving 11g WebGates."
10. Multi-Domain Support: Does not apply with Access
Manager 11g.
1. Packages: 10g WebGate installation packages are found on
media and virtual media that is separate from the core
components.
2. Provisioning: Before installation, you create a WebGate
instance in the Access System Console.
3. Associating with AAA: Before installation, you associated
the WebGate with an Access Server in the Access System
Console.
4. Installing: Using 10g WebGate packages.
5. Language Packs: 10g WebGate Language Packs could be
installed during WebGate installation (or later).
6. Web Server Configuration: Automatic during WebGate
installation (or manually after WebGate installation).
7. Certificate Installation: You copied files to the WebGate
installation directory path.
8. Forms: Were provided for use in 10g deployments.
9. Centralized Log Out for Oracle Access Manager 10g.
10. Multi-Domain Support: Could be configured for Oracle
Access Manager 10g.
Comparing Access Manager 11.1.2 and 10g
Registering and Managing 10g WebGates with Access Manager 11g 30-5
Clearing the user token and the session context clears the server-side state, which
includes clearing the OAM_ID cookie set on the server side. When the agent is
notified, the agent clears the client-side state of the application. For more information,
see Section 30.8, "Configuring Centralized Logout for 10g WebGate with 11g OAM
Servers."
30.3 Comparing Access Manager 11.1.2 and 10g
This topic provides a comparison against the 10g architecture for Access Manager and
OSSO. Included are the following topics:
■Comparing Access Manager 11g versus 10g
■Comparing Access Manager 11g versus 10g Policy Model
30.3.1 Comparing Access Manager 11g versus 10g
Access Manager 11g differs from 10g in that the identity administration features have
been transferred to Oracle Identity Manager 11g (including user self-service and self
registration, workflow functionality, dynamic group management, and delegated
identity administration).
Access Manager 10g supported Single Sign-on using a single session cookie (the
ObSSOCookie) that contained the user identity and session information required to
access target resources that had the same or lower authentication level. The
ObSSOCookie was encrypted and decrypted using a global shared secret key, the
value of which was stored in the directory server. The ObSSOCookie was consumed
by Access System components to verify the user identity and allow or disallow access
to protected resources.
To close any possible security gaps, Access Manager 11g provides new server-side
components that maintain backward compatibility with existing Access Manager 10g
policy-enforcement agents (WebGates) and OSSO 10g agents (mod_osso). New Access
Manager 11g WebGates are enhanced versions of 10g WebGates, that support a
per-agent secret key for the Single Sign-on (SSO) solution. Thus, cookie-replay type of
attack are prevented. The 11g WebGates are all trusted at the same level; a cookie
specific for the WebGate is set and cannot be used to access any other
WebGate-protected applications on a user's behalf.
Unless explicitly stated, the term "WebGate" refers to both an out of the box WebGate
or a custom Access Client.
Access Manager 11g uses technology from Oracle Coherence to provide centralized,
distributed, and reliable session management.
Table 30–2 provides a comparison of Access Manager 11g versus 10g. For a list of
names that have changed with Access Manager 11g, see "Product and Component
Name Changes with 11.1.2."
See Also: Section 30.4, "Configuring Centralized Logout for
IAMSuiteAgent"
Comparing Access Manager 11.1.2 and 10g
30-6 Administrator's Guide for Oracle Access Management
Table 30–2 Comparison: Access Manager 11g versus 10g
Access Manager 11g 10g
Agents ■Agents: WebGate, Access Client, OpenSSO,
OSSO (mod_osso), IAMSuiteAgent
Note: Nine Administrator languages are supported.
■Resource WebGate (RWG)
■Authentication WebGate (AWG)
■AccessGate
■Access Server
■Policy Manager
■Identity System
Note: Nine Administrator languages are supported.
Server-side
components
■OAM Server (installed on a WebLogic Managed
Sever)
Security Token Service and Identity Federation
run on OAM Server
■Access Server
■Policy Manager
■Identity Server
Console Oracle Access Management Console Access System Console
Identity System Console
Protocols that
secure
information
exchange on the
Internet
Front channel protocols exchanged between Agent
and Server: HTTP/HTTPS.
11g WebGate secures information exchange using the
Agent key.
-See Also: Cryptographic keys.
10g Agent information exchange is unsecured, in
plain text.
Cryptographic
keys
■One per-agent secret key shared between 11g
WebGate and OAM Server
■One OAM Server key, generated during Server
registration
Note: One key is generated and used per registered
mod_osso agent.
One global shared secret key per Access Manager
deployment which is used by all the 10g WebGates
Keys storage ■Agent side: A per-agent key is stored locally in
the Oracle Secret Store in a wallet file
■OAM Server side: A per- agent key, and server
key, are stored in the credential store on the
server side
■Security Token Service
Global shared secret stored in the directory server
only (not accessible to WebGate)
Cookies Host-based authentication cookie, described in
Table 1–2, " Features in Access Manager 11.1.2"
■One domain-based ObSSOCookie for all
WebGates (including the AWG), for both
authentication and session management
Encryption /
Decryption (The
process of
converting
encrypted data
back into its
original form)
Introduces client-side cryptography and ensures that
cryptography is performed at both the agent and
server ends:
1. WebGate encrypts obrareq.cgi using the agent
key.
Note: obrareq.cgi is the authentication request in
the form of a query string redirected from
WebGate to OAM Server.
2. OAM Server decrypts the request, authenticates,
creates the session, and sets the server cookie.
3. OAM Server also generates the authentication
token for the agent (encrypted using the agent
key), packs it in obrar.cgi with a session token (if
using cookie-based session management),
authentication token and other parameters, then
encrypts obrar.cgi using the agent key.
Note: obrar.cgi is the authentication response
string redirected from the OAM Server to
WebGate.
4. WebGate decrypts obrar.cgi, extracts the
authentication token, and sets a host-based
cookie.
■Token generation/ encryption, and validation/
decryption are delegated to the Access Server.
■Both obrareq.cgi and obrar.cgi are sent
unencrypted, relying on the underlying
HTTP(S) transport for security.
Comparing Access Manager 11.1.2 and 10g
Registering and Managing 10g WebGates with Access Manager 11g 30-7
30.3.2 Comparing Access Manager 11g versus 10g Policy Model
Access Manager 11g default behavior is to deny access when a resource is not
protected by a policy that explicitly allows access.
Access Manager 10g provides authentication and authorization based on policies
within a policy domain. Access Manager 10g default behavior allowed access when a
resource was not protected by a rule or policy that explicitly denied access to limit the
number of WebGate queries to the Access Server.
Table 30–3 compares the Access Manager 11g policy model with the 10g model. Access
Manager 11g default behavior is to deny access when a resource is not protected by a
policy that explicitly allows access. In contrast, Access Manager 10g default behavior
allowed access when a resource was not protected by a rule or policy that explicitly
specified access.
Session
Management
■Chapter 16, "Maintaining Access Manager
Sessions"
■Single domain supported.
Multi-domain: If a user idles out on one
domain, but not on the authentication WebGate,
the AWG cookie is still valid (re-authentication
is not needed).A new cookie is generated with
the refreshed timeout.
Client IP ■Maintain this Client IP, and include it in the
host- based OAMAuthnCookie.
■Include the original client IP inside the
ObSSOCookie.
If IP validation is configured, when cookie
presented in later authentication or
authorization requests this original client IP is
compared with the presenter's IP.
Rejection occurs if there is no match
Response token
replay
prevention
■Include RequestTime (the timestamp just before
redirect) in obrareq.cgi and copy it to obrar.cgi
to prevent response token replay.
N/A
Multiple network
domain support
Cross-network-domain single sign-on out of the box.
Oracle recommends you use Oracle Federation for
multiple network domain support.
A proprietary multiple network domain SSO
capability predates Oracle Access Management
Identity Federation. If this is implemented in your
10g deployment, register 10g Agents with Access
Manager 11g to continue this support.
■Single domain is supported.
Once a user logs off from one WebGate, the
domain cookie is cleared and the user is
considered to be logged off the entire domain.
■Multi-domain SSO can be supported through
chained customized logout pages.
Centralized
log-out
■The
logOutUrls
(10g WebGate configuration
parameter) is preserved. 10g logout.html
requires specific details for Access Manager 11g.
■11g WebGate parameters are new:
Logout Redirect URL
Logout Callback URL
Logout Target URL
See Chapter 27, "Configuring Centralized Logout for
Sessions Involving 11g WebGates."
logout.html requires specific details when using a 10g
WebGate with Access Manager 11g. See Chapter 27,
"Configuring Centralized Logout for Sessions
Involving 11g WebGates."
■Single domain is supported.
Once a user logs off from one WebGate, the
domain cookie is cleared and the user is
considered to be logged off the entire domain.
■Multi-domain SSO can be supported through
chained customized logout pages.
Table 30–2 (Cont.) Comparison: Access Manager 11g versus 10g
Access Manager 11g 10g
Comparing Access Manager 11.1.2 and 10g
30-8 Administrator's Guide for Oracle Access Management
Table 30–3 Comparing Access Manager 11g Policy Model versus 10g
Policy Elements 11g Policy Model 10g Policy Model
Policy Authoring Oracle Access Management Console Policy Manager
Policy Store Database LDAP directory server
Domain Application Domain Policy Domain
Resources 1. No URL prefixes. Resource definitions are
treated as complete URLs.
2. Pattern matching (with limited features) for:
' * ' and '...' are supported
3. Resources need not be unique across domains.
4. Query-string protection for HTTP URLs.
5. Each HTTP resource is defined as a URL path,
and associated with a host identifier.
However, resources of other types are
associated with a specific name (not a host
identifier).
6. Non-HTTP resource types are supported, with
definition of specific operations. Non-HTTP
resource types are never associated with a
host identifier.
7. Resources can designated as either Protected,
Unprotected, or Excluded.
8. Custom resource types are allowed.
1. URL prefixes are defined in domains
2. Pattern matching for:
{ } * …
3. Resources need not be unique across domains.
4. http resources can be protected based on URL
query string contents and/or HTTP operation.
5. Non-HTTP resource types and operations can
be defined.
Host identifiers 1. Host Identifiers are defined outside of policies
and are used while defining HTTP resources.
2. Host Identifiers are mandatory for defining
HTTP resources.
1. Host Identifiers are defined outside of policies
and are used while defining HTTP resources.
2. Host Identifiers are not mandatory, for
defining HTTP resources, till there are no Host
Identifiers defined in the system.
Authentication
Policies
1. Authentication policies include resources,
success responses, and an authentication
scheme.
2. Authorization policies can also contain
success responses, and time based, IP based
and user-based conditions.
3. Only one authentication policy and one
authorization policy can be associated with
any resource.
4. Authentication and Authorization policies can
evaluate to Success or Failure.
5. No Query Builder and no support for LDAP
filters for (for retrieving matches based on an
attribute of a certain display type, for
example).
6. There is no notion of a default policy in an
Application Domain. However, you can
define a policy for resource: /…/* which can
be used as a default policy within a
determined scope).
7. Token Issuance Policies can be defined using
resources and user- or partner-based
conditions. See Section 25.3.6, "Displaying
Token Issuance Policy Pages.".
1. Authentication policies are simple and contain
only authentication-scheme-based rule.
2. One resource can be associated with a set of
Authorization policies. Evaluation of these
policies can be based on an expression that
combines the policies within the set using
logical operators as desired.
A resource can also be associated with
multiple authentication policies and
authorization policy sets. However, only one
set applies.
3. An Authorization policy can evaluate to
Success or Failure, or Inconclusive.
4. Users can be specified using LDAP filters.
5. Default authentication policy and
authorization policy set can be defined for a
policy domain. This policy is only applicable
if there are no other applicable policies for a
runtime resource in that domain.
6. There is no support for Token Issuance
Policies.
Comparing Access Manager 11.1.2 and 10g
Registering and Managing 10g WebGates with Access Manager 11g 30-9
Authentication
Schemes
Authentication Schemes are defined globally and
can be shared (referenced within authentication
policies).
The trust level is expressed as an integer value
between 0 (no trust) and 99 (highest level of trust).
Note: Level 0 is unprotected. Only unprotected
resources can be added to an Authentication Policy
that uses an authentication scheme at protection
level 0.
See Also: Table 22–20, " Authentication Scheme
Definition".
Authentication Schemes can be defined outside of
policies and can be referenced within
authentication policies.
Authorization Policy Each resource assigned to an Application Domain
can be protected by only one authorization policy.
Each policy can include one or more conditions and
a rule.
See Also: Rule, later in this table, and Section 25.7,
"Defining Authorization Policies for Specific
Resources.".
To protect resources, you define authorization rules
that contain one or more conditions.You also
configure authorization expressions using one or
more authorization rules. A policy domain (and a
policy) can each contain only one authorization
expression.
Token Issuance Policy By default, only a container for Token Issuance
Policies is provided in a generated Application
Domain. No Conditions or Rules are generated
automatically. You must add these manually.
See Also: Section 25.3.6, "Displaying Token
Issuance Policy Pages.".
N/A
Responses Available for all policy types:
1. Authentication and Authorization success
Responses can be defined within the policies.
These are applied after evaluation of policies.
2. Cookie, Header, and Session responses are
supported.
3. URL redirection can be set.
4. Response definitions are part of each policy.
Response values can be literal strings or can
contain additional embedded expressions that
derive values from request, user, and session
attributes.
1. Authentication and Authorization Responses
can be defined within the policies for Success,
Failure, and Inconclusive events. These are
returned to the caller after evaluation of
policies.
2. HTTP_HEADER and Cookie based variables
can be set.
3. Redirect URLs can be set for Success and
Failure events of authentication and
authorization policy evaluations.
4. Response values can contain literal strings
and list of user attribute values.
Cookies See Also: Table 21–6
and
Section 21.5.1, "About Single Sign-On Cookies
During User Login."
See Also: Table 21–6
and
Section 21.5.1, "About Single Sign-On Cookies
During User Login."
Table 30–3 (Cont.) Comparing Access Manager 11g Policy Model versus 10g
Policy Elements 11g Policy Model 10g Policy Model
Configuring Centralized Logout for IAMSuiteAgent
30-10 Administrator's Guide for Oracle Access Management
30.4 Configuring Centralized Logout for IAMSuiteAgent
The IAMSuiteAgent is pre-configured with the logout parameters needed to perform
central logout against the OAM Server. While similar to a 10g WebGate, the
IAMSuiteAgent does not have a local logout.html page to be configured. Instead, the
IAMSuiteAgent is delivered with a pre-deployed application oamsso_logout), that is
used by the agent to perform the logout.
The logout functionality for the IAMSuiteAgent requires that the oamsso_logout
application is deployed in the Server where the IAMSuiteAgent is used. The initial
installation adds this application to AdminServer and to OAM Servers. However, you
must update this application's Target servers to include all those that are using the
IAMSuiteAgent.
To configure logout for the IAMSuiteAgent
1. Log in to the WebLogic Server Administration Console.
2. Navigate to Domain, Deployments, oamsso_logout, Targets.
3. Select all the Servers where the IAMSuiteAgent is enabled and where logout is
performed. For example, oim_server, oaam_admin, oaam_server, and so on.
4. Click Save.
5. Proceed to:
Query String-based
HTTP Resource
Definitions
Supported within Access Policies, as described in
Table 25–1, " Resource Definition Elements"
This Policy Model supports query string-based
HTTP resource definitions within Access Policies.
At run time, the OAM Proxy passes the Query
String to the policy layer after URL encoding, just
like for base resource URL. Only Query String that
are part of HTTP GET requests are passed. Query
String pattern does not apply to HTTP POST data.
Rule Available for only Authorization and Token
Issuance Policies.
Each Authorization policy includes a rule that
defines whether the policy allows or denies access
to resources protected by the policy.
The rule references Authorization conditions,
described next.
See Also: Section 25.9, "Introduction to
Authorization Policy Rules and Conditions.".
A policy is defined using authorization rules
(among other policy elements). Authorization
rules:
■Are defined outside of policies (but scoped
within a policy domain) and are referenced in
policies.
■Appear in two places: 1) as part of default
rules for the domain and 2) in policy
definitions.
Each rule specifies who (which users, groups or IP4
addresses) is allowed or denied access and the time
period in which this rule applies.
There is also a provision to specify whether Allow
takes precedence over Deny.
Condition Available for only Authorization and Token
Issuance Policies.
Each Authorization policy rule references
conditions that define to whom the rule applies, if
there is a time Condition, and how evaluation
outcomes are to be applied.
Conditions are declared outside of rules and are
referenced within a rule.
See Also: Section 25.9, "Introduction to
Authorization Policy Rules and Conditions."
N/A
Table 30–3 (Cont.) Comparing Access Manager 11g Policy Model versus 10g
Policy Elements 11g Policy Model 10g Policy Model
Registering a 10g WebGate with Access Manager 11g Remotely
Registering and Managing 10g WebGates with Access Manager 11g 30-11
■Section 25.15, "Validating Authentication and Authorization in an Application
Domain"
■Chapter 26, "Validating Connectivity and Policies Using the Access Tester"
30.5 Registering a 10g WebGate with Access Manager 11g Remotely
Whether you have a legacy 10g WebGate installed, or you are installing a fresh 10g
WebGate instance to use with Access Manager 11g, you must register WebGate to use
Access Manager 11g authentication and authorization services.
You can use either the Oracle Access Management Console or the remote registration
tool to perform this task. The remote registration tool enables you to specify all
WebGate parameters before registration using a template.
The following procedure walks through provisioning using the remote registration
tool, in-band mode. In this example, OAMRequest_short.xml is used as a template to
create an agent named my-10g-agent1, protecting /.../*, and declaring a public resource,
/public/index.html. Your values will be different. You can use a full registration
template to specify public, private, and excluded resources.
To use remote registration with a 10g WebGate for Access Manager 11g
1. Acquire the remote registration tool and set up the script for your environment.
For example:
a. Locate RREG.tar.gz file in the following path:
$ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz
b. Untar RREG.tar.gz file to any suitable location. For example:
rreg/bin/oamreg.
c. In the oamreg script (oamreg.bat or oamreg.sh), set the following environment
variables based on your situation (client side or server side) and information
in Table 15–5:
OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
JAVA_HOME = Java_location_on_the_computer
2. Create the registration request:
a. Locate OAMRequest_short.xml and copy it to a new file. For example:
$OAM_REG_HOME/input/OAMRequest_short.xml/
Copy: OAMRequest_short.xml
To: my-10g-agent1.xml
b. Edit my-10g-agent1.xml to include details for your environment. For example:
<OAMRegRequest>
<serverAddress>http://ruby.uk.example.com:7001</serverAddress>
<hostIdentifier>my-10g</hostIdentifier>
<agentName>my-10g-agent1</agentName>
<protectedResourcesList>
<resource>/myapp/</resource>
<resource>/myapp/.../*</resource>
See Also: The following, if needed:
■Section 15.7, "Performing Remote Registration for OAM Agents"
Registering a 10g WebGate with Access Manager 11g Remotely
30-12 Administrator's Guide for Oracle Access Management
</protectedResourcesList>
<publicResourcesList>
<resource>/public/index.html</resource>
</publicResourcesList>
<excludedResourcesList>
<resource>/excluded/index.html</resource>
</excludedResourcesList>
<autoCreatePolicy>true</autoCreatePolicy>
<primaryCookieDomain>.uk.example.com</primaryCookieDomain>
<logOutUrls>
<url>/oamsso/logout.html</url>
</logOutUrls>
</OAMRegRequest>
3. Register the agent. For example:
a. Locate the remote registration script.
Linux: rreg/bin/oamreg.sh
Windows: rreg\bin\oamreg.bat
b. From the directory containing the script, execute the script using inband
mode. For example:
$ ./bin/oamreg.sh inband input/my-10g-agent1.xml
Welcome to OAM Remote Registration Tool!
Parameters passed to the registration tool are:
Mode: inband
Filename: ...
c. When prompted, enter the following information using values for your
environment:
Enter your agent username: userame
Username: userame
Enter agent password: ********
Do you want to enter a WebGate password?(y/n)
n
iv.Do you want to import an URIs file?(y/n)
n
d. Review the final message to confirm that this was a successful registration:
Inband registration process completed successfully! Output artifacts are
created in the output folder"
4. Ignore the ObAccessClient.xml file created during registration for now.
5. Log in to the Oracle Access Management Console and add resources for the new
registration to the Application Domain (Table 25–1):
a. Under Application Security, click the following links to reveal Search controls:
Access Manager
Application Domains
See Also: Section 15.7.2, "Creating Your Remote Registration
Request"
Managing 10g OAM Agents Remotely
Registering and Managing 10g WebGates with Access Manager 11g 30-13
b. Use the Search controls to locate the Application Domain in which your
WebGate registration page is created, then click the name in the Results table
to display the page.
c. Click the Resources tab and then Create.
d. OAM Proxy Port—Under Configurations, double click Server Instances and
search for the server to get the OAM Proxy port details (Table 6–3).
6. Proceed as needed for your environment:
■Existing WebGate: Configuring Centralized Logout for 10g WebGate with 11g
OAM Servers
■Uninstalled WebGate: Locating and Installing the Latest 10g WebGate for
Access Manager 11g
■Optional: Managing 10g OAM Agents Remotely
30.6 Managing 10g OAM Agents Remotely
This section describes how to update, validate, and delete OAM 10g Agents using
remote registration templates and modes described in Section 15.8, "Introduction to
Updating Agents Remotely."
To remotely update OAM 10g Agent registration
1. Set up the registration tool as described in Section 15.7.1, "Acquiring and Setting
Up the Remote Registration Tool."
2. Update Agent:
a. Create your update request using the
OAMUpdateAgentRequest.xml
template.
b. On the computer hosting the Agent, run the following command with
agentUpdate
mode specify your own *Request*.xml as the input file. For
example:
./bin/oamreg.sh agentUpdate input/*OAMUpdateAgentRequest.xml
c. Provide the registration Administrator user name and password when asked.
d. Confirm success with on-screen messages.
e. Relocate to the agent host ObAccessClient.xml:
From the AdminServer (Console) host: /rreg/output/Agent_Name/
To the Agent host: $10gWG_install_dir/oblix/lib.
f. Restart the server that is hosting this agent.
3. Validating Agent:
a. On the Agent host, run the following command in
agentValidate
mode. For
example:
./bin/oamreg.sh agentValidate agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
4. Deleting an Agent:
Locating and Installing the Latest 10g WebGate for Access Manager 11g
30-14 Administrator's Guide for Oracle Access Management
a. On the computer hosting the Agent, run the following
agentDelete
command.
For example:
./bin/oamreg.sh agentDelete agentname
b. Provide the registration Administrator user name and password when asked.
c. Confirm success with on-screen messages.
Success: On-screen message confirms
AgentDelete process completed successfully
!
30.7 Locating and Installing the Latest 10g WebGate for Access Manager
11g
Use the procedures in this section if you need to install a fresh 10g WebGate for use
with Access Manager 11g. Otherwise, skip this section and proceed to Section 30.8,
"Configuring Centralized Logout for 10g WebGate with 11g OAM Servers."
Task overview: Installing the WebGate includes
1. Preparing for a Fresh 10g WebGate Installation with Access Manager 11g
2. Locating and Downloading 10g WebGates for Use with Access Manager 11g
3. Starting WebGate 10g Installation
4. Specifying a Transport Security Mode
5. Specifying WebGate Configuration Details
6. Requesting or Installing Certificates for Secure Communications
7. Updating the WebGate Web Server Configuration
8. Finishing WebGate Installation
9. Installing Artifacts and Certificates
10. Confirming WebGate Installation
30.7.1 Preparing for a Fresh 10g WebGate Installation with Access Manager 11g
Table 30–4 outlines the requirements that must be met before starting an 10g WebGate
installation.
Table 30–4 Preparing for 10g WebGate Installation with Access Manager 11g
About the ... Description
Latest Supported
WebGates
Always use the latest supported 10g (10.1.4.3) WebGates with Access Manager 11g. However, if the desired
10g (10.1.4.3) WebGate is not provided, use the next latest WebGate (10g (10.1.4.2.0).
See Also: Section 30.7.2, "Locating and Downloading 10g WebGates for Use with Access Manager 11g."
Location for
installation
Consider:
■WebGate in front of the application server.
■Applications using WebLogic Server container-managed security: In front of the WebLogic Application
Server in which your application is deployed
User Accounts The account that is used to install the WebGate is not the account that runs the WebGate:
■The 10g WebGate should be installed using the same user and group as the Web server.
■Unix: You can be logged in as root to install the WebGate. The WebGate can be installed using a
non-root user if the Web server process runs as a non-root user
Locating and Installing the Latest 10g WebGate for Access Manager 11g
Registering and Managing 10g WebGates with Access Manager 11g 30-15
Root Level versus
Site Level
■The WebGate can be installed at the root level or the site level.
■Installing WebGate on multiple virtual sites amounts to only one instance of WebGate.
Transport Security
Mode
Ensure that at least one OAM Server is configured to use the same mode as the agent to be installed.
See Also Appendix C, "Securing Communication."
Computer Level
or Virtual Web
Server Level
The WebGate can be configured to run at either the computer level or the virtual Web server level. Do not
install at both the computer level and the virtual Web server levels.
Oracle HTTP
Server Web
Server:
The 10g WebGate for Oracle HTTP Server is based on open source Apache. WebGate package names
include:
■OHS (based on Apache v1.3)
■OHS2 (based on Apache v2)
■OHS11g (based on Apache v2.2 and is not the subject of this chapter)
Apache Web
Servers
Access Manager 11g provides a single package for components that support Apache with or without SSL
enabled:
■The APACHE2_WebGate supports v2 with or without SSL (and with or without reverse proxy enabled
on Solaris and Linux). See also Chapter 31, "Configuring Apache, OHS, IHS for 10g WebGates."
■The APACHE22_WebGate supports v2.2 with or without SSL (and with or without reverse proxy
enabled on Solaris and Linux). See also Chapter 31, "Configuring Apache, OHS, IHS for 10g
WebGates."
Note: For SSL-enabled communication, Access Manager supports Apache with mod_ssl only, not
Apache-SSL. mod_ssl is a derivative of, and alternative to, Apache-SSL.
IBM HTTP Server
(IHS) v2 Web
Servers:
IHS2_WebGate is powered by Apache v2 on IBM-AIX. Access Manager supports IHS v2 and IHS v2
Reverse Proxy servers with or without SSL enabled.
For details, see Chapter 31, "Configuring Apache, OHS, IHS for 10g WebGates."
Table 30–4 (Cont.) Preparing for 10g WebGate Installation with Access Manager 11g
About the ... Description
Locating and Installing the Latest 10g WebGate for Access Manager 11g
30-16 Administrator's Guide for Oracle Access Management
30.7.2 Locating and Downloading 10g WebGates for Use with Access Manager 11g
Use the following procedure to obtain an 10g WebGate, if needed. Be sure to choose
the appropriate installation package for your Web server.
To find and download 10g WebGates
1. Review the latest Oracle Access Manager 10g certification information on the
Oracle Technology Network at:
http://www.oracle.com/technetwork/middleware/id-mgmt/fusion-certificati
on-100350.html
2. Go to Oracle Fusion Middleware 11gR1 Software Downloads at:
http://www.oracle.com/technology/software/products/middleware/htdocs/fm
w_11_download.html
Domino Web
Servers:
Before you install the 10g WebGate with a Domino Web server, you must have properly installed and set up
the Domino Enterprise Server R5.
See Also: Chapter 34, "Configuring Lotus Domino Web Servers for 10g WebGates."
IIS Web Servers Before installing WebGate, ensure that your IIS Web server is not in lock down mode. Otherwise things will
appear to be working until the server is rebooted and the metabase re-initialized, at which time IIS will
disregard activity that occurred after the lock down.
If you are using client certificate authentication, before enabling client certificates for the WebGate you must
enable SSL on the IIS Web server hosting the WebGate.
Setting various permissions for the /access directory is required for IIS WebGates only when you are
installing on a file system that supports NTFS. For example, suppose you install the ISAPI WebGate in
Simple or Cert mode on a Windows 2000 computer running the FAT32 file system. The last installation
panel provides instructions for manually setting various permissions that cannot be set on the FAT32
fleshiest. In this case, these instructions may be ignored.
Each IIS Virtual Web server can have it's own WebGate.dll file installed at the virtual level, or can have one
WebGate affecting all sites installed at the site level. Either install the Webgate.dll at the site level to control
all virtual hosts or install the Webgate.dll for one or all virtual hosts.
You may also need to install the postgate.dll file at the computer level. The postgate.dll is located in the
\WebGate_install_dir, as described in Section 33.5.3.4.2, "Installing the Postgate ISAPI Filter." If you perform
multiple installations, multiple versions of this file may be created which may cause unusual Access
Manager behavior. In this case, you should verify that only one webgate.dll and one postgate.dll exist.
See Also: Chapter 33, "Configuring the IIS Web Server for 10g WebGates"
Removal: To fully remove a WebGate and related filters from IIS, you must do more than simply remove the
filters from the list in IIS. IIS retains all of its settings in a metabase file. On Windows 2000 and later, this is
an XML file that can be modified by hand. There is also a tool available, MetaEdit, to edit the metabase.
MetaEdit looks like Regedit and has a consistency checker and a browser/editor. To fully remove a
WebGate from IIS, use MetaEdit to edit the metabase.
ISA Proxy Servers On the ISA proxy server, all ISAPI filters must be installed within the ISA installation directory. They can be
anywhere within the ISA installation directory structure:
1. Before installing the WebGate on the ISA proxy server:
Check for general ISAPI filter with ISA instructions on:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/isa/isaisapi_5cq8.asp
Ensure that the internal and external communication layers are configured and working properly.
2. During installation you will asked if this is an ISA installation; be sure to:
Indicate that this is an ISA proxy server installation, when asked.
Specify the ISA installation directory path as the WebGate installation path.
Use the automatic Web server update feature to update the ISA proxy server during WebGate
installation.
3. After WebGate installation, locate the file configureISA4webgate.bat, which calls a number of scripts
and the process to configure the ISA server filters that must be added programmatically.
See Also: Chapter 32, "Configuring the ISA Server for 10g WebGates"
Table 30–4 (Cont.) Preparing for 10g WebGate Installation with Access Manager 11g
About the ... Description
Locating and Installing the Latest 10g WebGate for Access Manager 11g
Registering and Managing 10g WebGates with Access Manager 11g 30-17
3. Click Accept License Agreement, at the top of the page.
4. From the Access Manager WebGates (10.1.4.3.0) row, click the download link for
the desired platform and follow on-screen instructions.
5. Store the WebGate installer in the same directory with any 10g Access System
Language Packs you want to install.
6. Proceed to Section 30.7.3, "Starting WebGate 10g Installation."
30.7.3 Starting WebGate 10g Installation
The following procedure walks through the steps, which are the same regardless of
Web server type.
Installation options are identified and can be skipped if they do not apply to your
environment. During WebGate installation, information is saved at specific points. You
can cancel WebGate installation processing if needed. However, if you cancel WebGate
installation after being informed that the WebGate is being installed, you must
uninstall the component.
To start WebGate 10g installation
1. On the computer to host WebGate 10g, log in as a user with Web server
Administrator privileges.
2. Stop the Web server instance.
3. Launch the WebGate installer for your preferred platform, installation mode, and
Web server. For example:
GUI Method:
Windows— Oracle_Access_Manager10_1_4_3_0_Win32_API_Webgate.exe
Console Method:
Solaris—./ Oracle_Access_Manager10_1_4_3_0_sparc-s2_API_Webgate
Linux—./ Oracle_Access_Manager10_1_4_3_0_linux_API_Webgate
where API refers to the API used by your Web server (for example, ISAPI for IIS
Web servers).
4. Dismiss the Welcome screen; follow on-screen instructions with Administrator
privileges.
5. Specify the installation directory for the WebGate.
6. Linux or Solaris: Specify the location of the GCC runtime libraries on this
computer.
7. Language Pack—Choose a Default Locale and any other Locales to install, then
click Next.
8. Record the installation directory name in the preparation worksheet if you haven't
already, then click Next to continue.
Note: On HP-UX and AIX systems, you can direct an installation to a
directory with sufficient space using the -is:tempdir path parameter.
The path must be an absolute path to a file system with sufficient
space.
Locating and Installing the Latest 10g WebGate for Access Manager 11g
30-18 Administrator's Guide for Oracle Access Management
The WebGate installation begins, which may take a few seconds. On Windows
systems, a screen informs you that the Microsoft Managed Interfaces are being
configured.
The installation process is not yet complete. You are asked to specify a transport
security mode. At this point, you cannot go back to restate information.
9. Specify the location where you unzipped the previously downloaded GCC
libraries, if needed.
30.7.4 Specifying a Transport Security Mode
Transport security between at least one OAM Server must match.
To specify a transport security mode
1. Choose Open, Simple, or Cert for the WebGate.
2. Proceed according to your specified transport security mode:
■Simple or Certificate Mode—Go to "Requesting or Installing Certificates for
Secure Communications"
■Open Mode—Skip to Section 30.7.7, "Updating the WebGate Web Server
Configuration"
30.7.5 Requesting or Installing Certificates for Secure Communications
If your Access Manager 11g environment uses Open mode transport security, you can
skip to Section 30.7.7, "Updating the WebGate Web Server Configuration."
WebGate Certificate Request: Generates the request file (aaa_req.pem), which you
must send to a root CA that is trusted by the OAM Server. The root CA returns signed
certificates, which can then be installed for WebGate.
Requested certificates must be copied to the \WebGate_install_dir\access\oblix\config
directory and then the WebGate Web server should be restarted.
To request or install certificates for WebGate 10g
1. Indicate whether you are requesting or installing a certificate, then click Next and
continue. For example:
■Requesting a certificate, proceed with step 2.
■Installing a certificate, skip to step 3.
2. Request a Certificate:
■Enter the requested information, then click Next and issue your request for a
certificate to your CA.
■Record certificate file locations, if these are displayed.
■Click Yes if your certificates are available and continue with step 3. Otherwise,
skip to Section 30.7.7, "Updating the WebGate Web Server Configuration."
3. Install a Certificate During Installation: Specify the full paths to the following
files, then click Next:
See Also: Appendix C, "Securing Communication"
See Also: Appendix C, "Securing Communication"
Locating and Installing the Latest 10g WebGate for Access Manager 11g
Registering and Managing 10g WebGates with Access Manager 11g 30-19
WebGate_install_dir\access\oblix\config
■cacert.pem the certificate request, signed by the Oracle-provided openSSL
Certificate Authority
■password.xml contains the random global passphrase that was designated
during installation, in obfuscated format. This is used to prevent other
customers from using the same CA. Access Manager performs an additional
password check during the initial handshake between the OAM Agent and
OAM Server.
■aaa_key.pem contains your private key (generated by openSSL).
■aaa_cert.pem signed certificates in PEM format.
■Proceed to Section 30.7.7, "Updating the WebGate Web Server Configuration."
30.7.6 Specifying WebGate Configuration Details
You perform the following task using information provided during WebGate
provisioning and registration with Access Manager 11g.
To provide WebGate configuration details
1. Provide the information requested for the WebGate as specified in the Access
System Console.
■WebGate ID—Enter the agent name that you supplied during registration.
■WebGate password—Enter the password supplied during registration, if any.
If no password was entered, leave the field blank.
■Access Server ID—Enter the name of the OAM Server with which this
WebGate is registered, if desired, or use any name you choose.
■Access Server Host Name—Enter the DNS host name for the OAM Server
with which this WebGate is registered
■Port number—Enter the port on which the OAM Proxy is running. If a port
was not entered during provisioning, the default port is 3004.
2. Click Next to continue.
30.7.7 Updating the WebGate Web Server Configuration
Your Web server must be configured to operate with the WebGate. Oracle recommends
automatically updating your Web server configuration during installation. However,
procedures for both automatic and manual updates are included.
Note: To manually update your Web server configuration
1. Click No when asked if you want to proceed with the automatic update,
then click Next.
2. Review the screen that appears to assist you in manually setting up your
WebGate Web server, and see Section 30.7.7.1, "Manually Configuring
Your Web Server."
3. Return to the WebGate installation screen, click Next, and proceed to
Section 30.5, "Registering a 10g WebGate with Access Manager 11g
Remotely."
Locating and Installing the Latest 10g WebGate for Access Manager 11g
30-20 Administrator's Guide for Oracle Access Management
To automatically update your Web server configuration
1. Click Yes to automatically update your Web server then click Next (or click No and
see Section 30.7.7.1, "Manually Configuring Your Web Server"):
■Most Web servers—Specify the absolute path of the directory containing the
Web server configuration file.
■IIS Web Servers—The process begins immediately and may take more than a
minute. For more information, see Chapter 33, "Configuring the IIS Web
Server for 10g WebGates."
You might receive special instructions to perform before you continue. Setting
various permissions for the /access directory is required for IIS WebGates only
when you are installing on a file system that supports NTFS. The last
installation panel provides instructions for manually setting various
permissions that cannot be set on the FAT32 file system. In this case, these
instructions may be ignored.
■Sun Web Servers—Be sure to apply the changes in the Web server
Administration console before you continue.
A screen announces that the Web server configuration has been updated.
2. Click Next and continue with Section 30.7.8, "Finishing WebGate Installation."
30.7.7.1 Manually Configuring Your Web Server
If, during WebGate installation, you declined automatic Web server updates, you must
perform the task manually.
To manually configure your Web server for the WebGate
1. Launch your Web browser, and open the following file, if needed. For example:
\WebGate_install_dir\access\oblix\lang\langTag\docs\config.htm
where \WebGate_install_dir is the directory where you installed the WebGate.
2. Select from the supported Web servers and follow all instructions, which are
specific to each Web server type, as you:
■Make a back up copy of any file that you are required to modify during
WebGate set up, so it is available if you need to start over.
■Ensure that you return to and complete all original setup instructions to
enable your Web server to recognize the appropriate Access Manager files.
Note: If the manual configuration process was launched during
WebGate installation, you can skip Step 1 in the following procedure.
Note: If you choose manual IIS configuration during 64-bit WebGate
installation, you can access details in the following path
WebGate_install_dir\access\oblix\lang\en-us\docs\dotnet_isapi.htm
Locating and Installing the Latest 10g WebGate for Access Manager 11g
Registering and Managing 10g WebGates with Access Manager 11g 30-21
3. Continue with Section 30.7.8, "Finishing WebGate Installation."
30.7.8 Finishing WebGate Installation
The ReadMe information provides details about documentation and Oracle.
To finish the WebGate installation
1. Review the ReadMe information, then click Next to dismiss it.
2. Click Finish to conclude the installation.
3. Restart your Web server to enable configuration updates to take affect.
■IIS Web Servers—Consider using
net stop iisadmin
and
net start w3svc
after installing the WebGate to help ensure that the Metabase does not become
corrupted.
■Security-Enhanced Linux: Run the chcon commands for the WebGate you just
installed on this platform.
4. Proceed with following topics before installing artifacts and certificates:
■Native POSIX Thread Library: When installing Access Manager WebGate for
use with NPTL, there is no need to set the environment variable LD_
ASSUME_KERNEL to 2.4.19.
■Apache2, OHS2, IHS2 Web Servers: Chapter 31, "Configuring Apache, OHS,
IHS for 10g WebGates."
■IIS Web Servers: Consider using
net stop iisadmin
and
net start w3svc
after installing the WebGate to help ensure that the Metabase does not become
corrupted. See also Chapter 33, "Configuring the IIS Web Server for 10g
WebGates."
■ISA Web Servers: Chapter 32, "Configuring the ISA Server for 10g WebGates."
■Lotus Domino Web Servers: Chapter 34, "Configuring Lotus Domino Web
Servers for 10g WebGates."
5. Proceed to Section 30.7.9, "Installing Artifacts and Certificates."
30.7.9 Installing Artifacts and Certificates
The ObAccessClient.xml file is one result of product of provisioning. After WebGate
installation, you must copy the file to the WebGate installation directory path. If you
received signed WebGate 10g certificates after installing WebGate, you can use the
following procedure to install these as well.
Note: If you accidentally closed the window, return to step 1 and
click the appropriate link again. Some setups launch a new browser
window or require you to launch a Command window to input
information.
Note: If you are installing a 64-bit IIS WebGate, see Section 33.8,
"Finishing 64-bit Webgate Installation."
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
30-22 Administrator's Guide for Oracle Access Management
Prerequisites
Configuring your Web server
To install artifacts (and certificates) for WebGate 10g
1. Copy
ObAccessClient.xml
■From:
$WLS_DOMAIN_HOME/output/AGENT_NAME
■To:
$WebGate_install_dir/oblix/lib
Copy
password.xml
■From:
$WLS_DOMAIN_HOME/output/AGENT_NAME
■To:
$WebGate_install_dir/oblix/config
2. Copy aaa_key.pem and aaa_cert.pem:
■From:
$IDM_DOMAIN_HOME/output/AGENT_NAME
■To:
$WebGate_install_dir/oblix/config/simple
The
simple
directory must be created before copying the artifacts.
3. Restart the WebGate Web server.
30.7.10 Confirming WebGate Installation
After WebGate installation and Web server updates, you can enable WebGate
diagnostics to confirm that your WebGate is running properly.
To review WebGate diagnostics
1. Confirm Access Manager 11g components are running.
2. Specify the following URL for WebGate diagnostics. For example:
Most Web
Servers—http(s)://hostname:port/access/oblix/apps/webgate/bin/webgate.cgi?
progid=1
IIS Web Servers—http(s)://hostname:port/access/oblix/apps/
webgate/bin/webgate.dll?progid=1
where hostname refers to the name of the computer hosting the WebGate; port
refers to the Web server instance port number.
3. The WebGate diagnostic page should appear.
■Successful: If the WebGate diagnostic page appears, the WebGate is
functioning properly and you can dismiss the page. Go to Section 30.8,
"Configuring Centralized Logout for 10g WebGate with 11g OAM Servers."
■ Unsuccessful: WebGate should be uninstalled and reinstalled, as described in
Section 30.9, "Removing a 10g WebGate from the Access Manager 11g
Deployment."
30.8 Configuring Centralized Logout for 10g WebGate with 11g OAM
Servers
This section provides the following topics:
■About Centralized Logout with 10g OAM Agents and 11g OAM Servers
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
Registering and Managing 10g WebGates with Access Manager 11g 30-23
■About the Centralized Logout Script for 10g WebGates with 11g OAM Servers
■Configuring Centralized Logout for 10g WebGates with Access Manager
30.8.1 About Centralized Logout Processing for 10g WebGate with 11g OAM Server
The following process overview outlines the Access Manager centralized logout
process that occurs when the application is deployed on the Web server for which the
protecting 10g WebGate is configured.
Logout is initiated when an application causes the invocation of the logout.html file
configured for the OAM agent (in this case, a 10g WebGate).
Process overview: Centralized logout for 10g WebGate with 11g OAM Server
1. The application causes invocation of the logout.html file configured for the 10g
WebGate.
The application might also pass
end_url
as a query string to logout.html. The end_
url parameter could either be a URI or a URL. For example:
/oamsso/logout.html?end_url=/welcome.html
or
/oamsso/logout.html?end_url=http://my.site.com/welcome.html
2. WebGate clears the ObSSOCookie for its domain and loads the logout.html script.
3. If the
end_url
parameter does not include host:port, the logout.html script gets the
host:port of the local server and constructs the
end_url
parameter as a URL. For
example:
http://serverhost:port/oam/server/logout?end_url=http://my.site.com/
welcome.html
4. Logic in logout.html redirect to the OAM Server. For example:
http://myoamserverhost:port/oam/server/logout?end_url=http://my.site.com/
welcome.html
5. The OAM Server executes logout as follows:
a. Cleans up the session information associated with the user at the server side.
b. Validates the
end_url
and sends a page with callback URLs to the user's
browser.
c. From the callback page, a new request is initiated to a specific URI on each
WebGate. When this request reaches the specific WebGate in the specific
domain, the ObSSOCookie for that domain is cleared.
d. The user is redirected to the
end_url
in the logout script. However, if the
end_
url
parameter is not present, an appropriate message is sent by the OAM
Server.
Note: The
Logout Callback URL
is specified in the expanded OAM
Agent registration page, as described in "About Create OAM WebGate
Page and Parameters" on page 15-2 (or remote registration template in
Table 15–3, " Elements on Expanded 11g and 10g WebGate/Access
Client Registration Pages").
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
30-24 Administrator's Guide for Oracle Access Management
For more information, see Section 30.8.2, "About the Centralized Logout Script for 10g
WebGates with 11g OAM Servers."
30.8.2 About the Centralized Logout Script for 10g WebGates with 11g OAM Servers
With an 10g WebGate, the logout.html script is required for both single- and multiple
DNS-domain centralized logout processing. The logout.html activates JavaScripts that
perform the actual logout.
Example 30–1 is a logout.html script that you can use as a template by editing certain
lines for your own environment, which are described at the top of the script. For
instance,
SERVER_LOGOUTURL
must be changed. Additional information is provided
after the example.
Example 30–1 logout.html Script
<html>
<head>
<script language="javascript" type="text/javascript">
///////////////////////////////////////////////////////////////////////////////
//Before using, you need to change the values of:
//a. "oamserverhost" to point to the host where the OAM Server is running.
//b. "port" to point to the port where the OAM Server is running.
///////////////////////////////////////////////////////////////////////////////
var SERVER_LOGOUTURL = "http://oamserverhost:port/oam/server/logout";
///////////////////////////////////////////////////////////////////////////////
function handleLogout() {
//get protocol used at the server (http/https)
var webServerProtocol = window.location.protocol;
//get server host:port
var webServerHostPort = window.location.host;
//get query string present in this URL
var origQueryString = window.location.search.substring(1);
var newQueryString = "";
//vars to parse the querystring
var params = new Array();
var par = new Array();
var val;
if (origQueryString != null && origQueryString != "") {
params = origQueryString.split("&");
for (var i=0; i<params.length; i++) {
if (i == 0)
newQueryString = "?";
if (i > 0)
newQueryString = newQueryString + "&";
par = params[i].split("=");
Note: 11g WebGates do not use the logout.html script and instead
require additional details in their Agent registration configuration, as
described in Section 30.8, "Configuring Centralized Logout for 10g
WebGate with 11g OAM Servers."
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
Registering and Managing 10g WebGates with Access Manager 11g 30-25
//prepare a new query string, if the end_url value needs to be changed
newQueryString = newQueryString + (par[0]);
newQueryString = newQueryString + "=";
val = par[1];
if ("end_url" == par[0]) {
//check if val (value of end_url) begins with "/" or "%2F" (is it an URI?)
if (val.substring(0,1) == "/" || val.substring(0,1) == "%") {
//modify the query string now
val = webServerProtocol + "//" + webServerHostPort + val;
}
}
newQueryString = newQueryString + val;
}
}
//redirect the user to this URL
window.location.href = SERVER_LOGOUTURL + newQueryString;
}
</script>
</head>
<body onLoad="handleLogout();">
</body>
</html>
Process overview: Logic in logout.html
1. Gets the host and port from the incoming request.
2. Gets the
end_url
parameter from the query string.
If the
end_url
parameter is not a URL, then the logout.html script constructs a
URL using the host and port from task 1. See "Guidelines for the end_url
parameter in logout.html" following this section.
3. Redirects to the OAM Server logout URL (SERVER_LOGOUTURL). For example:
http://myoamserver/host:port/oam/server/logout.
■Use the
end_url
constructed in process 2 as the query string.
■Preserve all other query string parameters in the query string.
Guidelines for the end_url parameter in logout.html
The
end_url
parameter can be either a URI or an URL.
■If the
end_url
query string is a URI, without host and port, then the logout.html
must construct the URL by determining the host and port of the Web Server where
logout.html is hosted. For example:
http://myoamserverhost:port/oam/server/logout?end_url=http://my
.site.com/welcome.html
■If the
end_url
parameter is a URL with the host and port, the logout.html script
simply passes that on without reconstructing it.
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
30-26 Administrator's Guide for Oracle Access Management
Table 30–5 illustrates how a logout link in the logout.html file might be specified:
30.8.3 Configuring Centralized Logout for 10g WebGates with Access Manager
The following procedures describe how to configure centralized logout for 10g
WebGates with Access Manager.
Oracle Fusion Middleware Application Security Guide includes a sample procedure
that includes steps for deploying an application in a WebLogic Server domain.
Task overview: Configuring centralized logout for 10g WebGates
1. Create a default logout page (logout.html) and make it available on the WebGate
installation directory:
a. Create and edit logout.html for the WebGate based on Example 30–1,
"logout.html Script".
b. Store your logout.html script in the following directory path:
WebGate_install_dir/oamsso/logout.html
c. Proceed with following steps, as needed.
2. Ensure that the logout.html (from Step 1) redirects the user to this central logout
URI, "/oam/server/logout' on the 11g OAM Server.
Note: An ADF application must pass the
end_url
parameter
indicating where to redirect the user after logout, as described in
Section A.3, "Configuring Centralized Logout for Oracle ADF-Coded
Applications."
/<app context root>/adfAuthentication?logout=true&end_url=<any uri>
Table 30–5 Sample end_url Parameter Specifications
As a ... Sample end_url Value
URI
/oamsso/logout.html?end_url=<someUri>
For example:
/oamsso/logout.html?end_url=/welcome.html
URL
/oamsso/logout.html?end_url=<someUrl>
For example:
/oamsso/logout.html?end_url=http://my.site.com/welcome.html
Note: Optional tasks or those required for only multiple DNS
domain logout are identified and can be skipped unless needed.
Note: If the logout.html file is located elsewhere, ensure that the
logout link is correctly specified in the agent registration to point to
the correct location of the logout.html file.
Removing a 10g WebGate from the Access Manager 11g Deployment
Registering and Managing 10g WebGates with Access Manager 11g 30-27
3. Optional: Allow the application to pass the end_url parameter indicating where to
redirect the user after logout, as described in "Guidelines for the end_url
parameter in logout.html" in Section 30.8.2.
4. Check the Web server file for which the 10g WebGate is configured and perform
the appropriate step:
■OHS Web server, httpd.conf file: If the following lines exist, delete them:
<LocationMatch "/oamsso/*">
Satisfy any
</LocationMatch>
■Other Web servers, configuration file: Add the following line:
Alias /oamsso "WebGateInstallationDirectory/oamsso"
30.9 Removing a 10g WebGate from the Access Manager 11g Deployment
Use the following procedure to remove the 10g WebGate from the Access Manager 11g
deployment, if needed.
Considerations
Web Server Configuration Changes: Web server configuration changes must be
manually reverted after uninstalling the WebGate). For more information about what
is added, see the appropriate chapter for your Web server.
WebGate IIS Filters: To fully remove a WebGate and related filters from IIS, you must
do more than simply remove the filters from the list in IIS. IIS retains all of its settings
in a metabase file. On Windows 2000 and later, this is an XML file that can be modified
by hand.
Prerequisites
Evaluate the Application Domain, resources, and policies associated with this agent
and ensure that these are configured to use another agent or that they can be removed.
To uninstall the 10g WebGate
1. Turn off the Web server for the WebGate you will remove.
2. On the WebGate registration page in the Oracle Access Management Console, click
the Disable box beside the State option to disable the WebGate.
3. Language Packs: Remove installed Language Packs (except the one selected as the
default Administrator language (locale)) as follows:
■Locate the appropriate Language Pack file in the component's uninstall
directory. For example:
WebGate_install_dir\uninstIdentityLP_fr-fr
Note: Deleting an agent registration does not remove the associated
host identifier, Application Domain, resources, or the agent instance.
Note: If you don't turn off the Web server, uninstall might fail and
the backup folder will not be removed. If this happens, you need to
manually remove the backup folder.
Removing a 10g WebGate from the Access Manager 11g Deployment
30-28 Administrator's Guide for Oracle Access Management
\uninstaller.exe
■Run the Language Pack Uninstaller program to remove the files.
■Repeat this process to remove the same Language Pack from associated
components.
■Stop and restart WebGate Web server to re-initialize proper language support.
■Repeat this process to remove each Language Pack (except the one selected as
the default Administrator language (locale)).
4. Perform the following steps to remove 10g WebGate configuration data:
■If you have only one instance of an Access Manager component, complete step
4 to remove it.
■If you have multiple instances of a component, see also step 5.
5. Locate and run the Uninstaller program for the specific component to remove
Access Manager files. For example:
WebGate_install_dir\access\_uninstWebGate\uninstaller.exe
6. Multiple Instances: If you have multiple WebGate instances and want to remove
one or all of them, you must use a specific method for your platform:
■Windows: The last component can be uninstalled from Add/Remove
programs. Others can be uninstalled by running the uninstall program from
the \access \uninstComponent directory.
■UNIX: You must always run uninstaller.bin.
7. Remove Access Manager-related updates to your Web server configuration. For
details about specific Web servers, see Chapter 31, "Configuring Apache, OHS, IHS
for 10g WebGates," Chapter 32, "Configuring the ISA Server for 10g WebGates,"
Chapter 33, "Configuring the IIS Web Server for 10g WebGates,", and Chapter 34,
"Configuring Lotus Domino Web Servers for 10g WebGates."
8. Restart the Web server.
9. Remove the WebGate_install_dir directory if it remains, especially if you plan to
reinstall it.
Note: On UNIX systems, use uninstaller.bin
31
Configuring Apache, OHS, IHS for 10g WebGates 31-1
31
Configuring Apache, OHS, IHS for 10g
WebGates
Oracle provides WebGates for Web servers powered by Apache v2. This includes
Apache, Oracle HTTP Server, and IBM HTTP Server (IHS).
This chapter provides details about configuring the three Web server types, and
includes:
■About Oracle HTTP Server and Access Manager
■About Access Manager with Apache and IHS v2 Webgates
■About Apache v2 Architecture and Access Manager
■Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers
■Preparing Your Web Server
■Activating Reverse Proxy for Apache v2 and IHS v2
■Verifying httpd.conf Updates for Webgates
■Tuning Oracle HTTP Server Webgates for Access Manager
■Tuning OHS /Apache Prefork and Worker MPM Modules for OAM
■Starting and Stopping Oracle HTTP Server Web Servers
■Tuning Apache/IHS v2 Webgates for Access Manager
■Removing Web Server Configuration Changes After Uninstall
■Helpful Information
31.1 Prerequisites
Ensure that your Oracle Access Management Console is running and get familiar with:
■"Introduction to Policy Enforcement Agents" on page 14-1
■"About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2" on
page 30-3
31.2 About Oracle HTTP Server and Access Manager
Access Manager Web component package names for Oracle HTTP Server are
designated with OHS, as follows:
■Oracle HTTP Server 11g is based on Apache v2.2; package names include OHS11g,
for example:
About Access Manager with Apache and IHS v2 Webgates
31-2 Administrator's Guide for Oracle Access Management
Oracle_Access_Manager10_1_4_3_0_ platform_OHS11g_Webgate
■Oracle HTTP Server 10g R2 (10.1.2) and 10g (10.1.3.1.0) provide packages based on
Apache v1.3 and Apache v2.0:
Apache v2.0-based packages include OHS2, for example:
Oracle_Access_Manager10_1_4_3_0_platform_OHS2_Webgate
Apache v1.3-based packages include OHS, for example:
Oracle_Access_Manager10_1_4_3_0_platform_OHS_Webgate
The following Oracle HTTP Server releases operate with Access Manager:
Oracle HTTP Server 11g: Access Manager Webgates Oracle HTTP Server 11g can be
used like Webgates for any other Web server. In addition, this Webgate for Oracle
HTTP Server 11g is a key component when configuring enterprise-level single sign-on
for Oracle Fusion Middleware 11g. For details, see the Oracle Fusion Middleware
Security Guide. See also the Oracle Fusion Middleware Administrator's Guide for HTTP
Server 11g Release 1 (11.1.1).
Oracle HTTP Server 10g (10.1.3.1.0): Provides two packages (one based on Apache v1.3
and another based on Apache v2.0). Webgates can be installed on a standalone Oracle
HTTP Server. OHS2 Webgate must be installed on the Oracle Application Server to
enable integration with Oracle single sign-on. During installation, the Webgate is
installed as a module on OHS2.
Be sure to familiarize yourself with Oracle HTTP Server Web component
requirements, as described in "Preparing Your Web Server" on page 31-7.
31.3 About Access Manager with Apache and IHS v2 Webgates
Access Manager provides components for Apache v2 Web servers and the IBM HTTP
Server in addition to the Oracle HTTP Server. The IBM HTTP Server (IHS2) is a
variation of Apache v2. Unless otherwise stated, the following information applies to
all three:
■Apache v2.0.5.2 Webgate
■Apache v2.0.48 Webgate, including reverse proxy if you choose to activate this
capability.
■Apache v2.0.47 Webgate for the IBM HTTP Server (IHS2) powered by Apache,
including reverse proxy if you choose to activate this capability.
Each platform-specific installation package supports both plain and SSL-capable
Apache modes. The number 2 in a file name indicates that this component is based on
Apache v2. For example:
AIX: Oracle_Access_Manager10_1_4_3_0_power-aix_IHS2_Webgate
Linux: Oracle_Access_Manager10_1_4_3_0_ linux_Apache2_Webgate
Solaris: Oracle_Access_Manager10_1_4_3_0_sparc-s2_Apache2_Webgate
Windows: Oracle_Access_Manager10_1_4_3_0_Win32_APACHE2_Webgate
Note: For the latest Access Manager certification information, see:
http://www.oracle.com/technology/products/id_mgmt/coreid_
acc/pdf/oracle_access_manager_certification_10.1.4_r3_matrix.xls
About Access Manager with Apache and IHS v2 Webgates
Configuring Apache, OHS, IHS for 10g WebGates 31-3
Earlier Access Manager releases included separate platform-specific installation
packages for plain versus SSL-capable modes. For example, two Webgate files were
provided for each platform: the APACHE_Webgate, and the APACHESSL_Webgate.
There have been no functional changes to Access Manager components to support
these Web servers. Access Manager authentication occurs through the Webgate using
HTTP basic, form, or SSL client certificates. Authorization for Web resources by
authenticated users, and simple and multi-domain SSO with other Web servers or
applications, also occurs through the Webgate.
31.3.1 About the Apache HTTP Server
The Apache HTTP Server is an open-source HTTP Web server project of the Apache
Software Foundation. The project goal is to provide a secure, efficient and extensible
server and HTTP services that meet current HTTP standards.
For more information, see "About Apache v2 Architecture and Access Manager" on
page 31-4.
31.3.2 About the IBM HTTP Server
The IBM HTTP Server (IHS) is a variation of Apache v2. Portions of the IBM HTTP
Server are based on software developed by The Apache Group. The IBM HTTP Server
component also includes software developed by the OpenSSL Project and software
developed by Eric Young.
Details about the Apache architecture and Access Manager, discussed in "About
Apache v2 Architecture and Access Manager" on page 31-4 apply to IHS with the
following exceptions:
■Previous versions of IHS required a separate IDS Client to use the mod_ibm_ldap
module. With IHS powered by Apache v2.0.47, this is not a requirement.
■IHS v2.0.47 supports FIPS 140-2. FIPS support is disabled by default. To enable
FIPS support, just add the SSLFIPSEnable directive to the httpd.conf file. Similarly,
use SSLFIPSDisable directive to disable FIPS support.
■On AIX, ensure that the appropriate runtime library is installed before you install
IHS v2.0.47.
For example on AIX 5.1, the xlC.rte 6.0 runtime library (for example: xlC.rte.6.0.0.0)
must be installed before you install IHS v2.0.47. This library is required on AIX to
install and use SSL with IHS v2. You can download this library from the following
Web site:
http://www-912.ibm.com/eserver/support/fixes/fcgui.jsp
31.3.3 About the Apache and IBM HTTP Reverse Proxy Server
Typically, a reverse proxy is used in the following situations:
■To provide Internet users with access to a server behind a firewall
■To balance the load among several back-end servers, or to provide caching for a
slower back-end server
■To bring several servers into the same URL space
The proxy_module implements a proxy/gateway for Apache and IHS powered by
Apache. The client requires no special configuration; a reverse proxy appears like an
About Apache v2 Architecture and Access Manager
31-4 Administrator's Guide for Oracle Access Management
ordinary Web server. The client makes requests as usual for content in the name-space
of the reverse proxy. It is the reverse proxy that decides where those requests are sent.
Content is returned as if the reverse proxy was the origin.
For more information, see "Requirements for Apache v2 Web Servers" on page 31-6.
31.4 About Apache v2 Architecture and Access Manager
The Apache v2 Web server provides a hybrid multi-threaded, multi-process
architecture that is compatible with the thread-safe Access Manager libraries.
In addition to the standard set of modules, the Apache v2 Web server includes
Multi-Process Modules (MPMs) to bind network ports on the computer and to accept
and process requests. The appropriate MPM must be compiled into the server and
activated before you install an Apache or IHS v2 Webgate:
■On Windows: mpm_winnt is the default MPM on Windows platforms. mpm_
winnt can use native networking features rather than the POSIX layer used in
Apache 1.3.
■On UNIX: The prefork MPM is the default MPM for Apache v2 Web servers on
UNIX platforms. The prefork MPM implements a non-threaded, pre-forking Web
server that handles requests in a manner similar to Apache v1.3.
■On AIX: The worker MPM is the default MPM for IHS v2 on the AIX platform.
The worker MPM implements a hybrid multi-process, multi-threaded server. The
most important directives used to control this MPM are ThreadsPerChild and
MaxClients. For details, see "Tuning Apache/IHS v2 Webgates for Access
Manager" on page 31-27.
The Apache v2 Web server includes an Apache Portable Runtime (APR) library that
provides an interface to platform-specific implementations, assures API developers
predictable if not identical behavior regardless of platform, and eliminates the need for
conditional compilation #lfdefs. Although backward compatibility is supported with
the include/apu_compat.h file, using the Apache v2 APR is recommended.
For more information, see your Apache v2 documentation. See also, "Tuning
Apache/IHS v2 Webgates for Access Manager" on page 31-27.
Important: The proxy_module can be used to implement a proxy
capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and
HTTP/1.1. However, only the reverse proxy capability is supported
with the Webgate.
Important: Unless explicitly stated otherwise, all details in this
discussion apply equally to Apache v2 and IHS v2 Web Servers for
10g Webgates.
Note: If you compile Apache on UNIX with the mpm_worker_
module for Webgate, you need to optimize the default pthread
stacksize for Webgate to ensure optimal performance during
multithreaded server implementation as described in "Apache v2 on
UNIX with the mpm_worker_module for Webgate" on page E-32.
Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers
Configuring Apache, OHS, IHS for 10g WebGates 31-5
The Apache architecture affects Access Manager components in different ways, as
discussed in the following sections.
For Webgates installed with IHS and Apache v2
■There is no shared cache between processes.
■Each process maintains its own connections to the Access Server. Therefore, you
should limit the number of Webgate connections. This issue is partially affected by
the performance of the systems running the Web servers and Access Servers.
Limitations of Apache and IHS v2 Web Servers
Due to limitations of the Apache v2 Web server, plug-ins configured for the Access
Manager form-based authentication scheme do not pass variables when:
■The optional challenge parameter, passthrough:Yes, is included in the
authentication scheme to pass login credentials through to a post-processing
program.
■The form action is a CGI script that dumps all headers and variables passed to it
and the method is called using the HTTP POST method.
For example:
<html>
<form name="myloginform" action="/access/...cgi" method="post">
31.5 Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers
Access Manager HTML pages use UTF-8 encoding. Apache-based Web servers,
including Apache, Oracle HTTP Server, and IBM HTTP Server (IHS) allow
Administrators to specify a default character set for all HTML pages sent out using the
AddDefaultCharset
directive. This directive overrides any character specified by the
application generating the HTML pages. If the
AddDefaultCharset
directive enables a
character set other than UTF-8, Access Manager HTML pages are garbled.
Oracle recommends that you specify the
AddDefaultCharset
directive in the Web
server configuration file (httpd.conf) as follows to ensure the correct display of Access
Manager HTML pages:
AddDefaultCharset Off
See your Web server documentation for more information about this directive.
The following topics provide additional details you should be aware of:
■Requirements for IHS2 Web Servers
■Requirements for Apache and IHS v2 Reverse Proxy Servers
Note: Webgates for Apache v2 (and derivatives) can be used in
installations that contain Webgates for other Web servers.
If you compile Apache on UNIX with the mpm_worker_module for
Webgate, you need to optimize the default pthread stacksize for
Webgate to ensure optimal performance during multithreaded server
implementation as described in "Apache v2 on UNIX with the mpm_
worker_module for Webgate" on page E-32.
Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers
31-6 Administrator's Guide for Oracle Access Management
■Requirements for Apache v2 Web Servers
31.5.1 Requirements for IHS2 Web Servers
This discussion identifies specific requirements for IHS v2 with Access Manager. With
IHS v2, you do not compile any source code to get the binaries. However, the
following requirements do apply to IHS v2 Web servers:
■For an SSL capable configuration on AIX, the xLC.rte.6.0 runtime library is
required.
■For an SSL capable configuration, the GSKit7 is required and can be downloaded
from
https://techsupport.services.ibm.com/server/aix.fdc
.
31.5.2 Requirements for Apache and IHS v2 Reverse Proxy Servers
As discussed earlier, the proxy_module implements a proxy/gateway. The client
requires no special configuration. Although the proxy_module can be used to
implement a proxy capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and
HTTP/1.1, only the reverse proxy capability is supported with certain Access Manager
Apache and IHS v2 Webgates.
For Apache Web Servers: To use reverse proxy functions with Access Manager, you
need to include the proxy module in the configure command. For example:
--enable-proxy: Apache proxy module
--enable-proxy-connect: Apache proxy CONNECT module
--enable-proxy-ftp: Apache proxy FTP module
--enable-proxy-http: Apache proxy HTTP module
You also need to load mod_proxy and the mod_proxy_http module into the server
dynamically. A reverse proxy is activated using the ProxyPass directive or the [P] flag
to the RewriteRule directive.
For IHS Web Servers: After installing the IHS Web server, reverse proxy
configurations must be completed in the httpd.conf file in the following directory:
IHS_install_dir/conf directory
For more information, see "Activating Reverse Proxy for Apache v2 and IHS v2" on
page 31-19.
31.5.3 Requirements for Apache v2 Web Servers
This discussion identifies specific requirements for Apache v2 with Access Manager.
Additional information can be found in your Apache documentation:
PATH Variable: On UNIX systems, your PATH variable must contain the gcc location
before you compile Apache v2. However, the Sun C compiler location must not be in
your PATH variable. On Windows systems, Apache can be built using either
command-line tools or the Visual Studio IDE Workbench. The command-line build
requires that the environment reflect the PATH, INCLUDE, LIB and other variables
that can be configured with the vcvars32 batch file.
Multi-Process Module (MPM): With Apache v2, a default MPM is provided for each
platform to bind network ports on the computer and to accept and process requests.
Apache must have one, and only one, MPM in use at any time. If no MPM is selected
during compilation, the default will be loaded into the Web server. You may activate
the MPM during compilation.
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-7
mod_ssl: Access Manager supports Apache with or without SSL-capable
communication. The base Apache Web server does not use SSL for browser
connections and will not respond to HTTPS requests. For SSL-capable communication,
Access Manager supports Apache with mod_ssl only. No SSL-specific Access Manager
features operate with Apache-SSL.
mod_ssl relies on OpenSSL to provide the cryptography engine; mod_ssl provides an
interface to the OpenSSL library. The OpenSSL library provides Strong Encryption
using the Secure Sockets Layer and Transport Layer Security protocols.
With previous versions of Apache, the mod_ssl module had to be downloaded
separately and compiled into the server. With Apache HTTP Server v2 module, mod_
ssl comes as a loadable module that you can enable during configuration.
Multi-threading: Multi-threading is required for installations with Apache v1.3.27 or
later.
Dynamic Shared Object (DSO): DSO support is required for Webgate. Apache
modules that extend basic core server functionality may be either statically compiled
for permanent inclusion in the Apache binary, or dynamically compiled and stored
separately to load at runtime without recompiling. With Apache v1.3, mod_so had to
be compiled. With Apache v2 on Windows systems, mod_so is a Base module and
always included. With Apache v2 on UNIX, the loaded code typically comes from
shared object files.
mod_perl: mod_perl embeds the Perl programming language in the Apache Web
server. Without Perl, Apache v2 can still be built and installed; however, some support
scripts written in Perl cannot be used.
31.6 Preparing Your Web Server
The methods and steps to prepare your host computer for the Access Manager Web
component installation depends upon the specific Web server and platform, as
discussed in the following task overview.
To use reverse proxy functions with Access Manager, you need to include the proxy
module in the configure command, as discussed in "About the Apache and IBM HTTP
Reverse Proxy Server" on page 31-3. See also "Activating Reverse Proxy for Apache v2
and IHS v2" on page 31-19.
Task overview: Preparing your Web server and installing Access Manager
1. Install the IHS v2 Web server or compile and install the Apache v2 Web server as
discussed in:
■Preparing the IHS v2 Web Server
■Preparing Apache and Oracle HTTP Server Web Servers on Linux
Note: Dynamically loaded Apache 1.3 modules cannot be used
directly with Apache v2. Apache v1.3 modules must be modified to
load dynamically or compile into Apache v2.
Note: With Apache v.1.3.2x, some operating systems required
additional options during configuration. However, to build Apache
v2, there is no need to set any additional variables.
Preparing Your Web Server
31-8 Administrator's Guide for Oracle Access Management
■Preparing Oracle HTTP Server Web Servers on Linux and Windows Platforms
■Setting Oracle HTTP Server Client Certificates
■Preparing the Apache v2 Web Server on UNIX
■Preparing the Apache v2 SSL Web Server on AIX
■Preparing the Apache v2 Web Server on Windows
2. Activate reverse proxy capability if desired, as described in "Activating Reverse
Proxy for Apache v2 and IHS v2" on page 31-19.
3. Install Oracle Access Management, as described in Oracle Fusion Middleware
Installation Guide for Oracle Identity and Access Management.
4. Finish Web server configuration, as described in "Verifying httpd.conf Updates for
Webgates" on page 31-22.
5. Refer to the following topics as needed:
■"Tuning Oracle HTTP Server Webgates for Access Manager" on page 31-25
■"Tuning OHS /Apache Prefork and Worker MPM Modules for OAM" on
page 31-25
■"Tuning Apache/IHS v2 Webgates for Access Manager" on page 31-27
31.6.1 Preparing the IHS v2 Web Server
To prepare your IHS v2 Web server to accept and use the Webgate for IHS v2, you
need to complete one or more of the following procedures, depending on your
environment and requirements:
■Preparing the Host for IHS v2 Installation
■Installing the IBM HTTP Server v2
■Setting Up SSL-Capability
■Starting a Secure Virtual Host
■Activating Reverse Proxy for Apache v2 and IHS v2
When you have completed the appropriate procedures, you are ready to install the
Webgate for IHS v2.
31.6.1.1 Preparing the Host for IHS v2 Installation
You need to complete this procedure to set up the host computer before you install the
IHS Web server. For additional information, see "Requirements for IHS2 Web Servers"
on page 31-6 and "Requirements for Apache v2 Web Servers" on page 31-6.
This example illustrates installation on AIX 5.1. Your environment may vary.
To prepare for IHS v2 installation
1. On the host computer, download and install the IBM Developer Kit, Java
Technology Edition version 1.4 from the following site:
Note: In all the procedures that follow, path name variables,
modules, and options are examples provided only to illustrate the
steps. Your environment will vary. Refer to your Web server
documentation for additional details.
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-9
http://www.ibm.com/java/jdk
The IBM Developer Kit ships with the WebSphere Application Server or can be
downloaded from this site.
2. On the host computer, download and install the xlC.rte 6.0 runtime for AIX 5.1,
which is required by the GSKit7 runtime executable from the following site:
https://techsupport.services.ibm.com/server/aix.fdc
3. On the host computer, create a new directory in which you will uncompress the
IBM HTTP Server install image.
4. On the host computer, download the IBM HTTP Server install image from the
following Web site:
http://www-306.ibm.com/software/webservers/httpservers/
5. On the host computer, uncompress the install image in your new directory.
For example:
tar -xf IHS.tar
A listing of the following files appears, based on your operating system:
gskit.sh
setup.jar
gskta.rte (a GSKit runtime executable for AIX)
You are ready to begin the installation, as described next.
6. Proceed to "Installing the IBM HTTP Server v2" on page 31-9.
31.6.1.2 Installing the IBM HTTP Server v2
The procedure that follows walks you through a typical IBM HTTP Web server
installation. Alternatively, you may choose to perform a silent installation. In this case,
you use silent.res file with the
java -jar setup.jar
-silent -options silent.res
command. You can customize silent install options by editing the silent.res text file. All
options are set to true by default. To disable an option, set its value to false.
To install the IBM HTTP Web server powered by Apache v2
1. Set your path to point to the Java Technology Edition version 1.4 installed on your
computer in the previous example. For example:
export PATH=$PATH:/usr/java14/java/bin
2. From to the directory where you uncompress the install image, type the following
command:
java -jar setup.jar
3. Choose the language in which to run the installation.
The Welcome to the InstallShield Wizard for the IBM HTTP Server appears.
4. Click Next to dismiss the Welcome screen.
5. Specify the directory name. For example:
AIX: /usr/IBMIHS/
Preparing Your Web Server
31-10 Administrator's Guide for Oracle Access Management
6. Click Next to continue.
Options appear for a typical, custom, or developer installation. When you choose a
typical installation, a list will appear with everything included and the size of the
image. If you choose a custom installation, a list of components appears and you
can clear the box next to the any components you do not want to install.
7. Select the type of installation you would like to perform, then click Next. For
example:
Typical
The following message appears. You can click Cancel to stop the installation.
Installing IBM HTTP Server. Please wait.
The next message also appears. You can click Cancel to stop the inventory update.
Updating the inventory.
8. Click Finish to complete your installation.
9. Stop then start the IHS server using the apachectl commands, as follows:
For example:
IHS2_install_dir/bin
./apachectl stop
./apachectl start
where IHS2_install_dir is the directory where you installed the IHS v2 Web server.
You may configure the IHS v2 Web server in several modes either before or after
installing the Webgate for IHS v2:
■Setting Up SSL-Capability
■Starting a Secure Virtual Host
■Activating Reverse Proxy for Apache v2 and IHS v2
31.6.1.3 Setting Up SSL-Capability
If you need to setup SSL-capability, use the following procedure either before or after
installing the Webgate for IHS v2.
To setup SSL for IHS v2 using the default configuration file
1. Locate and open the following file:
IHS2_install_dir/conf/httpd.conf
2. Specify the SSLEnable directive to enable SSL.
3. Specify a Keyfile directive and any SSL directives you want to enable.
4. Stop then start the IHS server, as follows. For example:
IHS2_install_dir/bin
./apachectl stop
./apachectl start
where IHS2_install_dir is the directory where you installed the IHS v2 Web server.
5. Continue with the following procedures:
■Starting a Secure Virtual Host
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-11
■Activating Reverse Proxy for Apache v2 and IHS v2
31.6.1.4 Starting a Secure Virtual Host
If you need to start a secure virtual host, use the following procedure either before or
after installing the Webgate for IHS v2.
To start an IHS v2 secure virtual host
1. Locate and open the following file:
IHS2_install_dir/conf/httpd.conf
where IHS2_install_dir is the directory where you installed the IHS v2 Web server.
2. Specify the SSLEnable directive in the virtual host stanza of the configuration file,
to enable SSL for a virtual host.
You can specify any directive, with the exception of the cache directives, inside a
virtual host.
3. Specify a Keyfile directive and any SSL directives you want to enable for that
particular virtual host.
4. Load the mod_ibm_ssl.so using the LoadModule directive in the conf file.
5. Stop then start the IHS virtual host, as follows. For example:
IHS2_install_dir/bin
./apachectl stop
./apachectl start
6. Continue with Activating Reverse Proxy for Apache v2 and IHS v2.
31.6.2 Preparing Apache and Oracle HTTP Server Web Servers on Linux
When installing Webgates for Apache or Oracle HTTP Server on Linux, you are
prompted to install as the same user under which the Web server is running. See the
User and Group directive entries in the httpd.conf file.
When installing Access Manager Webgates for vendor-bundled Apache v2 on Red Hat
Enterprise Linux 4, ensure that all Webgates are installed for Web server user & group
(default: apache). See also "Tuning Apache/IHS v2 Webgates for Access Manager" on
page 31-27.
31.6.3 Preparing Oracle HTTP Server Web Servers on Linux and Windows Platforms
When using Webgates for Oracle HTTP Server v2 on Windows and Linux platforms,
both the Perl module and the PHP module must be commented out in the httpd.conf.
Note: The start and stop instructions for an SSL implementation are
the same as non-SSL-capable implementations.
Note: On Linux, Webgates for Oracle HTTP Server 11g use only
NPTL; you cannot use the LinuxThreads library. In this case, do not
set the environment variable LD_ASSUME_KERNEL to 2.4.19.
Preparing Your Web Server
31-12 Administrator's Guide for Oracle Access Management
31.6.4 Setting Oracle HTTP Server Client Certificates
When using cert_decode and credential_mapping authentication modules, you must
ensure that the Client Certificate authentication scheme works properly with
SSL-enabled Oracle HTTP Server by adding
+EarlierEnvVars
and
+ExportCertData
to the existing SSL options in the Oracle HTTP Server Web server configuration file.
For example:
credential_mapping:
obMappingBase="o=company,c=us",obMappingFilter=
"(&(objectclass=InetOrgPerson)(mail=%certSubject.E%))"
ssl.conf must include:
SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars
To add ssl options to Oracle HTTP Server
1. Locate and open the Oracle HTTP Server Web server configuration file with a text
editor. For example:
$ORACLE_INSTANCE/ohs/conf/ssl.conf
2. In the ssl.conf file, add the following information to existing SSL options. For
example:
SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars
3. Save the file and restart the Web server.
31.6.5 Preparing the Apache v2 Web Server on UNIX
This discussion provides an overview and steps to prepare the Apache v2 HTTP Web
server for Access Manager on UNIX platforms, including Solaris, UNIX, Linux, and
AIX. See also "Preparing the Apache v2 SSL Web Server on AIX" on page 31-16
Apache v2 can be configured, built, and installed plain or as SSL-capable. After
downloading and extracting Apache source files, you use a script (configure script on
UNIX and the makefile.win make script for Windows) to compile the source tree for
your environment.
When you configure Apache v2 on UNIX platforms, you specify the installation
directory path name using the
-prefix=
option with the
./configure
command.
During configuration you enable the modules that are appropriate for your
environment. For example, mod_so is included in the server automatically when
dynamic modules are included in the compilation. However, you can ensure the server
is capable of loading DSOs by including the
-enable-so
option with the configure
Note: With Oracle HTTP Server 11g, there is no need to comment out
any module for Webgates on any platform.
Note: Basic requirements are the same regardless of your platform.
However, the remainder of this discussion and the procedures that
follow focus on UNIX platforms. For more information, see also
"Preparing the Apache v2 SSL Web Server on AIX" on page 31-16.
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-13
command. If you have multiple Perl interpreters installed, you can include the
-with-perl option to ensure the correct interpreter is selected during configuration.
In the configure command, you can also include the options to enable mod_ssl, and to
activate an MPM. After configuration, you can verify which MPM was chosen using
./httpd -l
to list every module that is compiled into the server.
When you finish configuring Apache, you build the various parts that form the
Apache package using the make command then install the package under the
installation directory you specified with the
-prefix=
option during configuration.
For steps and examples, see the following procedures and your Apache
documentation:
■To prepare plain Apache v2 for UNIX
■To prepare SSL-capable Apache v2 on UNIX
■To prepare Apache v2 for Windows
■Activating Reverse Proxy for Apache v2 and IHS v2
In the procedures that follow, path name variables, modules, and options are examples
provided only to illustrate the steps. Your environment will vary. Refer to your Web
server documentation for additional details. There is no difference in the build
procedure between Apache v2.0.48 and v2.0.52.
To prepare plain Apache v2 for UNIX
1. Confirm that your environment meets Apache requirements for the appropriate
compiler and build tools, as described in Apache documentation located at:
http://httpd.apache.org/docs-2.0/install.html#requirements
2. Download a complete, unmodified version of the Apache HTTP Server v2, as
described in the Apache documentation. For example:
http://httpd.apache.org/download.cgi
3. Extract (uncompress, then untar) source files from the tarball, as described in the
Apache documentation. For example:
gzip -d httpd-2_0_48.tar.gz
tar -xvf httpd-2_0_48.tar
You can use the following step as an example of configuring the Apache source
tree. If you compile Apache on UNIX with the mpm_worker_module for Webgate,
see "Apache v2 on UNIX with the mpm_worker_module for Webgate" on
page E-32.
Note: There are no known restrictions with regard to supported
compiler versions for Apache v2 and Access Manager plug-ins. See
the Apache documentation.
Note: Be sure to download Perl, if needed.
Preparing Your Web Server
31-14 Administrator's Guide for Oracle Access Management
4. Ensure that you have the correct version of GNU gcc libraries in the proper path to
build the Apache source; gcc libraries should be in the PATH:
export PATH=/usr/local/packages/gcc-3.4.6/bin:$PATH
5. Configure the Apache source tree and enable or activate the desired modules
using details in the Apache documentation. For example:
cd apache_source_dir
./configure --with-mpm=prefork --prefix=apache_install_dir --with-included-apr
./configure --with-mpm=worker --prefix=apache_install_dir --with-included-apr
where apache_source_dir refers to the directory where you extracted Apache and
apache_install_dir refers to the directory where you want to install Apache.
6. Compile the Apache package you configured using the make command. For
example:
make
7. Install the Apache package in the configured directory path that you specified
earlier using the --prefix= option. For example:
make install
8. Customize the installation using instructions in the Apache documentation.
For example, you may need to tune the httpd.conf to set basic values for:
ServerName
User/owner of the WebServer
Group
9. Stop then restart the Apache Web server to test the installation using commands in
the apache_install_dir/bin directory. For example:
./apachect1 stop
./apachectl start
10. Continue with appropriate tasks for your environment, as follows:
■To prepare SSL-capable Apache v2 on UNIX
■Preparing the Apache v2 Web Server on UNIX
■Activating Reverse Proxy for Apache v2 and IHS v2
The following procedure outlines how to prepare an SSL-capable Apache v2 Web
server on UNIX. The Apache mod_ssl is loadable; however, this installation requires
the Open Source toolkit for SSL/TLS. Again, be sure to download Perl, if needed. If
AIX is the platform you are using, be sure to see "Preparing the Apache v2 SSL Web
Note: To use reverse proxy functions with Access Manager, you need
to include the proxy module in the configure command, as discussed
in "About the Apache and IBM HTTP Reverse Proxy Server" on
page 31-3.
Note: To view the complete list of values, use the command:
./configure --help.
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-15
Server on AIX" on page 31-16 for additional information.
To prepare SSL-capable Apache v2 on UNIX
1. Confirm that your environment meets Apache requirements for the appropriate
compiler and build tools, as described in Apache documentation located at:
http://httpd.apache.org/docs-2.0/install.html
2. Download a complete, unmodified version of the Apache HTTP Server v2 and
Open Source, as described in the Apache documentation.
http://httpd.apache.org/download.cgi
http://www.openssl.org/
3. Extract (uncompress, then untar) source files from the tarballs, as described in the
Apache documentation. For example:
gzip -d httpd-2_0_48.tar.gz
tar -xvf httpd-2_0_48.tar
gzip -d openssl-0_9_6f.tar.gz
tar -xvf openssl-0_9_6f.tar
4. Configure the OpenSSL source tree, as described in Apache documentation. For
example:
cd openssl_source_dir
./config -fPIC --prefix=openssl_install_dir
where openssl_source_dir refers to the directory where you extracted OpenSSL and
openssl_install_dir refers to the directory where you want to install the configured
OpenSSL package.
5. Compile the OpenSSL package in the installation directory you configured using
the make command with the --prefix= option. For example:
make
6. Issue the make test command to complete any sanity testing of OpenSSL and
check the correct version of the tools required. For example:
make test
7. Install the OpenSSL package in the configured directory path that you specified
earlier using the --prefix= option. For example:
make install
8. Configure the Apache source tree and enable or activate desired modules, as
described in your Apache documentation. For example:
cd apache_source_dir ./configure --prefix=apache_install_dir
--enable-so \ --with-mpm='prefork' --with-perl=perl_interpreter_path \
--with-port=non_ssl_port --enable-ssl \ --with-ssl=openssl_install_dir
where apache_source_dir refers to the directory where you extracted Apache;
apache_install_dir refers to the directory where you want to install Apache; and
openssl_install_dir refers to the directory where you installed the configured
OpenSSL package.
9. Compile using the make command to build the Apache SSL-capable package in
the installation directory you configured using the --prefix= option. For example:
Preparing Your Web Server
31-16 Administrator's Guide for Oracle Access Management
make install
10. Install the Apache SSL-capable package in the configured directory path that you
specified earlier using the --prefix= option. For example:
make install
You must explicitly make certificates for the Apache v2 server to enable SSL using
the openssl tool located at openssl_install_dir/bin/. The make certificate command
does not work with Apache v2.
11. Make certificates using the OpenSSL tool in the openssl_install_dir/bin directory, as
described in your OpenSSL documentation and remember that "Common Name"
is the fully qualified host name.
12. Customize the installation using instructions in the Apache documentation:
■Tune the httpd.conf to set basic values for:
ServerName
User/owner of the WebServer
`Group
■Tune the ssl.conf to set basic values for:
Listen 7000
<VirtualHost _default_:7000>
ServerName ps0733.persistent.co.in:7000
SSLCertificateFile /home/qa/software/ws/apache/
apache-2.0.48_ssl_7000/conf/ssl.crt/server.crt
SSLCertificateKeyFile /home/qa/software/ws/apache/
apache-2.0.48_ssl_7000/conf/ssl.key/server.key
13. Stop then restart the Apache Web server to test the installation using commands in
the apache_install_dir/bin directory. For example:
./apachectl stop
./apachectl startssl
14. Continue with Activating Reverse Proxy for Apache v2 and IHS v2, if needed.
31.6.6 Preparing the Apache v2 SSL Web Server on AIX
While building the Apache v2 SSL Web server, the symbols from the OpenSSL Library
libssl.a are exported into the httpd executable in Apache. The symbols needed by
Access Manager from the OpenSSL library are:
■SSL_get_peer_certificate( )
■i2d_X509( )
During linking and binding on the AIX platform, any unused or unreferenced symbols
are deleted. Therefore, the two symbols required by Access Manager are missing from
the httpd executable.
You need to use openssl-0.9.7d to compile on AIX (openssl-0.9.7e does not compile on
AIX). The rest of the steps are the same as on UNIXopenssl-0.9.7d.
Client Cert Authentication: If you are using Client Cert Authentication on the AIX
platform, be sure to use AIX 5.2 Maintenance Level 4 with the following hot fix
applied for dlsym problem on AIX:
http://www-1.ibm.com/support/docview.wss?uid=isg1IY63366
Preparing Your Web Server
Configuring Apache, OHS, IHS for 10g WebGates 31-17
To prepare the AIX platform for Apache v2
1. Ensure that your AIX platform meets the system requirements for Access
Manager.
2. See details in "Preparing the Apache v2 Web Server on UNIX" on page 31-12 and
when building the Apache v2 Web server:
■Use openssl-0.9.7d to compile the Web server for AIX.
■Use the make command in the following manner:
make MFLAGS=EXTRA_LDFLAGS='-Wl,-bE:OpenSSL_Symbols.exp'
where OpenSSL_Symbols.exp is the file containing the two required symbols. The
symbol must be exported using the export file only, as shown.
31.6.7 Preparing the Apache v2 Web Server on Windows
Following are some details about how installing and configuring Apache v2 on
Windows differs from Apache v2 on UNIX. For more information, see your Apache
documentation.
During Installation: Apache will configure files in the \conf subdirectory to reflect the
chosen installation directory. If any configuration files in this directory already exist, a
new copy of the corresponding file will be written with the extension .ORIG. For
example, \conf\httpd.conf.ORIG.
After Installation: Apache is configured using the files in the \conf subdirectory.
These are the same files used to configure the UNIX version. However, there are a few
differences.
You must edit the configuration files in the \conf subdirectory to customize Apache
for your environment. These files will be configured during the installation; Apache is
ready to run from the installation directory, with the documents server from the
subdirectory htdocs. There are many options you should set before starting to use
Apache. For example, Apache listens on port 80 unless you change the Listen directive
in the configuration files or install Apache only for the current user.
Multi-Threading: Apache for Windows is multi-threaded, which means that it does
not use a separate process for each request as Apache does on UNIX. Instead there are
usually only two Apache processes running: a parent process, and a child which
handles the requests. Within the child process each request is handled by a separate
thread.
UNIX-Style Names: Apache uses UNIX-style names internally. The directives that
accept filenames as arguments must use Windows filenames instead of UNIX
filenames. However, you must use forward slashes, not back slashes. Drive letters may
be used. However, if a drive letter is omitted, the drive with the Apache executable is
assumed.
LoadModule Directive: Apache for Windows includes the ability to load modules at
runtime without recompiling the server. If Apache is compiled normally, it will install
a number of optional modules in the \Apache2\modules directory. To activate these
or other modules, you must use the LoadModule directive. For example, to activate
Note: Do not export the symbol on AIX with the following methods:
-bnog: To suppress garbage collection of symbols -bexpal: To export all
symbols -uSymbolName: To export a particular symbol.
Preparing Your Web Server
31-18 Administrator's Guide for Oracle Access Management
the status module, use the following (in addition to the status-activating directives in
access.conf):
LoadModule status_module modules/mod_status.so
On UNIX, the loaded code typically comes from shared object files (.so extension), on
Windows this may be either the .so or .dll extension.
Process Management Directives: These directives are also different for Apache on
Windows.
Error Logging: During Apache startup, any errors are logged into the Windows event
log, which provides a backup to the error.log file. For more information, see your
Apache documentation.
Apache Service Monitor: Apache comes with an Apache Service Monitor utility. With
it you can see and manage the state of all installed Apache services on any computer
on your network. To manage an Apache service with the monitor, you must first install
the service. Apache may be run as a service on Windows. For details, see your Apache
documentation.
Starting, Restarting, Shutting Down: Running Apache as a service is the
recommended method. An Apache service is typically started, restarted, and shut
down using the Apache Service Monitor and commands like NET START Apache2
and NET STOP Apache2. You may also use standard Windows service management.
You may work with Apache from the command line using the apache command.
Apache will execute and remain running until it is stopped by pressing Control-C. You
may also run Apache from the Start Menu during installation.
Apache Services Accounts: By default, all Apache services are registered to run as the
system user (the LocalSystem account). The LocalSystem account has no network
privileges through any Windows-secured mechanism. However, the LocalSystem
account has wide privileges locally. For details about creating a separate account to
run one or more Apache services, see your Apache documentation.
To prepare Apache v2 for Windows
1. Confirm that your environment meets Apache requirements, as described in
Apache documentation located at:
http://httpd.apache.org/docs-2.0/install.html
For Windows installations a list of HTTP and FTP mirrors from which you can
download Apache v2 is provided online.
When you complete the next step, be sure to download the version of Apache for
Windows with the .msi extension.
2. Download a complete, unmodified version of the Apache HTTP Server v2 (and
OpenSSL), as described in the Apache documentation. For example:
http://httpd.apache.org/download.cgi
http://www.openssl.org/
3. Install Apache v2 (run the .msi file you downloaded and supply requested
information), using your Apache documentation as a guide.
Note: Pressing Control-C may not allow Apache to end any current
operations and clean up gracefully.
Activating Reverse Proxy for Apache v2 and IHS v2
Configuring Apache, OHS, IHS for 10g WebGates 31-19
4. Locate the .default.conf file, verify new settings, then update your existing
configuration file if needed.
5. Start Apache, either in a console window or as a service.
6. Launch a browser and enter the following URL to connect to the server and access
the default page. For example:
http://localhost/
A welcome page and a link to the Apache manual should appear. If not, look in
the error.log file in the logs subdirectory.
Once your basic installation is working, you need to configure it properly by
editing the files in the \conf subdirectory.
7. Configure the Apache installation for your environment, using the Apache
documentation as a guide.
8. Test your customized environment.
9. Continue with Activating Reverse Proxy for Apache v2 and IHS v2, if needed.
31.7 Activating Reverse Proxy for Apache v2 and IHS v2
The Webgates for Apache v2 and IHS v2 powered by Apache support reverse proxy
capability, if you choose to activate this capability. The procedures to implement
reverse proxy capability differ, depending on your environment:
■To activate reverse proxy capability for Apache v2 Web servers
■To activate reverse proxy capability for IHS v2 Web servers
31.7.1 Activating Reverse Proxy For Apache v2 Web Servers
For reverse proxy functions with Access Manager, you need to include the Apache
proxy module in the configure command for the Web server. You also need to load
mod_proxy and the mod_proxy_http module into the server dynamically. A reverse
proxy is activated using the ProxyPass directive or the [P] flag to the RewriteRule
directive.
Reverse proxy capability is activated using the ProxyPass directive or the [P] flag to
the RewriteRule directive. It is not necessary to turn ProxyRequests on to configure a
reverse proxy. Access control is less critical when using a reverse proxy (ProxyPass
directive with ProxyRequests Off), because clients can contact only the hosts that you
have specifically configured. You can control access to your proxy using the <Proxy>
control block.
To activate reverse proxy capability for Apache v2 Web servers
1. Review "About the Apache and IBM HTTP Reverse Proxy Server" on page 31-3.
2. Include the Apache proxy module in the configure command for the Web server, if
needed.
For example:
--enable-proxy
--enable-proxy-connect
--enable-proxy-ftp
--enable-proxy-http
See the Apache documentation for more information.
Activating Reverse Proxy for Apache v2 and IHS v2
31-20 Administrator's Guide for Oracle Access Management
3. Use the ProxyPass directive or the [P] flag to the RewriteRule directive to activate
a reverse proxy, as follows:
Reverse Proxy
ProxyRequests Off
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /foo http://foo.example.com/bar
ProxyPassReverse /foo http://foo.example.com/bar
4. Control access to your proxy using the <Proxy> control block as follows:
<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
</Proxy>
5. Perform steps in Chapter 30, "Registering and Managing 10g WebGates with
Access Manager 11g", if you haven't yet done so.
31.7.2 Activating Reverse Proxy For IHS v2 Web Servers
Use the following procedure after installing the Web server.
To activate reverse proxy capability for IHS v2 Web servers
1. Review "About the Apache and IBM HTTP Reverse Proxy Server" on page 31-3
2. Install the IHS v2 Web server, as described in "Preparing the IHS v2 Web Server"
on page 31-8.
3. Load the modules by including these lines (uncommented) in the Dynamic Shared
Object section of the httpd.conf file in:
IHS_install_dir/conf/httpd.conf
LoadModule access_module modules/mod_access.so
LoadModule auth_module modules/mod_auth.so
LoadModule auth_dbm_module modules/mod_auth_dbm.so
LoadModule include_module modules/mod_include.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule unique_id_module modules/mod_unique_id.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule mime_module modules/mod_mime.so
LoadModule dav_module modules/mod_dav.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule asis_module modules/mod_asis.so
LoadModule info_module modules/mod_info.so
LoadModule cgid_module modules/mod_cgid.so
LoadModule dav_fs_module modules/mod_dav_fs.so
LoadModule vhost_alias_module modules/mod_vhost_alias.so
LoadModule dir_module modules/mod_dir.so
LoadModule imap_module modules/mod_imap.so
LoadModule actions_module modules/mod_actions.so
Activating Reverse Proxy for Apache v2 and IHS v2
Configuring Apache, OHS, IHS for 10g WebGates 31-21
LoadModule userdir_module modules/mod_userdir.so
LoadModule alias_module modules/mod_alias.so
LoadModule rewrite_module modules/mod_rewrite.so
4. Directives Under the IfModule mod_proxy.c Tag--Use the information and the
following examples to ensure that:
■Allow or Deny conditions are appropriately commented.
For example:
<Proxy *>
Order deny, allow
# Deny from all
Allow from all
# Allow from .domain.com
</Proxy>
■URLs to be protected are mentioned in both the ProxyPass and the
ProxyPassReverse directives.
For example:
<IfModule mod_proxy.c>
ProxyRequests Off
ProxyPass /testproxy http://bedford: 8809/testrev/
ProxyPassReverse /testproxy http://bedford: 8809/testrev/
ProxyPass /test2 http://bedford: 8809/testrev/
ProxyPassReverse /test2 http://bedford: 8809/testrev/
5. Restart the Web server after any modifications to the httpd.conf file.
6. Tes ti ng : To access the proxy URL, access
http://<proxy_host>:80/testproxy/
7. Enabling SSL on Reverse Proxy Server: Use the documentation on the IHS default
page.
For example, sample SSL settings in the DSO section of the httpd.conf file load the
ibm_ssl_module as:
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
8. Include the following directives in your httpd.conf file:
SSLEnable
Keyfile /opt/IBMIHS/bin/key.kdb
SSLClientAuth none
SSLProxyEngine on
9. Restart server.
10. Access the Web server URL and confirm that the browser is presented with a
certificate.
Note:
While testing, make sure the URLs have a trailing forward slash.
Sometimes resources cannot be accessed without the forward slash at
the end.
Verifying httpd.conf Updates for Webgates
31-22 Administrator's Guide for Oracle Access Management
11. key.kdb: To generate the key.kdb, use the ikeyman utility (preferably in GUI
mode) provided in the IHS_install_dir/bin directory.
12. Perform the following steps:
■Complete 10g Webgate installation with Access Manager 11g as described in
Chapter 30, "Registering and Managing 10g WebGates with Access Manager
11g", if you haven't yet done so
■Return to this chapter to perform remaining tasks in this chapter as needed.
31.8 Verifying httpd.conf Updates for Webgates
It is a good idea to complete the following procedures to ensure that the Apache or
IHS v2 httpd.conf file includes Web server configuration updates for Access Manager.
For details, see:
■Verifying Webgate Details
■Verifying Language Encoding
To update httpd.conf for reverse proxy on IHS Web servers, see "Activating Reverse
Proxy For IHS v2 Web Servers" on page 31-20. To customize httpd.conf for your Web
server, see your Web server documentation.
31.8.1 Verifying Webgate Details
The example that follows shows the Webgate section in the httpd.conf file. The details
will vary, depending on your environment. This example is provided only to illustrate
the type of changes you will see in httpd.conf.
To verify the Webgate section in httpd.conf
1. Locate the updated httpd.conf file on the computer hosting the Webgate.
2. Open the httpd.conf file and ensure that the section that loads the Webgate in your
platform is present.
For example:
On Windows
#*** BEGIN Oblix NetPoint Webgate Specific ****
<IfModule mod_ssl.c>
LoadModule obWebgateModule "WebGate_install_
dir\access\oblix\apps\webgate\bin\webgatessl.d ll"
WebGateInstalldir "WebGate_install_dir"
WebGateMode PEER
</IfModule>
<IfModule !mod_ssl.c>
LoadModule obWebgateModule "WebGate_install_
dir\access\oblix\apps\webgate\bin\webgate.dll"
Note: You can switch back to open mode for the Web server simply
by commenting out the preceding directives and restarting the server.
Note: The ikeyman utility uses the gsk7bas utility. However, you
need to apply fix pack PQ83048 on gsk7bas.
Verifying httpd.conf Updates for Webgates
Configuring Apache, OHS, IHS for 10g WebGates 31-23
WebGateInstalldir "WebGate_install_dir"
WebGateMode PEER
</IfModule>
<Location "\oberr.cgi">
SetHandler obwebgateerr
</Location>
<LocationMatch "/*">
AuthType Oblix
require valid-user
</LocationMatch>
#*** END Oblix NetPoint Webgate Specific ****
On UNIX
#*** BEGIN Oblix NetPoint Webgate Specific ****
LoadFile "/home/qa/netpoint/703/c1-copy/wg/access/oblix/lib/libgcc_s.so.1"
LoadFile "/home/qa/netpoint/703/c1-copy/wg/access/oblix/lib/libstdc++.so.5"
<IfModule mod_ssl.c>
LoadModule obWebgateModule "/home/qa/netpoint/703/c1-copy/wg/access/oblix/
apps/webgate/bin/webgatessl.so"
</IfModule>
<IfModule !mod_ssl.c>
LoadModule obWebgateModule "/home/qa/netpoint/703/c1-copy/wg/access/oblix/
apps/webgate/bin/webgate.so"
</IfModule>
WebGateInstalldir "/home/qa/netpoint/703/c1-copy/wg/access"
WebGateMode PEER
<Location /access/oblix/apps/webgate/bin/webgate.cgi>
SetHandler obwebgateerr
</Location>
<Location "/oberr.cgi">
SetHandler obwebgateerr
</Location>
<LocationMatch "/*">
AuthType Oblix
require valid-user
</LocationMatch>
#*** END Oblix NetPoint Webgate Specific ****
Notes for UNIX
When running Apache v2 on HP-UX, do not use nobody for User or Group, because
shared memory may not work. Instead, use your login name as User Name with a
group Group as "Oblix" (or "www" as User Name and "others" as Group Name). On
HP-UX, "www" is equivalent to "nobody" on Solaris.
When running Apache v2 on HPUX 11.11, ensure that the AcceptMutex directive in
the Apache httpd.conf file is set to "fcntl". If the directive is not present, add it to the
httpd.conf file (AcceptMutex fcntl). For more information, see
http://issues.apache.org/bugzilla/show_bug.cgi?id=22484).
Notes for IHS on AIX
#*** BEGIN Oblix NetPoint Webgate Specific ****
LoadModule obWebgateModule DR/oblix/apps/webgate/bin/webgate.so
WebGateInstalldir DR
WebGateMode PEER
<Location "/oberr.cgi">
SetHandler obwebgateerr
</Location>
Verifying httpd.conf Updates for Webgates
31-24 Administrator's Guide for Oracle Access Management
<LocationMatch "/*">
AuthType Oblix
require valid-user
</LocationMatch>
#*** END Oblix NetPoint Webgate Specific ****
1. Use the chmod -r username:groupname directory/file to change the User Name
and Group Name of a directory or a file.
When you do this, you need to change the User and Group parameters in the
httpd.conf file accordingly.
2. See "Tuning Apache/IHS v2 Webgates for Access Manager" on page 31-27 for
more information and complete any additional steps needed to finish the Access
Manager implementation for Apache v2.
To start httpd.conf updates anew
1. Restore the original httpd.conf file to remove any Access Manager entries that are
present.
2. Update the httpd.conf file for Access Manager using one of the following methods:
■Either open the file component_install_
dir/access/oblix/lang/LangTag/docs/config.htm and perform a manual
configuration, as described in Chapter 30, "Registering and Managing 10g
WebGates with Access Manager 11g".
■Or launch the ManageHttpConf program in component_install_
dir/access/oblix/tools/setup/InstallTools/ManageHttpConf without any
options to print instructions on its use.
3. Complete activities in "Tuning Apache/IHS v2 Webgates for Access Manager" on
page 31-27.
31.8.2 Verifying Language Encoding
As mentioned earlier, Access Manager HTML pages use UTF-8 encoding.
Apache-based Web servers allow Administrators to specify a default character set for
all HTML pages sent out using the
AddDefaultCharset
directive, which overrides any
character specified by the application generating the HTML pages. If the
AddDefaultCharset
directive enables a character set other than UTF-8, Access
Manager HTML pages are garbled.
To ensure proper language encoding
1. Open the httpd.conf file.
2. Locate the
AddDefaultCharset
directive.
Important: You use the following procedure only if you need to clear
the httpd.conf file of Webgate-related changes, then complete the
Apache v2 Web server configuration for the Webgate anew.
Note: If the ManageHttpConf program is run with Webgate entries
already present in the httpd.conf file, an error message will be printed
and the httpd.conf file will not be updated.
Tuning OHS /Apache Prefork and Worker MPM Modules for OAM
Configuring Apache, OHS, IHS for 10g WebGates 31-25
3. Complete one of the following activities to ensure that proper encoding of Access
Manager HTML pages:
■Either set the
AddDefaultCharset
directive to Off.
■Or Comment out the
AddDefaultCharset
directive.
4. Save the httpd.conf file and restart the Web server.
31.9 Tuning Oracle HTTP Server Webgates for Access Manager
After installing the Access Manager Web component for Oracle HTTP Server, you need
to complete the steps that follow.
As mentioned earlier, before installing Webgates for Oracle HTTP Server, in the
httpd.conf file you must change the user and group to match the user that is installing
the component.
To tune Oracle HTTP Server for Webgates
1. Shut down opmn, as you usually do.
2. Locate and open the opmn.xml file for editing. For example:
$ORACLE_HOME/opmn/bin/opmn.xml
3. In the opmn.xml file, adjust items as follows:
<ias-component id="HTTP_Server">
<process-type id="HTTP_Server" module-id="OHS2">
<environment>
<variable id="TMP" value="/tmp"/>
<variable id="LD_ASSUME_KERNEL" value="2.4.19"/>
</environment>
<module-data>
<category id="start-parameters">
<data id="start-mode" value="ssl-disabled"/>
</category>
</module-data>
<process-set id="HTTP_Server" numprocs="1"/>
</process-type>
</ias-component>
4. Refresh the OPMN configuration by executing the following script:
#ORACLE_HOME/opmn/bin/opmnctl reload
5. Start the Oracle HTTP Server Web server, as described in "Starting and Stopping
Oracle HTTP Server Web Servers"
31.10 Tuning OHS /Apache Prefork and Worker MPM Modules for OAM
Oracle recommends specific tuning parameters with Webgates for these Web servers.
The tuning parameters described in this section are configured in the httpd.conf file
with Apache v2.0 and OHS11g.
Note: On Linux, Webgates for Oracle HTTP Server 11g use only
NPTL; you cannot use the LinuxThreads library. In this case, do not
set the environment variable LD_ASSUME_KERNEL to 2.4.19.
Tuning OHS /Apache Prefork and Worker MPM Modules for OAM
31-26 Administrator's Guide for Oracle Access Management
For Apache v2.2, however, tuning is configured in the following files:
apache_install_dir/conf/extra/httpd-mpm.conf
apache_install_dir/conf/extra/httpd-default.conf
Also for Apache v2.2, the entries for httpd-mpm.conf and httpd-default.conf should be
uncommented, as follows:
From:
#Include conf/extra/httpd-mpm.conf
#Include conf/extra/httpd-default.conf
To:
Include conf/extra/httpd-mpm.conf
Include conf/extra/httpd-default.conf
Use the following topics as needed for your environment:
■Tuning Oracle HTTP Server /Apache Prefork MPM Module
■Tuning Oracle HTTP Server /Apache Worker MPM Module
■Tuning Kernel Parameters
31.10.1 Tuning Oracle HTTP Server /Apache Prefork MPM Module
Oracle recommends the following as broad guidelines when using Access Manager
with either the Oracle HTTP Server or Apache Prefork MPM module:
Timeout 300
KeepAlive On
MaxKeepAliveRequests 500
KeepAliveTimeout 10
StartServers: 5 (Initial number of processes to start; used only on startup.)
MaxClients: 500 (Total number of processes to handle load at peak time. Determines
how many child processes will be created to handle requests at peak period.
ServerLimit: 500 (The maximum configured value for MaxClients for the lifetime of
the process. If MaxClients is set to a value higher than the default, ServerLimit value
should be specified above the rest of the parameters.
MinSpareServers, MaxSpareServers: Default values should suffice requirements to
handle a heavy load. During operation, these values regulate how the parent process
creates children to serve requests.
MaxRequestsPerChild: 0 - Number of requests sent to each child process. 0 indicates
the process never expires/dies
31.10.2 Tuning Oracle HTTP Server /Apache Worker MPM Module
Oracle recommends the following as broad guidelines when using Access Manager
with either the Oracle HTTP Server or the Apache Worker MPM module:
Timeout 300
KeepAlive On
MaxKeepAliveRequests 500
Tuning Apache/IHS v2 Webgates for Access Manager
Configuring Apache, OHS, IHS for 10g WebGates 31-27
KeepAliveTimeout 10
StartServers: 2 (Initial number of processes to start; used only on startup.)
MaxClients: 500 (Total number of processes to handle load at peak time. Determines
how many child processes will be created to handle requests at peak period.
ServerLimit: 25 (The maximum configured value for MaxClients for the lifetime of the
process. If MaxClients is set to a value higher than the default, ServerLimit value
should be specified above the rest of the parameters.
MinSpareServers, MaxSpareServers: 25, 75. During operation, these values regulate
how the parent process creates children to serve requests.
ThreadsPerChild: 25 (The number of worker threads in single httpd process.)
MaxRequestsPerChild: 0 (This directive sets the limit on the number of requests that
an individual child server process will handle. The value 0 will ensure that the process
never expires.)
31.10.3 Tuning Kernel Parameters
Oracle recommends that you ensure the kernel parameters for the soft and hard limit
on the file descriptors are set to a high value. For example:
Hard limit (rlim_fd_max): 65535
Soft limit (rlim_fd_cur): 65535
The high value of the file descriptor is a strong recommendation for the Apache server
that will open and close sockets for requests.
31.11 Starting and Stopping Oracle HTTP Server Web Servers
Starting and stopping an Oracle HTTP Server Web server is the same procedure for
both v1.3 and v2, on all platforms.
To start the Oracle HTTP Server Web server
1. Locate and change to the following directory:
$ORACLE_HOME\opmn\bin\
2. From the command line, enter the following command:
opmnctl/startproc process-type=HTTP_Server
To stop the Oracle HTTP Server Web server
1. Locate and change to the following directory:
$ORACLE_HOME\opmn\bin\
2. From the command line, enter the following command:
opmnctl/stopproc process-type=HTTP_Server
31.12 Tuning Apache/IHS v2 Webgates for Access Manager
Unless explicitly stated, information here applies to both Apache and IHS v2 Webgate
(also known as plug-ins). For details about Oracle HTTP Server, see the Oracle HTTP
Server Administrator's Guide 10 g R2 (10.1.2).
Tuning Apache/IHS v2 Webgates for Access Manager
31-28 Administrator's Guide for Oracle Access Management
Apache v2 bundled with Security-Enhanced Linux: With SELinux, errors could be
reported in WebServer logs/console when starting a Web server on Linux distributions
that have more strict SELinux policies in place after installing an Access Manager
Webgate. You can avoid these errors by running appropriate
chcon
commands for the
installed Web component before restarting the Web server.
Apache v2 bundled SELinux-enabled Linux Distribution: Security-enhanced Linux
(SELinux) is an automatically enabled implementation of a mandatory access-control
mechanism. As described in your Linux documentation, SELinux policies provide
access to certain pre-defined system directories such as /etc/httpd/conf,
/usr/sbin/apachect, and /var/log/ (to name a few) for system daemons.
When Webgates are installed with the bundled Apache Web server, certain policies
must be added to allow Apache processes to access installation files.
The bundled Apache Web server runs as user "apache" with a security context defined
as
context=user_u:system_r:unconfined_t
. As a result, when Webgates are installed
in any of the user folders, the Apache Web server will not start.
The $SELINUX_SRC variable represents the SELinux policy source directory. The
default value is /etc/selinux/targeted/src/policy. However, your environment may
vary. Be sure to consult your system Administrator for the actual value for your
system.
To add Access Manager policies to Apache bundled with Red Hat Enterprise
Linux 4
1. After installing each Access Manager Webgate, log in as the 'root' user.
2. Ensure that all Webgates are installed for Web server user & group (default:
apache).
3. Create an oracle_access_manager.te policy file in the $SELINUX_
SRC/domains/programs/directory and add the following rules:
type oracle_access_manager_t, file_type, sysadmfile;
allow httpd_t oracle_access_manager_t:file { rw_file_perms create rename
link unlink setattr execute };
allow httpd_t oracle_access_manager_t:dir { rw_dir_perms create append
rename link unlink setattr };
4. Create an oracle_access_manager.fc file context in the directory $SELINUX_
SRC/file_contexts/program, then register the Webgate installation directory
(without identity or access suffix). For example:
Oracle_Access_Manager_install_dir(/.*)? system_u:object_r:oracle_access_
manager_t
5. Compile and deploy the policy files as follows:
cd $SELINUX_SRC
make load
Label Oracle Access Manager files
See Also: "SELinux Issues" on page E-25
Note: When the Webgate is installed in a separate directory from the
Access Manager, be sure to register the Webgate installation directory
separately.
Tuning Apache/IHS v2 Webgates for Access Manager
Configuring Apache, OHS, IHS for 10g WebGates 31-29
run restorecon -R Oracle_Access_Manager_install_dir (without the identity or
access suffix)
Apache v2 Directives: Apache 1.3 uses a process model for serving multiple HTTP
requests at once. This differs from the single process (thread) model employed by
other Web servers, which manage several requests simultaneously in one process.
Several directives in the Apache v2 Web server configuration file (httpd.conf) affect
how the Apache Web server decides to create or destroy worker processes. The
following parameters affect the performance of the Apache v2 Web server:
■ThreadsPerChild: This directive sets the number of threads created by each child
process. The child creates these threads at startup and never creates more.
■If you are using an MPM like mpm_winnt, where there is only one child
process, this number should be high enough to handle the entire load of the
server.
■If you are using an MPM like mpm_worker, where there are multiple child
processes, the total number of threads should be high enough to handle the
common load on the server.
■MinSpareThreads: This value is only used with mpm_worker. Since Access
Manager plug-in initialization is deferred until the first request, there is minimal
advantage of keeping high value for this directive. However, it is useful to keep
this parameter as high as possible.
■MaxSpareThreads: This value is only used with mpm_worker. The value for
MaxSpareThreads must be greater than or equal to the sum of MinSpareThreads
and ThreadsPerChild or the Apache HTTP Server automatically corrects it.
Recommendation: Keep the value high. For a dedicated server this will not be a
problem.
■MaxSpareServers: With Apache v2, this is used only with the prefork MPM
model. To preserve as much state as possible in the server, set the
MaxSpareServers to a high value. Setting this value to the maximum of 255 keeps
all Apache worker-processes available indefinitely, but it does not provide an
opportunity for worker-process recycling during low-load periods.
■MinSpareServers: With Apache v2, this is used only with the prefork MPM
model. Since Access Manager plug-in initialization is deferred until the first
request, using a high value for the MinSpareServers parameter provides minimal
advantage. However, it is useful to keep this parameter as high as possible. For
dedicated Web server systems, this should pose no great burden.
■MaxClients: With IHS v2 and the worker MPM, MaxClients restricts the total
number of threads that will be available to serve clients. For hybrid MPMs, the
default value is 16 (ServerLimit) multiplied by a value of 25 (ThreadsPerChild). To
increase MaxClients to a value that requires more than 16 processes, you must also
raise ServerLimit.
Appropriate values for the preceding parameters depend on the expected load and the
performance class of the systems involved, including the Access Server and LDAP
server.
Note: Only the prefork MPM in Apache v2 uses the same process
model for serving HTTP requests as Apache v1.3. For all other MPMs,
Apache v2 uses a hybrid process-thread model.
Removing Web Server Configuration Changes After Uninstall
31-30 Administrator's Guide for Oracle Access Management
Apache servers on very high performance systems with high expected loads may be
recompiled with a larger limit on the number of worker processes. These systems may
see a greater performance impact on the StartServers and MinSpareServers parameters
for dealing with sudden load spikes.
You may need to adjust operating system limits for the Access Server for proper
operation. In particular, the maximum number of file descriptors available for any one
Access Server may need to be increased beyond the default value. Configuring more
than one connection between each Apache-based Webgate and an Access Server may
quickly exceed this limit.
For additional information, see your Apache documentation.
31.13 Removing Web Server Configuration Changes After Uninstall
Web server configuration changes that occur during installation must be manually
removed after uninstalling the Webgate). This type of information must be removed
manually.
Further, you must remove any changes that you manually made to your Web server
configuration file for the Webgate) should be removed. For more information about
what is added for each component, look elsewhere in this chapter.
31.14 Helpful Information
Consult the following manual for more information about the Oracle HTTP Server:
Oracle HTTP Server Administrator's Guide 10 g R2 (10.1.2)
The following URLs provide information about building an Apache release and source
code:
Apache v2 documentation:
http://httpd.apache.org/docs-2.0/
Apache v2 source code:
http://httpd.apache.org/download.cgi
Mod-SSL documentation:
http://httpd.apache.org/docs-2.0/mod/mod_ssl.html
OpenSSL documentation:
http://www.openssl.org/docs/
OpenSSL source code:
http://www.openssl.org/source/
Compiling and Installing Apache v2:
http://httpd.apache.org/docs-2.0/install.html#test
IHS:
http://www-306.ibm.com/software/webservers/httpservers/doc/v2047/manual/re
adme.html
32
Configuring the ISA Server for 10g WebGates 32-1
32
Configuring the ISA Server for 10g WebGates
This chapter describes how to configure the Access Manager ISAPI Webgate and
Microsoft Internet Security and Acceleration Server (ISA Server) to operate together.
Topics include:
■Prerequisites
■About Access Manager and the ISA Server
■Compatibility and Platform Support
■Installing and Configuring Webgate for the ISA Server
■Configuring the ISA Server for the ISAPI Webgate
■Starting, Stopping, and Restarting the ISA Server
■Removing Access Manager Filters Before Webgate Uninstall on ISA Server
32.1 Prerequisites
Ensure that your Oracle Access Management Console is running and get familiar with:
■"Introduction to Policy Enforcement Agents" on page 14-1
■"About Access Manager and the ISA Server" on page 32-1
32.2 About Access Manager and the ISA Server
The ISA Server is Microsoft's "integrated edge security gateway". It is designed to
protect IT environments from Internet-based threats and to give users secure remote
access to applications and data.
Webgate is the Access Manager Web server plug-in access client that intercepts HTTP
requests for Web resources and forwards them to the Access Server for authentication
and authorization. ISAPI is the Internet Web server extension that Access Manager
uses to identify Webgates that communicate with the ISA Server (and the IIS Web
Server).
This Webgate has been tested to operate with the ISA Server in scenarios that use both
Access Manager Basic and Form (form-based) authentication schemes. You develop
Basic and Form authentication schemes and policy domains using Access Manager as
usual.
Note: Access Manager Client Certificate authentication is not
supported for the ISA Server.
Compatibility and Platform Support
32-2 Administrator's Guide for Oracle Access Management
Using ISA Server with Access Manager is similar to using the IIS Web server.
However, the ISA Server provides firewall and Virtual Private Network (VPN)
functions.
ISA Server can be configured for third-party security filters. To enforce Access
Manager security during authentication and authorization when you use ISA Server,
both webgate.dll and postgate.dll must be registered as ISA Server Web filters. Every
request to the Access Server that passes through ISA Server requires webgate.dll and
postgate.dll.
The following overview outlines the tasks that you must perform and the topics
where you will find the steps to set up the ISAPI Webgate with the ISA Server.
Task overview: Installing and configuring the ISAPI Webgate on ISA Server
1. Confirming "Compatibility and Platform Support" on page 32-2
2. "Installing and Configuring Webgate for the ISA Server" on page 32-2.
3. "Configuring the ISA Server for the ISAPI Webgate" on page 32-3.
4. Perform the following tasks, as described in:
a. "Ordering the ISAPI Filters" on page 32-6
b. "Removing Access Manager Filters Before Webgate Uninstall on ISA Server"
on page 32-7
32.3 Compatibility and Platform Support
Get the latest certification matrix from Oracle Technology Network at the following
URL:
http://www.oracle.com/technology/products/id_mgmt/coreid_acc/pdf/oracle_access_
manager_certification_10.1.4_r3_matrix.xls
32.4 Installing and Configuring Webgate for the ISA Server
After ISA Server installation, you perform the following tasks to install Webgate for
use with ISA Server.
Task overview: Performing Webgate configuration for ISA Server includes
1. "Installing Webgate with ISA Server" on page 32-2
2. "Changing /access Directory Permissions" on page 32-3
3. "Registering Access Manager Plug-ins as ISA Server Web Filters" on page 32-3
32.4.1 Installing Webgate with ISA Server
When you install Webgate with the ISA Server, the destination for the ISAPI Webgate
installation (also known as the Webgate_install_dir) should be same as that of the
See Also: Oracle Fusion Middleware Administrator's Guide for
Oracle Access Management for more information about authentication
management and policy domains.
See Also: "Compatibility and Platform Support" on page 32-2
Configuring the ISA Server for the ISAPI Webgate
Configuring the ISA Server for 10g WebGates 32-3
Microsoft ISA Server. For example, if ISA Server is installed on C:\Program
Files\Microsoft ISA Server, the ISAPI Webgate should also be installed there.
Task overview: Installing the ISAPI Webgate for the ISA Server
1. See Chapter 30 for details on the following topic, as these apply to your
environment:
■Registering a 10g WebGate with Access Manager 11g Remotely
■Locating and Installing the Latest 10g WebGate for Access Manager 11g
■Configuring Centralized Logout for 10g WebGate with 11g OAM Servers
2. Changing /access Directory Permissions on page 32-3
32.4.2 Changing /access Directory Permissions
After finishing ISAPI Webgate installation and configuration for the ISA Server, you
need to change permissions to the \access subdirectory. This subdirectory was created
in the ISA Server (also Webgate) installation directory. You need to add the user
NETWORK SERVICE and grant full control to NETWORK ADMINISTRATOR.
This enables the ISA Server to establish a connection between the Webgate and Access
Server. Certain configuration files should be readable by network Administrators,
which is why you grant NETWORK ADMINISTRATOR full control.
To change permissions for the \access subdirectory
1. In the file system, right-click Webgate_install_dir\access, and select Properties.
2. In the Properties window, click the Security tab.
3. Add user "NETWORK SERVICE" and then select "Allow" to give "Full Control".
4. For the "NETWORK ADMINISTRATOR", select "Full Control".
32.5 Configuring the ISA Server for the ISAPI Webgate
The following topics describe how to configure the ISA Server to operate with the
Access Manager ISAPI Webgate.
Task overview: Performing Webgate configuration for ISA Server includes
1. "Registering Access Manager Plug-ins as ISA Server Web Filters" on page 32-3
2. "Configuring ISA Firewall Policies for ISA Web Filters" on page 32-4
32.5.1 Registering Access Manager Plug-ins as ISA Server Web Filters
After resetting ISAPI Webgate permissions, you need to register Access Manager
webgate.dll and postgate.dll plug-ins as Web Filters within ISA Server. Web filters
screen all HTTP traffic that passes through the ISA Server host. Only compliant
requests are allowed to pass through.
Access Manager authentication schemes define how the user is challenged for
credentials, maps user-supplied information, verifies it, and so forth. With the ISA
Note: During Webgate installation, do not automatically update the
ISA Server configuration. Instead, choose "No" when asked about
automatic updates to the ISA Server configuration.
Configuring the ISA Server for the ISAPI Webgate
32-4 Administrator's Guide for Oracle Access Management
Server, you must choose either Form or Basic authentication as the challenge method.
You must also specify a Challenge Parameter to map the credentials provided by the
user to the corresponding user profile stored in the directory server.
The following procedure describes how to register Access Manager plug-ins in the ISA
Server.
To register Access Manager plug-ins as ISA Server Web filters
1. Locate the ISA Server installation directory, from which you will perform the
following tasks.
2. Run
net stop fwsrv
to stop the ISA Server.
3. Register the webgate.dll as an ISAPI Web filter by running
regsvr32 ISA_
install_dir\access\oblix\apps\webgate\bin\webgate.dll
.
4. Register the postgate.dll as an ISAPI Web filter by running
regsvr32 ISA_
install_dir\access\oblix\apps\webgate\bin\postgate.dll
.
5. Restart the ISA Server by running
net start fwsrv
to restart the ISA Server.
6. Proceed to "Configuring ISA Firewall Policies for ISA Web Filters".
32.5.2 Configuring ISA Firewall Policies for ISA Web Filters
To authenticate users, ISA Server must be able to communicate with the authentication
servers. After registering Access Manager webgate.dll and postgate.dll as ISA Web
filters, you must configure the ISA Firewall Policy rule to protect resources using these
Web filters.
Web publishing rules essentially map incoming requests to the appropriate Web
servers. Access rules determine how clients on a source network access resources on a
destination network. ISA Firewall Policy rules require client membership in a user set:
either Firewall clients, authenticated Web clients, or virtual private network (VPN)
clients. The ISA Server attempts to match authenticated users based upon ISA Firewall
Policy rules.
Note: If Access Manager libraries are not registered as ISA Web
filters, Access Manager authentication could fail. Do not point to
webgate.dll in the action path for form-based login in the
authentication scheme. Instead, specify the path to a dummy file in
the /access directory as shown here:
action= "/access/dummy
"
For form based authentication, postgate.dll must be installed and
should be at a higher level than webgate.dll.
Note: If you need to undo the filter registration, you can use the
following procedure with the
/u
option in the
regsvr32
command. For
example:
regsvr32 /u ISA_install_
dir\access\oblix\apps\webgate\bin\webgate.dll
See Also: Your ISA Server documentation for details about ISA
Firewall Policies and rules
Configuring the ISA Server for the ISAPI Webgate
Configuring the ISA Server for 10g WebGates 32-5
The following procedure describes how to configure an ISA Firewall Policy rule to use
with ISA Web filters for Access Manager webgate.dll and postgate.dll.
To configure ISA policies to enable Access Manager authentication and
authorization
1. From the Start menu, click All Programs, click Microsoft ISA Server, and then
click ISA Server Management.
2. From the tree of the ISA Server Management console, locate the name of this
server, and then click Firewall Policy.
3. From the Tasks tab, click Publish Web Sites.
4. In the Web publishing rule name field, type a descriptive name for the rule, and
then click Next.
5. On the Select Rule Action page, confirm that the Allow option is selected, and then
click Next.
6. In the Publishing type, confirm that the Publish a single Web site or load
balancer option is selected, and then click Next.
7. On the Server Connection Security page, click Use non-secured connections to
connect the published Web server or server farm, and then click Next.
8. Perform the following steps to set internal publishing details:
a. In the Internal site name box, type the internally-accessible name of the Web
server.
b. Check the Use a computer name or IP address to connect to the published
server check box.
c. Type the internally-accessible and fully qualified domain name, or type the IP
address of the Web server computer, in the Computer name or IP address box
d. Click Next.
9. In the Public name box, type the publicly-accessible domain name of the Web
server computer, and then click Next.
10. To publish a particular folder in the Web site:
a. Type the folder name in the Path (optional) box to display the full path of the
published Web site in the Web site box.
b. Click Next.
11. In the Accept requests for list:
a. Click This domain name (type below).
b. In the Public name box, type the publicly-accessible fully qualified domain
name of the Web site.
Note: After you perform the following procedure, when you create a
listener in the authentication click Allow client authentication over
HTTP in Advanced Properties.
Note: If you are using secured connections, see the server connection
security settings provided by ISA Server.
Configuring the ISA Server for the ISAPI Webgate
32-6 Administrator's Guide for Oracle Access Management
c. Click Next.
12. In the Web listener list, either click the Web listener to use for this Web publishing
rule; otherwise or create a new Web listener, as follows:
a. Click New, type a descriptive name for the new Web listener, and then click
Next.
b. Click Do not require SSL secured connections with clients, and then click
Next.
c. In the Listen for requests from these networks list, click the required
networks and click to check the External box, then click Next.
d. In the Select how clients will provide credentials to ISA Server list, click No
Authentication, and then click Next.
e. On the Single Sign On Settings page, click Next, and then click Finish.
13. Authentication Delegation: Perform the following steps in the Select the method
used by ISA Server to authenticate to the published Web server list:
a. Click No Delegation.
b. Click Client Cannot Authenticate Directly.
c. Click Next.
This is used by ISA Server to authenticate to the published Web server.
14. On the User Sets page:
a. Choose All (the default user setting) to set the rule that applies to requests
from the user sets box.
b. Click Next and then click Finish.
15. Click Apply to update the firewall policy, and then click OK.
16. Validate that only applicable ports are open and that the traffic that you would like
to pass through is allowed.
32.5.3 Ordering the ISAPI Filters
It is important to ensure that the Webgate ISAPI filters are included in the right order.
postgate.dll should be loaded before webgate.dll.
To order the Webgate ISAPI filters for ISA Server
1. From the Start menu, click All Programs, click Microsoft ISA Server, and then click
ISA Server Management.
2. Expand Configuration, then check Add-ins to display your Web-filters.
3. Right-click the Web-filters and select Properties.
4. Confirm the following .dll files appear.
For example:
postgate.dll
webgate.dll
5. Add any missing filters, if needed, then select a filter name and use the up and
down arrows to arrange the filter order as shown in step 5.
Removing Access Manager Filters Before Webgate Uninstall on ISA Server
Configuring the ISA Server for 10g WebGates 32-7
32.6 Starting, Stopping, and Restarting the ISA Server
When instructed to restart your ISA Server during Access Manager Web component
installation or setup, be sure to follow any instructions that appear on the screen. Also,
consider using
net stop fwsrv
and
net start fwsrv
are good ways to stop and
start the ISA Server. The
net
commands help to ensure that the Metabase does not
become corrupted following an installation.
For more information, see your ISA Server documentation.
32.7 Removing Access Manager Filters Before Webgate Uninstall on ISA
Server
If you plan to uninstall the Webgate that is configured to operate with the ISA Server,
you must first unregister the Access Manager filters manually, and then uninstall
Webgate.
To unregister filters before Webgate uninstall
1. Stop the ISA Server.
2. Run the following command to unregister webgate.dll. For example:
regsvr32 /u ISA_install_dir\access\oblix\apps\webgate\bin\webgate.dll
3. Run the following command to unregister postgate.dll. For example:
regsvr32 /u ISA_install_dir\access\oblix\apps\webgate\bin\postgate.dll
WARNING: Confirm that there is only one webgate.dll and one
postgate.dll filter and ensure that these are in an enabled state. Also,
ensure that postgate.dll is installed at higher priority level than
webgate.dll.
See Also: Chapter 30 for details about uninstalling 10g Webgates
Removing Access Manager Filters Before Webgate Uninstall on ISA Server
32-8 Administrator's Guide for Oracle Access Management
33
Configuring the IIS Web Server for 10g WebGates 33-1
33
Configuring the IIS Web Server for 10g
WebGates
This chapter summarizes activities that you need to perform to configure 10.1.4
WebGate with a Microsoft Internet Information Server (IIS Web server for Windows
environments). Unless explicitly stated, information and steps in this chapter apply
equally to 32-bit and 64-bit WebGate installations. Topics include:
■Prerequisites
■WebGate Guidelines for IIS Web Servers
■Prerequisite for Installing Webgate for IIS 7
■Updating IIS 7 Web Server Configuration on Windows 2008
■Completing Webgate Installation with IIS
■Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
■Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
■Finishing 64-bit Webgate Installation
■Confirming Webgate Installation on IIS
■Starting, Stopping, and Restarting the IIS Web Server
■Removing Web Server Configuration Changes Before Uninstall
33.1 Prerequisites
Ensure that your Oracle Access Management Console is running and get familiar with:
■Introduction to Policy Enforcement Agents on page 14-1
■About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2 on
page 30-3
33.2 WebGate Guidelines for IIS Web Servers
ISAPI is an Internet Web server extension that the WebGate that communicates with
the IIS Web server. For example, you will need the following package to install the
WebGates for IIS:
Oracle_Access_Manager10_1_4_3_0_Win32_ISAPI_Webgate
64-bit Webgate: Oracle_Access_Manager10_1_4_3_0_Win64_ISAPI_Webgate.exe
WebGate Guidelines for IIS Web Servers
33-2 Administrator's Guide for Oracle Access Management
Updating the IIS Web server configuration file is required when installing Webgates.
With IIS Web servers, a configuration update involves updating the Web server
directly by adding the ISAPI filter and creating extensions required by Access
Manager. A filter listens to all requests to the site on which it is installed. Filters can
examine and modify both incoming and outgoing streams of data to enhance IIS
functionality. ISAPI extensions are implemented as DLLs that are loaded into a process
that is controlled by IIS. Like ASP and HTML pages, IIS uses the virtual location of the
DLL file in the file system to map the ISAPI extension into the URL namespace that is
served by IIS.
Oracle recommends that you update the IIS Web server configuration file
automatically during Webgate installation. Automatic updates may take more than a
minute. However, updating the IIS Web server configuration file manually takes
longer and could introduce unintended errors.
For more specific guidelines, see:
■Guidelines for ISAPI WebGates
■Prerequisite for Installing Any 10g Webgate for IIS 7
■Prerequisite for Installing a 32-bit Webgate for IIS 7
33.2.1 Guidelines for ISAPI WebGates
General WebGate preparation and installation details apply to ISAPI WebGates.
Additionally, this topic provides specific guidelines for ISAPI WebGates installed with
an IIS Web server. You can install multiple WebGates with a single IIS Web server
instance or you might have a 64-bit WebGate.
lockdown Mode: Before installing the WebGate, ensure that your IIS Web server is not
in lockdown mode. Otherwise things will appear to be working until the server is
rebooted and the metabase re-initialized, at which time IIS will disregard activity that
occurred after the lockdown.
Permissions: Setting various permissions for the /access directory is required for IIS
Webgates only when you are installing on a file system that supports NTFS. For
example, suppose you install the ISAPI Webgate in Simple or Cert mode on a
Windows 2000 computer running the FAT32 file system. The last installation panel
provides instructions for manually setting various permissions that cannot be set on
the FAT32 file system. In this case, these instructions may be ignored.
Virtual Hosts: Each IIS Virtual Web server can have it's own Webgate.dll file installed
at the virtual level, or can have one Webgate affecting all sites installed at the site level.
Either install the Webgate.dll at the site level to control all virtual hosts or install the
Webgate.dll for one or all virtual hosts.
postgate.dll: You may also need to install the postgate.dll file at the computer level.
The postgate.dll is located in the \Webgate_install_dir, as described in "Installing the
Postgate ISAPI Filter". If you perform multiple installations, multiple versions of this
file may be created which may cause unusual Access Manager behavior. In this case,
you should verify that only one webgate.dll and one postgate.dll exist.
Note: Unless explicitly stated, details apply equally to 32-bit and
64-bit Webgates.
WebGate Guidelines for IIS Web Servers
Configuring the IIS Web Server for 10g WebGates 33-3
Updating Web Server Configuration for Webgate: As with other Webgates, your Web
server must be configured to operate with the Webgate. Oracle recommends
automatically updating your Web server configuration during installation. However,
you can decline the automatic update and instead manually configure your Web
server as described in "Registering a 10g WebGate with Access Manager 11g Remotely"
on page 30-11.
FAT32 file system: You may receive special instructions to perform during Webgate
installation. For example: Setting various permissions for the /access directory is
required for IIS Webgates only when you are installing on a file system that supports
NTFS. The last installation panel provides instructions for manually setting various
permissions that cannot be set on the FAT32 file system. In this case, these instructions
can be ignored.
SSL and Client Certificate Authentication: On IIS, if you are using client certificate
authentication you must enable SSL on the IIS Web server hosting the Webgate before
enabling client certificates for Webgate. You must also ensure that various filters are
installed in a particular order. In addition, you may need to install the postgate.dll as
an ISAPI filter.
Web Server Releases: Web server details in this chapter apply to the stated release. If
the release is not stated, you can presume it is IIS v5. Details specific to IIS v6 or IIS v7
are identified.
32-bit versus 64-bit Webgates: Unless explicitly stated, all information applies equally
to both 32-bit and 64-bit Webgates.
General Webgate Preparation and Installation Details: Refer to this chapter for
IIS-specific guidelines. Refer to Chapter 30 for general preparation and installation
details.
Completing and Confirming Webgate Installation: Perform tasks relevant to your
ISAPI Webgate and IIS version:
Note: The postgate.dll is always installed at the site level. If for some
reason the Webgate is reinstalled, the postgate.dll is also reinstalled. In
this case, ensure that only one copy of the postgate.dll exists at the site
level.
See Also:
■Webgates for IIS v7 on page 33-4
■Webgates for IIS v6 on page 33-4
See Also:
■Webgates for IIS v6 on page 33-4
■Finishing 64-bit Webgate Installation on page 33-24
See Also:
■Completing Webgate Installation with IIS
■Finishing 64-bit Webgate Installation
■Confirming Webgate Installation on IIS
WebGate Guidelines for IIS Web Servers
33-4 Administrator's Guide for Oracle Access Management
33.2.1.1 Webgates for IIS v7
General guidelines and Webgate installation are usually the same regardless of the IIS
release for which you are installing a Webgate. However, there are several specific
topics to review when you are installing one or more Webgates for IIS v7:
■Prerequisite for Installing Webgate for IIS 7 on page 33-5
■Updating IIS 7 Web Server Configuration on Windows 2008 on page 33-6
■Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance on
page 33-14
33.2.1.2 Webgates for IIS v6
General guidelines and Webgate installation are usually the same regardless of the IIS
release for which you are installing a Webgate. However, there are several specific
topics of interest.
Multiple Webgates with a Single IIS 6 Instance: IIS v6.0 supports hosting multiple
Web sites on a single Web server instance and ISAPI Webgate allows you to protect
each Web site with a different Webgate.
64-bit IIS v6 Webgate: Perform installation as you do for all others, using instructions
available in Chapter 30. If you choose manual Web server configuration during
Webgate installation, you can access details in the following path:
Webgate_install_dir\access\oblix\lang\en-us\docs\dotnet_isapi.htm
Following Webgate installation and IIS configuration, perform tasks in "Finishing
64-bit Webgate Installation" on page 33-24.
Earlier Release Webgate Installations: Previously Oracle recommended that Webgate
be installed in the same physical directory location as Policy Manager. This required a
virtual directory named "access" for both Policy Manager and Webgate, which is
mapped to the physical location of both Policy Manager and Webgate.
If you have an earlier, combined Webgate and Policy Manager installation, you can
de-couple the components using the following steps.
To de-couple an earlier Webgate/Policy Manager installation
1. Uninstall any patches applied to the earlier Webgate and Policy Manager, if any.
2. Uninstall the earlier Policy Manager and Webgate combination.
3. Install Policy Manager 10g (10.1.4.3).
4. In a separate directory location, install Webgate 10g (10.1.4.3)
33.2.1.3 Multiple Webgates with a Single IIS 6 Instance
Unless explicitly stated, details in this topic apply equally to 32-bit and 64-bit
Webgates.
IIS v6.0 supports hosting multiple Web sites on a single Web server and ISAPI Webgate
allows you to protect each Web site with a different Webgate.
See Also: Multiple Webgates with a Single IIS 6 Instance
Note: You can install Webgate 10g (10.1.4.3) for IIS in any location,
separate from that of Policy Manager.
Prerequisite for Installing Webgate for IIS 7
Configuring the IIS Web Server for 10g WebGates 33-5
IIS 6 provides application pools that are used to run virtual servers. You can think of
an application pool as a group of one or more URLs that are served by a worker
process or a set of worker processes. An application pool is a configuration that links
one or more applications to a set of one or more worker processes. Because
applications in this pool are separated from other applications by worker process
boundaries, an application in one application pool is not affected by problems caused
by applications in other application pools. Today, Webgate instances can run in
different process spaces.
When you have multiple Web sites on a single IIS v6.0 Web server instance, you need
to ensure that user requests reach the correct Web site. To do this, you need to
configure a unique identity for each site on the server using at least one of three
unique identifiers:
■Host header name
■IP address
■TCP port number
You can install multiple Webgates on different Web sites of the same IIS Web server
instance. However, several manual steps are required.
33.3 Prerequisite for Installing Webgate for IIS 7
This section provides prerequisites for installing Webgates with IIS v7 Web servers. It
includes the following topics:
■Prerequisite for Installing Any 10g Webgate for IIS 7
■Prerequisite for Installing a 32-bit Webgate for IIS 7
33.3.1 Prerequisite for Installing Any 10g Webgate for IIS 7
The following procedure applies to 32-bit and 64-bit Webgates equally.
With Webgate for IIS v7 Web Server, you can use Form-based authentication without
enabling pass through functionality only when the
<add segment="bin"/>
entry is not
present in the applicationHost.config file. For example, if you have
access/oblix/apps/webgate/bin/webgate.dll as an action in the Form-based
authentication scheme, ensure that the
<add segment="bin"/>
entry is not present in
Note: Previous ISAPI Webgate releases did not support multiple
Webgates with a single IIS Web server instance. You either had to
install one Webgate for all Web sites at the top level, or protect a single
Web site by configuring Webgate at the Web site level.
Note: If you have multiple Web sites on a single server and these are
distinguished by IP address and port, multiple Webgates are not
required. Starting with release 10.1.4.2.0 virtual hosts on Apache and
IIS 6.0 are supported. As a result, a single Webgate on the top level can
protect all the Web sites even if the IP addresses are different. This is
handled by using different Host Identifiers for each Web site.
See Also: "Installing and Configuring Multiple Webgates for a
Single IIS 6 Instance" on page 33-19
Updating IIS 7 Web Server Configuration on Windows 2008
33-6 Administrator's Guide for Oracle Access Management
the applicationHost.config file. If the entry is present, you must remove it, as described
next
To locate and remove the
<add segment="bin"/>
entry
1. Go to Windows\System32\inetsrv\config and open the applicationHost.config
file.
2. Search for the <
hiddenSegments
> module.
3. Remove the entry
<add segment="bin"/>
if it is present.
4. Save the file.
33.3.2 Prerequisite for Installing a 32-bit Webgate for IIS 7
The following procedure applies to 32-bit Webgates only.
The following procedure provides steps to configure a 32-bit Webgate for IIS 7 Web
Server to use either Simple or Cert transport security mode. This configuration
requires that the IIS 6 Management Compatibility module be installed.
To add the IIS 6 Management Compatibility module for a 32-bit Webgate for IIS 7
and Simple or Cert security
1. From the State menu, click Administrative Tools, and then click Server Manager.
2. In the Server Manager tree, expand Roles, and then click Web Server (IIS).
3. In the Web Server (IIS) pane, Role Services section, click Add Role Services.
4. On the Select Role Services page of the Add Role Services Wizard, click IIS6
Management Compatibility under Management Tools.
5. On the Confirm Installation Selections page, click Install.
6. On the Results page, click Close.
33.4 Updating IIS 7 Web Server Configuration on Windows 2008
You can display these steps when you decline automatic Web server updates during
Webgate installation.
To display steps to configure IIS 7 Web server on Windows 2008 for ISAPI
Webgates
1. When installing Webgate, click No when asked if you want the automatic Web
server update and:
a. Read information on a new screen to assist in manually setting up your Web
server for the Webgate.
b. Click the following item in the table that appears perform the steps that are
displayed.
Table 33–1 IIS 7 Webgate Windows Server 2008
Supported Server OS Microsoft IIS
Windows Server 2008 ISAPI
... ...
Completing Webgate Installation with IIS
Configuring the IIS Web Server for 10g WebGates 33-7
2. After performing steps to update the IIS 7 Web server on Windows 2008, return to
the Webgate installation screen and click Next, as described in the chapter on
Webgate installation.
3. Proceed with "Completing Webgate Installation with IIS".
33.5 Completing Webgate Installation with IIS
Unless explicitly stated, details in this topic apply equally to 32-bit and 64-bit
Webgates.
Completing Webgate installation with an IIS Web server, includes the following
activities after the installation is complete.
Task overview: Completing IIS Webgate installations includes
1. Enabling Client Certificate Authentication on the IIS Web Server on page 33-7
2. Ordering the ISAPI Filters on page 33-8
3. Enabling Pass-Through Functionality for POST Data on page 33-9
4. Protecting a Web Site When the Default Site is Not Setup on page 33-13
33.5.1 Enabling Client Certificate Authentication on the IIS Web Server
Unless explicitly stated, details in this topic apply equally to 32-bit and 64-bit
Webgates.
If you are using client certificate authentication, you must enable SSL on the IIS Web
server. If you select client certificate authentication during setup, you must also add
the cert_authn.dll as one of the ISAPI filters.
To enable SSL on the IIS Web server
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Information Services.
2. Expand the local computer to display your Web Sites.
3. Expand the Default Web Site (or the appropriate Web site), then expand
\access\oblix\apps\webgate\bin.
See Also:
As needed, see:
■Finishing 64-bit Webgate Installation on page 33-24
■Installing and Configuring Multiple Webgates for a Single IIS 6
Instance on page 33-19
If you have IIS v7, Oracle recommends the following topics:
■Updating IIS 7 Web Server Configuration on Windows 2008 on
page 33-6
■Installing and Configuring Multiple 10g WebGates for a Single IIS
7 Instance on page 33-14
Note: The procedures here reflect the sequence for IIS v5. Your
environment might be different.
Completing Webgate Installation with IIS
33-8 Administrator's Guide for Oracle Access Management
4. Right click cert_authn.dll and select Properties.
5. In the Properties panel, select the File Security tab.
6. In the Secure Communications sub-panel, click Edit.
7. In the Client Certificate Authentication sub-panel, click Accept Certificates and
click OK.
8. Click OK in the cert_authn.dll Properties panel.
9. Proceed to the next procedure: "To add cert_authn.dll as an ISAPI filter".
To add cert_authn.dll as an ISAPI filter
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Information Services.
2. Expand the local computer to display your Web Sites.
3. Right click the appropriate Web Site to display the Properties panel.
4. Click the ISAPI Filters tab, then click the Add button to display the Filter
Properties panel.
5. Enter filter name "cert_authn".
6. Click the Browse button and navigate to the following directory:
\Webgate_install_dir\access\oblix\apps\webgate\bin
7. Select cert_authn.dll as the executable.
8. Click OK on the Filter Properties panel.
9. Click Apply on the ISAPI Filters panel.
10. Click OK.
11. Ensure the filters are listed in the correct order.
33.5.2 Ordering the ISAPI Filters
Unless explicitly stated, details in this topic apply equally to 32-bit and 64-bit
Webgates.
It is important to ensure that the Webgate ISAPI filters are included in the right order.
To order the Webgate ISAPI filters
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Information Services.
2. Expand the local computer to display your Web Sites.
3. Right-click the Web Site and select Properties.
4. Click Properties, select ISAPI filters.
5. Confirm the following .dll files appear.
For example:
Note: This task is the same whether you are installing one or more
Webgates per IIS Web server instance.
Completing Webgate Installation with IIS
Configuring the IIS Web Server for 10g WebGates 33-9
cert_authn.dll
webgate.dll
6. Add any missing filters, if needed, then select a filter name and use the up and
down arrows to arrange the filter order as shown in step 5.
33.5.3 Enabling Pass-Through Functionality for POST Data
This section describes how the Webgate can be set up in conjunction with IIS 6.0
Worker Process Isolation Mode. It also covers configuration steps required for IIS 6.0
running in IIS 5.0 Isolation Mode.
Topics here include:
■About ISAPI Webgate 10.1.4.2.3
■About Pass-Through Functionality for POST Data
■Implementing Pass-Through: IIS 6.0 in Worker Process Isolation Mode
■Implementing Pass-Through with IIS 6.0 Web Server in IIS 5.0 Isolation Mode
33.5.3.1 About ISAPI Webgate 10.1.4.2.3
Starting with ISAPI Webgate release 10.1.4.2.3, Access Manager pass-through
functionality is supported with IIS 6.0 running in a Worker Process Isolation Mode.
ISAPI Webgate 10.1.4.2.3 also operates with IIS 6.0 running in IIS 5.0 Isolation Mode
using postgate.dll.
This section describes how to set up ISAPI Webgate release 10.1.4.2.3 in conjunction
with IIS 6.0 Worker Process Isolation Mode. It also provides configuration steps
required for IIS 6.0 running in IIS 5.0 Isolation Mode. This section supersedes
information in Section 19-6 (Installing Postgate.dll on IIS Web Servers) of the Oracle
Access Manager Installation Guide.
33.5.3.2 About Pass-Through Functionality for POST Data
POST data is required for pass through during a form login on the IIS Web server
when using the Webgate extension method (where the Webgate is the action of the
form). In other words, if a form authentication scheme on the IIS Web server is
WARNING: Confirm that there is only one webgate.dll and one
postgate.dll filter. If you perform multiple Webgate installations on
one computer, multiple versions of the postgate.dll file might be
created and cause unusual Access Manager behavior.
Note: This section supersedes information in "Installing Postgate.dll
on IIS Web Servers" in the 10g Oracle Access Manager Installation
Guide. For the IIS 5.0 Web server, the existing functionality using
postgate.dll continues to be supported.
Note: Oracle recommends using Worker Process Isolation Mode for
new or existing implementations. Worker Process Isolation Mode is a
default setting for the IIS 6.0 Web server. For the IIS 5.0 Web server, the
existing functionality (using postgate.dll) continues to be supported.
Completing Webgate Installation with IIS
33-10 Administrator's Guide for Oracle Access Management
configured with the pass-through option, and the target of the login form requires the
data posted by the form, the Webgate extension method (where the Webgate DLL is
the action of the form) cannot be used. The Webgate filter method (where the action of
the form is a protected URL that is not the Webgate DLL) must be used instead, and
based on IIS version, the postgate.dll must be installed or configure webgate.dll as
ISAPI extension.
IIS 6.0 in Worker Process Isolation Mode: webgate.dll must be configured as an ISAPI
filter and also as an ISAPI extension to achieve pass-through functionality. (This does
not apply to ISA server integration.) Pass-through functionality is supported with
10.1.4.2.3 and higher ISAPI Webgates. However, you must also set a new user-defined
parameter
"UseWebGateExtForPassthrough"
to
true
in the Webgate configuration
profile in the Access System Console.
IIS 5.0 or IIS6.0 running in IIS 5.0 Isolation Mode: postgate.dll must be configured as
an ISAPI filter to achieve the pass-through functionality.
33.5.3.3 Implementing Pass-Through: IIS 6.0 in Worker Process Isolation Mode
The following steps outline this task.
Task overview: Implementing Pass-Through Functionality with IIS 6.0 Web
Server in Worker Process Isolation Mode
1. Install Webgate as described in "Locating and Installing the Latest 10g WebGate
for Access Manager 11g" on page 30-14.
2. Set the pass-through parameter as described in "Setting the
UseWebGateExtForPassthrough Parameter in the Webgate Profile".
3. Configure webgate.dll as described in "Configuring webgate.dll as an ISAPI
Extension".
33.5.3.3.1 Setting the UseWebGateExtForPassthrough Parameter in the Webgate Profile You
must set the new user-defined parameter,
UseWebGateExtForPassthrough
, in the
Webgate profile to implement pass-through functionality with the IIS 6.0 Web server in
Worker Process Isolation Mode. You must set
UseWebGateExtForPassthrough
to
true
.
If this parameter is set to
false
, pass-through functionality will not work.
To set the UseWebGateExtForPassthrough Parameter in the WebGate Profile
1. Launch the Access System Console and click Application Security.
2. Click Agents.
3. Enter your search criteria for the WebGate, and then click Search.
4. In the Search Results table, click a WebGate name.
5. Locate the User Defined Parameters section of the Access/WebGate Gate page,
enter the following parameter, and click Apply.
Parameter:
UseWebGateExtForPassthrough
Val u e:
true
6. Click the Apply button if you want to add more user-defined parameters.
7. Repeat for each WebGate in your deployment.
8. Proceed to "Configuring webgate.dll as an ISAPI Extension".
See Also: "IIS Web Server Issues" on page E-18
Completing Webgate Installation with IIS
Configuring the IIS Web Server for 10g WebGates 33-11
33.5.3.3.2 Configuring webgate.dll as an ISAPI Extension
The webgate.dll is part of the Webgate installation. The following procedure describes
how to configure webgate.dll as an ISAPI extension. This task must also be performed
to implement pass-through functionality with IIS 6.0 Web Server in Worker Process
Isolation Mode.
To configure webgate.dll as an ISAPI extension
1. Go to websites, right click, and select Properties.
2. In the Properties dialog box, select the Home Directory tab.
3. Click the Configurations button to open the Application Configurations dialog
box.
4. In Wild Card Application Maps, click the Inset button.
5. Provide the path to webgate.dll. For example:
Webgate_install_dir/access/oblix/apps/webgate/bin/webgate.dll
6. Uncheck the "verify that file exists" box.
7. Confirm and finalize the changes: click OK, then click OK again; click Apply, and
then click OK.
8. Stop the IIS Administration Server from Services and restart the IIS Web server.
33.5.3.4 Implementing Pass-Through with IIS 6.0 Web Server in IIS 5.0 Isolation
Mode
The following steps outline this task.
Task overview: Implementing Pass-Through Functionality with IIS 6.0 Web
Server in IIS 5.0 Isolation Mode
1. Install Webgate as described in the Chapter 30, "Registering and Managing 10g
WebGates with Access Manager 11g".
2. Set up IIS 6.0 as described in "Setting Up IIS 6.0 Web Server in IIS 5.0 Isolation
Mode" on page 33-11.
3. Install postgate.dll as described in "Installing the Postgate ISAPI Filter""Installing
the Postgate ISAPI Filter".
33.5.3.4.1 Setting Up IIS 6.0 Web Server in IIS 5.0 Isolation Mode The following information
is updated for the 10.1.4.2.3 Webgate.
When IIS 6.0 Web server is used, the following steps outline how to set up the WWW
Service to run in IIS 5.0 Isolation Mode. This is required by the ISAPI postgate filter.
Note: You can have multiple webgate.dlls configured at different
website levels from the top level Web Sites. In this case, you also need
to configure webgate.dll as an ISAPI extension for each website
protected by Webgate.
Note: Skip this task if you are using IIS 6.0 Web server in Worker
Process Isolation Mode.
Completing Webgate Installation with IIS
33-12 Administrator's Guide for Oracle Access Management
To set IIS 5.0 isolation on IIS 6 Web servers
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Information Services.
2. Expand the local computer to display your Web Sites.
3. Right-click the Web Site and select Properties.
4. Select the Service tab in the Web Site Properties window.
5. Check the box beside Run WWW service in IIS 5.0 Isolation Mode.
6. Click OK.
7. Proceed with "Installing the Postgate ISAPI Filter".
33.5.3.4.2 Installing the Postgate ISAPI Filter
The following information is updated for the 10.1.4.2.3 Webgate.
For single Webgate installations, you should install the filters in the following order:
■The ISAPI Webgate filter should be installed after the sspifilt filter and before any
others.
■The postgate filter should be installed before the Webgate filter, only if needed.
■All other Access Manager filters can be installed at the end.
You can have multiple webgate.dlls configured at different levels from the top level
Web Sites. However, they share the same postgate.dll. If you perform multiple
Webgate installations on one computer, multiple versions of the postgate.dll file can be
created which might cause unusual Access Manager behavior. There can only be one
postgate.dll configured at the (top) Web Sites level of a computer
The following procedures guide as you install and position the postgate ISAPI filter
when you have a single Webgate installed with a single IIS Web server instance.
To install the postgate ISAPI filter
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Information Services.
2. Expand the local computer to display your Web Sites.
3. Right-click the Web Site and select Properties.
4. Select the ISAPI Filters tab in the Web Site Properties window.
5. Click the Add button to display the Filter Properties panel.
6. Enter the filter name "postgate".
7. Click the Browse button and navigate to the following directory:
Note: Before installation (or after uninstallation) the filters must be
removed manually. If multiple copies of a filter are installed, this
means that they were not manually removed before installing the new
filters.
Note: postgate.dll is not supported when you have more than one
Webgate installed and configured for a single IIS Web server instance.
Completing Webgate Installation with IIS
Configuring the IIS Web Server for 10g WebGates 33-13
\Webgate_install_dir\access\oblix\apps\webgate\bin
8. Select postgate.dll as the executable.
9. Click OK on the Filter Properties panel.
10. Click Apply on the ISAPI Filters panel.
11. Reposition the postgate ISAPI filter, as follows:
a. Start the Internet Information Services console, if needed.
b. Right-click your local computer, then select All Tasks, select Restart IIS.
c. Select the ISAPI Filters tab on the Properties panel.
d. Select the postgate filter and move it before Webgate, using the up arrow.
For example:
postgate.dll
webgate.dll
e. Restart IIS.
33.5.4 Protecting a Web Site When the Default Site is Not Setup
Unless explicitly stated, this topic applies equally to 32-bit and 64-bit Webgates.
When you install a Webgate on an IIS Web server that does not have the "Default Web
Site" configured, the installer does not create "Virtual Directory access", which must be
done manually using the following procedure.
To protect a Web site (not the default site)
1. Start the Internet Information Services console, if needed
2. Select the name of the Web site to protect.
3. Right-click the name of the Web site to protect and select New, and then select
Virtual Directory in the menu.
4. Click Next.
5. Select Alias: access, then click Next.
6. Directory: Enter the full path to the /access directory, then click Next.
Webgate_install_dir\access
7. Select Read, Run Scripts, and Execute, then click Next.
8. Click Finish.
9. Restart IIS. For example:
Select Start, then Run.
Type
net start w3svc.
Click OK.
Note: Consider using
net stop iisadmin
and
net start w3svc
to
help ensure that the Metabase does not become corrupted.
See Also: "Setting Access Permissions, ISAPI filters, and Directory
Security Authentication" on page 33-25
Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
33-14 Administrator's Guide for Oracle Access Management
33.6 Installing and Configuring Multiple 10g WebGates for a Single IIS 7
Instance
This section describes how to install and configure multiple Webgates for different
Web sites on the same IIS 7 Web server instance. Several steps are manual and will
differ from those that are performed when you install a single Webgate with a single
IIS instance. When installing multiple Webgates for a single IIS instance:
■The webgate.dll must be configured as an ISAPI filter at the individual Web site
level, not the default (top) Web server level
■The /access virtual directory is mapped at the Web site level to the respective
/access directory in the Webgate installation.
When configuring the impersonation DLL for multiple Webgates, you need to
configure a user to act as the operating system.
Task overview: Installing and configuring multiple Webgates for a single IIS 7
instance
1. Installing Each IIS 7 Webgate in a Multiple Webgate Scenario
2. Setting the Impersonation DLL for Multiple IIS 7 Webgates
3. Enabling Client Certification for Multiple IIS 7 Webgates
4. Configuring IIS 7 Webgates for Pass Through Functionality
5. Confirming IIS 7 Webgate Installation
6. Perform the following tasks, which are the same whether you install one or more
Webgates per IIS Web server instance:
■"Ordering the ISAPI Filters" on page 33-8
■"Confirming Webgate Installation on IIS" on page 33-26
33.6.1 Installing Each IIS 7 Webgate in a Multiple Webgate Scenario
After installing the ISAPI Webgate, there are several manual steps to perform as
described here.
By default, webgate.dll is configured as an ISAPI filter at the host name (top) level.
When installing multiple Webgates with a single IIS 7 instance, you need to remove
the respective webgate.dll from the top level and configure it for the appropriate
individual Web site after each Webgate installation.
To install each Webgate when you will have several with one IIS 7 instance
1. Install the ISAPI 7 Webgate as described in Chapter 30.
2. Go to the Web site to protect, and configure webgate.dll as the ISAPI filter using
these steps:
a. Start the Internet Information Services (IIS) Manager: Click Start, Programs,
Administrative Tools, Internet Information Services (IIS) Manager.
b. Select the hostname from the Connections pane.
c. From the hostname Home pane, double-click ISAPI Filters, look for any
Webgate.dll; if it is present, select it and click Remove from the Action pane.
See Also: "Confirming Multiple Webgate Installation" on page 33-24
Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
Configuring the IIS Web Server for 10g WebGates 33-15
d. In the Connection pane, under Sites, click the name of the Web Site for which
you want to configure a Webgate filter.
e. In the Home pane, double-click ISAPI Filters.
f. In the Actions pane, click Add…
g. In the Filter name text box of the Add ISAPI Filter dialog box, type "Webgate"
as name for the ISAPI filter.
h. In the Executable box, type the file system path of the Webgate ISAPI filter file
or click the ellipsis button (...) to go to the folder that contains the Webgate.dll
ISAPI filter file, and then click OK.
Webgate_install_dir\access\oblix\apps\webgate\bin\webgate.dll
3. Creating a Virtual Directory:
a. Expand the Sites pane and select the Web Site for which you just configured
the ISAPI filter (Webgate.dll).
b. On the Action pane, click View Virtual Directories and then select Add Virtual
Directory.
c. Specify access in the Alias text box and the physical path to the Webgate
access folder of Webgate or click the ellipsis button (...) to go to the "access"
folder, and then click OK.
Webgate_install_dir\access\
d. Save and apply these changes.
4. Setting permissions to the Virtual Directory:
a. Select the "access" virtual directory created in Step 3.
b. From the access Home pane, double click Handler Mappings; from the Action
pane, select Edit Feature Permissions….
c. Check boxes beside Read, Script, and Execute, then click OK.
5. Setting Directory Permissions for Webgate:
a. In Explorer, right click the Webgate installation directory
Webgate_install_
dir\access
and select Properties.
b. Click the Security tab and click the Edit button.
c. Add user "IUSR", select "Allow" for "Modify".
d. Add user "IIS_IUSRS", select "Allow" for "Modify".
e. Add user "NETWORK", select "Allow" for "Modify".
f. Add user "NETWORK SERVICE", select "Allow" for "Modify".
g. For group "Administrators" select "Allow" for "Modify".
6. Webgate in Simple or Cert Mode:
a. In the file system, locate and right-click the "password.xml" file in Webgate_
install_dir\access\oblix\config\password.xml, and select Properties.
b. Click the Security tab.
c. Give "Allow" for "Read" rights to users "IUSR", "NETWORK SERVICE", "IIS_
WPG", "IIS_IUSRS".
7. Ensure that there is no webgate.dll in the top level (the hostname level).
Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
33-16 Administrator's Guide for Oracle Access Management
8. Perform the next set of tasks using instructions in the following topics:
a. "Setting the Impersonation DLL for Multiple IIS 7 Webgates" on page 33-16
b. "Enabling Client Certification for Multiple IIS 7 Webgates" on page 33-17
9. Repeat these steps when you install the next Webgate for the IIS instance.
33.6.2 Setting the Impersonation DLL for Multiple IIS 7 Webgates
The client's access token is known as an impersonation token. The impersonation
token identifies the client, the client's groups, and the client's privileges. The
information in the token is used during access checks when the thread requests access
to resources on the client's behalf.
Access Manager authenticates and authorizes the user. The Access Manager
IISImpersonationExtension.dll in the wildcard extension behaves like a filter for each
request to the Web server. Access Manager designates a special user that does have the
right to impersonate another user by configuring it using the impersonation
username/password on the AccessGate Configuration page. That designated user
must have "act as operating system" rights. DLL impersonates the user authenticated
and authorized by Access Manager and generates the impersonation token.
You perform the following steps to set the impersonation DLL for each Webgate that
protects a Web site for a single IIS 7 Web server instance. You can do this either
immediately after the installation task in the previous topic or all at one time.
To add the impersonation DLL to IIS 7 configuration for individual Web sites
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Add "IISImpersonationExtension.dll" as a Wildcard Script Map to the required
Web Site:
a. Expand Sites in the connection pane.
b. Click the Web Site name to which you want to add
IISImpersonationExtension.dll.
c. Double click Handler Mappings from the selected Web Site's "home" pane.
d. From the Action pane, click Add Wildcard Script Map.
e. In the Name text box of the Add Wildcard Script Map dialog box, type "Oracle
Impersonation Plugin" as name for the dll.
f. In the Executable box, type the file system path of the Webgate
IISImpersonationExtension.dll or click the ellipsis button (...) to go to the
folder that contains IISImpersonationExtension.dll, and then click OK.
Webgate_install_dir/access/oblix/apps/Webgate/bin/
IISImpersonationExtension.dll
This example shows the default path, where Webgate_install_dir is the file
system directory where you have installed this particular Webgate.
3. Proceed as follows:
Note: This task must be performed for each Webgate that protects an
individual Web site for a single IIS Web server instance.
Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
Configuring the IIS Web Server for 10g WebGates 33-17
■Client Certificate Authentication: "Enabling Client Certification for Multiple
IIS 7 Webgates"
■"Confirming IIS 7 Webgate Installation" on page 33-19.
33.6.3 Enabling Client Certification for Multiple IIS 7 Webgates
You perform this task to set the enable client certification for each Webgate that
protects a Web site for a single IIS 7 Web server instance. You can do this either
immediately after the adding the impersonation DLL to an individual Web site or all at
one time.
If you select client certificate authentication during setup, you must also enable and
then add the cert_authn.dll as one of the ISAPI filters in the respective Web site.
To enable cert_authn.dll on the IIS 7 Web server
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Expand Sites in the connection pane.
3. Expand the Web Site to \access\oblix\apps\webgate\bin.
4. Right click the "bin" directory and select Switch To Content View.
5. Right click the "cert_authn.dll".and from the drop down menu, select Switch To
Feature View.
6. From the cert_authn.dll Home pane, double click SSL Settings.
7. From SSL Settings pane, select Require SSL check-box and select Accept from
Client Certificates.
8. Select Apply from Action pane.
9. Repeat for each Webgate installed on this host, for which you want to enable client
certification.
10. Restart the IIS 7 Web server.
11. Proceed to the next task: "To add cert_authn.dll as an ISAPI v7 filter".
To add cert_authn.dll as an ISAPI v7 filter
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Expand Sites in the connection pane.
3. Click on the Web Site name for which you want to add "cert_authn.dll".
4. In the Home pane, double-click ISAPI Filters.
5. In the Actions pane, click Add.
6. In the Filter name box of the Add ISAPI Filter dialog box, type Oracle Certification
Authentication Plugin as name for the ISAPI filter.
Note: SSL should be enabled on the Web Site before configuring the
client certification for Webgate. Follow these steps after the Web Site is
SSL enabled.
Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance
33-18 Administrator's Guide for Oracle Access Management
7. In the Executable box, type the file system path of the Webgate cert_authn.dll or
click the ellipsis button (...) to go to the folder that contains cert_authn.dll, and
then click OK.
Webgate_install_dir/access/oblix/apps/Webgate/bin/cert_authn.dll
This example shows the default path, where Webgate_install_dir is the file system
directory where you have installed this particular Webgate.
8. Click View Ordered List from the Action pane and arrange the filters as shown
here by using "Move Up" or "Move Down":
cert_authn.dll
webgate.dll
9. Select Apply from Action pane.
10. Repeat for each Webgate installed on this host, for which you want to enable client
certification.
11. Restart the IIS 7 Web server.
12. Proceed as needed for your deployment:
■"Configuring IIS 7 Webgates for Pass Through Functionality"
33.6.4 Configuring IIS 7 Webgates for Pass Through Functionality
Here you will add Webgate.dll as a Wildcard Script Map to the required Web Site.
While configuring Webgate to work with pass through functionality, you must ensure
that "Physical Path" of the Web sites on which you are installing Webgates differ.
Otherwise, the changes in "Handler Mappings" are reflected in all the Web Sites
sharing the same physical path.
To configure Webgate for pass through functionality
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Expand Sites in the connection pane.
3. Click the Web Site name for which you want to enable pass through.
4. Double click Handler Mappings from the selected Web Site's "home" pane.
5. From the Action pane, click Add Wildcard Script Map.
6. In the Name text box of the Add Wildcard Script Map dialog box, type Webgate as
name for the ISAPI filter.
7. In the Executable box, type the file system path of the Webgate ISAPI filter file
(Webgate.dll) or click the ellipsis button (...) to go to the folder that contains the
Webgate.dll ISAPI filter file, and then click OK.
Webgate_install_dir/access/oblix/apps/Webgate/bin/Webgate.dll
Note: "Physical Path" is the path that is provided at the time of
creating the Web Site. To check this path after the creation of the Web
Site, , In Action pane click on Basic Settings..., you will be presented
with a window showing the physical path of the Web Site.
■Click the Web Site name.
■In the Action pane, click Basic Settings.
Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
Configuring the IIS Web Server for 10g WebGates 33-19
8. In the Access System Console:
a. Locate the Web Gate profile and click Modify.
b. Under User Defined Parameters, enter the following parameter and value:
UseWebGateExtForPassthrough
true
c. Save the profile.
9. Repeat for each Webgate installed on this host, for which you want to enable pass
through.
10. Restart the IIS 7 Web server.
11. Proceed to the next task: "Confirming IIS 7 Webgate Installation".
33.6.5 Confirming IIS 7 Webgate Installation
You can use the following procedure to confirm IIS 7 Webgate installation.
To verify IIS 7 Webgate installation
1. Go to the URL:
http(s)://hostname:port/access/oblix/apps/webgate/bin/webgate.dll?progid=1
where hostname refers to the name of the computer hosting the Webgate; port refers
to the Web server instance port number.
2. The Webgate diagnostic page should appear.
■Successful: If the Webgate diagnostic page appears, the Webgate is
functioning properly and you can dismiss the page.
■Unsuccessful: If the Webgate diagnostic page does not open, the Webgate is
not functioning properly. In this case, the Webgate should be uninstalled and
reinstalled. For more information about removing Access Manager see the
OAM Installation Guide Chapter 22, then return to the chapter on installing a
Webgate.
33.7 Installing and Configuring Multiple Webgates for a Single IIS 6
Instance
Unless explicitly stated, this topic applies equally to 32-bit and 64-bit Webgates.
This section describes how to install and configure multiple Webgates for different
Web sites on same IIS Web server instance. Several steps are manual and will differ
from those that are performed when you install a single Webgate with a single IIS
instance. When installing multiple Webgates for a single IIS instance:
■The webgate.dll must be configured as an ISAPI filter at the individual Web site
level, not the default (top) Web server level
■The /access virtual directory is mapped at the Web site level to the respective
/access directory in the Webgate installation.
See Also: "Installing and Configuring Multiple 10g WebGates for a
Single IIS 7 Instance" on page 33-14
Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
33-20 Administrator's Guide for Oracle Access Management
When configuring the impersonation DLL for multiple Webgates, you need to
configure a user to act as the operating system.
There can only be one postgate.dll configured at the (top) Web Sites level of a machine.
However, you might have multiple webgate.dlls configured at different levels below
the top level Web Sites. If you perform multiple Webgate installations on one machine,
multiple versions of the postgate.dll file might be created that can cause unusual
Access Manager behavior.
Task overview: Installing and configuring multiple Webgates for a single IIS
instance
1. Installing Each Webgate in a Multiple Webgate Scenario
2. Setting the Impersonation DLL for Multiple Webgates
3. Enabling SSL and Client Certification for Multiple Webgates
4. Perform the following tasks, which are the same whether you install one or more
Webgates per IIS Web server instance:
■"Ordering the ISAPI Filters" on page 33-8
■"Confirming Webgate Installation on IIS" on page 33-26
33.7.1 Installing Each Webgate in a Multiple Webgate Scenario
Unless explicitly stated, this topic applies equally to 32-bit and 64-bit Webgates.
After installing the ISAPI Webgate, there are several manual steps to perform as
described here.
By default, webgate.dll is configured as an ISAPI filter at the Web sites (top) level.
When installing multiple Webgates with a single IIS instance, you need to remove the
respective webgate.dll from the top level and configure it for the appropriate
individual Web site after each Webgate installation.
To install each Webgate when you will have several with one IIS instance
1. Install the ISAPI Webgate as described in Chapter 30.
2. Go to the Web site to protect, and configure webgate.dll as the ISAPI filter using
these steps:
a. Start the Internet Information Services (IIS) Manager: Click Start, Programs,
Administrative Tools, Internet Information Services (IIS) Manager
b. Right click Web Sites, and then click the Properties option.
c. Click the ISAPI filter tab, look for the path to webgate.dll; if it is present in the
filter, then select it and click the Remove button.
d. Under Web Sites, right-click the name of the Web site to protect, and select the
Properties option.
See Also: "Confirming Multiple Webgate Installation" on page 33-24
Note: If you perform multiple Webgate installations on one machine,
multiple versions of the postgate.dll file might be created which can
cause unusual Access Manager behavior. The postgate.dll is not
supported in environments where you have multiple Webgates
configured with a single IIS v6 web server instance.
Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
Configuring the IIS Web Server for 10g WebGates 33-21
e. Click the ISAPI filter tab to add the filter DLLs.
f. Add the following filter to identify the path to the webgate.dll file, and name
it "webgate".
Webgate_install_dir/access/oblix/apps/webgate/bin/webgate.dll
g. Save and apply these changes.
h. Go to the Directory Security tab.
i. Confirm that "anonymous access" and "basic authentication" are selected so
that Access Manager provides authentication for this Web server.
j. Save and apply these changes.
3. Go to Web sites level to protect and create an /access virtual directory that points
to the newly installed Webgate_install_dir:
a. Under Web Sites, right-click the name of the Web site to be protected.
b. Select New and create a new virtual directory named
access
that points to the
appropriate Webgate_install_dir/access.
c. Under Access Permissions, check Read, Run Scripts, and Execute.
d. Save and apply these changes.
4. In the file system, set directory permissions for Access Manager:
a. In the file system, locate and right-click Webgate_install_dir\access, and the
select Properties.
b. Click the Security tab.
c. Add user "IUSR_machine_name" and then select "Allow" for "Modify".
For example, for a machine_name of Oracle, select IUSR_ORACLE.
d. Add user "IWAM_machine_name" and then select "Allow" for "Modify"
For example, for a machine_name Oracle, select IWAM_ORACLE.
e. Add user "IIS_WPG" and then select "Allow" for "Modify".
f. Add user "NETWORK SERVICE" and then select "Allow" for "Modify".
g. For the group "Administrators", select "Allow" for "Modify".
5. If Webgate has been set up in Simple or Cert mode, perform the follow steps:
a. In the file system, locate and right-click the "password.xml" file in Webgate_
install_dir\access\oblix\config\password.xml.
b. Click the Security tab.
c. Give "Allow" for "Read" rights to users "IUSR_machine_name", IWAM_
machine_name, "IIS_WPG", and "NETWORK SERVICE".
6. Add a new Web service extension using the following steps:
a. Right click Web Service Extensions, and then select Add a new Web service
extension....
b. Add the Extension name
Oracle Webgate
.
c. Click Add to add the path to the extension file, and then enter the path to the
appropriate webgate.dll.
Webgate_install_dir\access\access\oblix\apps\webgate\bin\webgate.dll
Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
33-22 Administrator's Guide for Oracle Access Management
d. Click OK to save the changes.
e. Check box beside Set extension status to allowed.
f. Click OK to save the changes.
7. Ensure that there is no webgate.dll in the ISAPI filter at the top Web site level
("web sites").
8. Perform the next set of tasks using instructions in the following topics:
a. "Setting the Impersonation DLL for Multiple Webgates" on page 33-22
b. "Enabling SSL and Client Certification for Multiple Webgates" on page 33-23
9. Repeat these steps when you install the next Webgate for the IIS instance.
33.7.2 Setting the Impersonation DLL for Multiple Webgates
Unless explicitly stated, this topic applies equally to 32-bit and 64-bit Webgates and IIS
v6.
The client's access token is known as an impersonation token. The impersonation
token identifies the client, the client's groups, and the client's privileges. The
information in the token is used during access checks when the thread requests access
to resources on the client's behalf.
The Access System authenticates and authorizes the user.
IISImpersonationExtension.dll of Access Manager in the wildcard extension behaves
like a filter for each request to the Web server. The Access System designates a special
user that does have the right to impersonate another user by configuring it using the
impersonation username/password on the AccessGate Configuration page. That
designated user must have "act as operating system" rights. DLL impersonates the
user authenticated and authorized by Access Manager and generates the
impersonation token.
You perform the following steps to set the impersonation DLL for each Webgate that
protects a Web site for a single IIS Web server instance. You can do this either
immediately after the installation task in the previous topic or all at one time.
To add the impersonation DLL to IIS configuration for individual Web sites
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Click the plus icon (+) beside the Local Computer icon in the left pane to display
your Web Sites.
3. Click Web Service Extensions in the left pane.
4. Double-click Webgate in the right pane to open the Properties panel.
5. Click the Required Files tab.
6. Click Add.
7. In the Path to file text box, type the full path to IISImpersonationExtension.dll, and
then click OK. For example:
Note: This task must be performed for each Webgate that protects an
individual Web site for a single IIS Web server instance.
Installing and Configuring Multiple Webgates for a Single IIS 6 Instance
Configuring the IIS Web Server for 10g WebGates 33-23
Webgate_install_dir\access\oblix\apps\webgate\bin\IISImpersonationExtension.dll
This example shows the default path, where Webgate_install_dir is the file system
directory where you have installed this particular Webgate.
8. Verify that the Allow button beside the Webgate icon is grayed out, which
indicates that the dll is allowed to run as a Web service extension.
9. Right click the Web site name, and then click Properties.
10. Click the Home Directory tab, and then click the Configuration button.
11. In the list box for Wildcard application maps, click the entry for
IISImpersonationExtension.dll
to highlight it, then click Edit.
12. Ensure that the box is unchecked, and then click OK.
13. Repeat these steps for each Webgate and Web site pair for the IIS Web server
instance.
14. Proceed as follows:
■Client Certificate Authentication: "Enabling SSL and Client Certification for
Multiple Webgates"
■"Confirming Multiple Webgate Installation" on page 33-24.
33.7.3 Enabling SSL and Client Certification for Multiple Webgates
You perform this task to set the enable client certification for each Webgate that
protects a Web site for a single IIS Web server instance. You can do this either
immediately after the adding the impersonation DLL to an individual Web site or all at
one time.
If you select client certificate authentication during setup, you must also add the cert_
authn.dll as one of the ISAPI filters in the respective Web site.
To enable SSL on the IIS v6 Web server
1. Start the Internet Information Services (IIS) Manager, if needed: Click Start,
Programs, Administrative Tools, Internet Information Services (IIS) Manager.
2. Expand the local computer icon to display your Web Sites.
3. Expand the appropriate individual Web Site, then expand
\access\oblix\apps\webgate\bin.
4. Right click
cert_authn.dll
and select Properties.
5. In the Properties panel, select the File Security tab.
6. In the Secure Communications sub-panel, click Edit.
7. In the Client Certificate Authentication sub-panel, click Accept Certificates and
click OK.
8. Click OK in the cert_authn.dll Properties panel.
9. Repeat for each Webgate installed on this host.
10. Proceed to the next task: "To add cert_authn.dll as an ISAPI filter".
Note: Procedures in this topic apply equally to 32-bit and 64-bit
Webgates, and IIS 6, unless stated otherwise.
Finishing 64-bit Webgate Installation
33-24 Administrator's Guide for Oracle Access Management
To add cert_authn.dll as an ISAPI filter
1. Start the Internet Information Services console, if needed.
2. Expand the local computer to display your Web Sites.
3. Right click the appropriate Web Site to display the Properties panel.
4. Click the ISAPI Filters tab, then click the Add button to display the Filter
Properties panel.
5. Enter filter name "
cert_authn
".
6. Click the Browse button and navigate to the following directory:
\Webgate_install_dir\access\oblix\apps\webgate\bin
7. Select
cert_authn.dll
as the executable.
8. Click OK on the Filter Properties panel.
9. Click Apply on the ISAPI Filters panel.
10. Click OK.
11. Repeat for each Webgate installed on this host.
12. Ensure the filters are listed in the correct order.
13. Proceed to "Confirming Multiple Webgate Installation".
33.7.4 Confirming Multiple Webgate Installation
This task applies equally to 32-bit and 64-bit Webgates, and IIS v6 Web servers.
If you perform multiple Webgate installations on one machine, multiple versions of
the postgate.dll file might be created which can cause unusual Access Manager
behavior. the postgate.dll is not supported in environments where you have multiple
Webgates configured with a single IIS v6 web server instance.
33.8 Finishing 64-bit Webgate Installation
This section describes how to complete installation of a 64-bit Webgate. You can skip
this section if you are installing a 32-bit Webgate. In this case, see instead, "Completing
Webgate Installation with IIS" on page 33-7.
Before you start tasks here, be sure that you have completed Webgate installation
according to information in Chapter 30. You must also have completed Web server
configuration updates for this Webgate either automatically during Webgate
installation or manually, as described in "Webgates for IIS v6" on page 33-4.
Task overview: Finishing installation of a 64-bit Webgate
1. Perform steps in "Setting Access Permissions, ISAPI filters, and Directory Security
Authentication" on page 33-25.
2. Enable client certificates, if desired. See "Setting Client Certificate Authentication"
on page 33-25.
3. When finished, you can:
See Also:
■"Finishing 64-bit Webgate Installation" on page 33-24
■"Confirming Webgate Installation on IIS" on page 33-26
Finishing 64-bit Webgate Installation
Configuring the IIS Web Server for 10g WebGates 33-25
■Confirm operations as described in "Confirming Webgate Installation on IIS"
on page 33-26
■Implement Windows Impersonation, as described in the Oracle Fusion
Middleware Integration Guide for Oracle Access Manager.
33.8.1 Setting Access Permissions, ISAPI filters, and Directory Security Authentication
Unless explicitly stated, this topic applies equally to 32-bit and 64-bit Webgates. It
describes setting access permissions for the Web site that you are using as a default.
To set or confirm access Permissions, ISAPI filters, and Directory Security
Authentication
1. Start the Internet Service Manager. For example, from the Start menu click
Programs then click Administrative Tools, and click Internet Service Manager.
2. Expand the local computer by clicking +, in the left panel.
3. Click to expand the Web Sites tab.
4. Right-click Default Web Site (or the site you are using as a default), and create a
virtual directory as described in "Protecting a Web Site When the Default Site is
Not Setup" on page 33-13.
5. Right-click Web Sites in the Internet Information Services tab, click Properties,
and perform the following steps:
a. From the Internet Information Services tab, click the Edit button.
b. Locate the ISAPI filter tab to confirm (or add) the filter DLLs, as follows:
Filter: If you updated the IIS Web server configuration file, webgate.dll should
be properly located.
No Filter: Add the webgate.dll filter from Webgate_install_
dir\oblix\access\apps\webgate\bin\webgate.dll
c. Save and apply any changes.
d. Click the Directory Security tab and confirm that both Anonymous Access
and Basic Authentication are selected.
Selected: Proceed to Step 6.
Not Selected: Select Anonymous Access and Basic Authentication, then save
and apply these changes.
6. Proceed as follows:
■"Setting Client Certificate Authentication", if desired
■No Client Certificate Authentication: Restart the IIS Web server.
■Filter Positions: Perform instructions in "Ordering the ISAPI Filters" on
page 33-8 to ensure that all filters have been added and are in the proper order.
33.8.2 Setting Client Certificate Authentication
This task is optional and should be performed only if you want to use client certificate
authentication. In this case, IIS and Webgate must be SSL-enabled.
Information in this topic is a sub set of details in "Enabling Client Certificate
Authentication on the IIS Web Server" on page 33-7.
Confirming Webgate Installation on IIS
33-26 Administrator's Guide for Oracle Access Management
To add cert_authn.dll as an ISAPI filter
1. Start the Internet Information Services console, if needed: Click Start, Programs,
Administrative Tools, Internet Service Manager.
2. Expand the local computer to display your Web Sites.
3. Right-click the Default Web Site (or the Web site that you use as a default), then
expand \access\oblix\apps\webgate\bin.
4. Right click cert_authn.dll and select Properties, then:
a. In the Properties panel, select the File Security tab.
b. In the Secure Communications sub-panel, click Edit.
c. In the Client Certificate Authentication sub-panel, click Accept Certificates
and click OK.
d. Click OK in the Secure Communications panel.
e. Click OK in the cert_authn.dll Properties panel.
5. Click the ISAPI Filters tab, click the Add button to display the Filter Properties
panel, and then:
6. Ensure the filters are listed in the correct order, as described in "Ordering the
ISAPI Filters" on page 33-8.
7. Proceed to "Confirming Webgate Installation on IIS" on page 33-26.
33.9 Confirming Webgate Installation on IIS
After installing Webgate and updating the IIS Web server configuration file, you can
use the Webgate diagnostics to verify the Webgate is properly installed.
To verify Webgate installation
1. Go to the URL:
http(s)://hostname:port/access/oblix/apps/webgate/bin/webgate.dll?progid=1
where hostname refers to the name of the computer hosting the Webgate; port refers
to the Web server instance port number.
2. The Webgate diagnostic page should appear.
■Successful: If the Webgate diagnostic page appears, the Webgate is
functioning properly and you can dismiss the page.
■ Unsuccessful: If the Webgate diagnostic page does not open, the Webgate is
not functioning properly. In this case, the Webgate should be uninstalled and
reinstalled. For more information about removing Access Manager see
"Removing a 10g WebGate from the Access Manager 11g Deployment" on
page 30-27, in the chapter on installing a 10g Webgate Chapter 30.
Note: This task is the same for both 32-bit and 64-bit Webgates. It is
the same whether you are installing one or more Webgates per IIS Web
server instance.
Removing Web Server Configuration Changes Before Uninstall
Configuring the IIS Web Server for 10g WebGates 33-27
33.10 Starting, Stopping, and Restarting the IIS Web Server
When instructed to restart your IIS Web server during Webgate installation or setup,
be sure to follow any instructions that appear on the screen. Also, consider using
net
stop iisadmin
and
net start w3svc
are good ways to stop and start the Web server.
The
net
commands help to ensure that the Metabase does not become corrupted
following an installation.
33.11 Removing Web Server Configuration Changes Before Uninstall
The information in this section applies equally to 32-bit and 64-bit Webgates.
Web server configuration changes that occur during installation must be manually
reverted after uninstalling the Webgate. For example, the ISAPI transfilter will be
installed for IIS Webgate. However, if you uninstall Webgate this is not removed
automatically. Also, the created Web service extension and the link to the identity
directory will not be removed. This type of information must be removed manually.
These are examples of information to remove, not a complete list.
Further, you must remove any changes that you manually made to your Web server
configuration file for the Webgate should be removed. For more information about
what is added for each component, look elsewhere in this chapter.
To fully remove a Webgate and related filters from IIS, you must do more than simply
remove the filters from the list in IIS. IIS retains all of its settings in a metabase file. On
Windows 2000 and later, this is an XML file that can be modified by hand. There is also
a tool available, MetaEdit, to edit the metabase. MetaEdit looks like Regedit and has a
consistency checker and a browser/editor. To fully remove a Webgate from IIS, use
MetaEdit to edit the metabase.
Removing Web Server Configuration Changes Before Uninstall
33-28 Administrator's Guide for Oracle Access Management
34
Configuring Lotus Domino Web Servers for 10g WebGates 34-1
34
Configuring Lotus Domino Web Servers for
10g WebGates
This chapter provides tips about installing and configuring Lotus Domino to operate
with the WebGate. Topics include:
■Prerequisites
■Installing the Domino Web Server
■Setting Up the First Domino Web Server
■Starting the Domino Web Server
■Enabling SSL (Optional)
■Installing a Domino Security (DSAPI) Filter
34.1 Prerequisites
Ensure that your Oracle Access Management Console is running and get familiar with:
■"Introduction to Policy Enforcement Agents" on page 14-1
■"About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2" on
page 30-3
34.2 Installing the Domino Web Server
Before you install the WebGate with a Domino Web server, you need a properly
installed and set up Domino Enterprise Server R5. The following information focuses
on Solaris. However, with some modifications, these steps can be used as a guide for
other UNIX systems.
To download the Domino Web server on UNIX
1. Download Lotus Domino from the following URL:
Note: The information here presumes that you are familiar with your
operating system commands, Lotus Notes, and the Domino Web
server.
Note: You need to register if this is the first time you download from
lotus.com.
Setting Up the First Domino Web Server
34-2 Administrator's Guide for Oracle Access Management
http://www-10.lotus.com/ldd/down.nsf
2. Untar the downloaded file to your staging area. For example:
gct@planetearth[/export/users2/gct/temp] 433 : ls C37UUNA.tar
gct@planetearth[/export/users2/gct/temp] 434 : tar xf C37UUNA.tar
gct@planetearth[/export/users2/gct/temp] 435 : ls C37UUNA.tar sol/
You need to install Domino as user "root". The installation script creates soft link,
/opt/lotus, to link to your Lotus Domino installation directory.
To install the Domino Web server on UNIX
1. Run the install script for the Domino Web server. For example:
gct@planetearth[/export/users2/gct/temp/sol] 441 : su root
Password:
root@planetearth[/export/users2/gct/temp/sol] 1 : ls
install* license.txt script.dat sets/ tools/
root@planetearth[/export/users2/gct/temp/sol] 2 :
root@planetearth[/export/users2/gct/temp/sol] 2 : ./install
========================================================
Domino Server Installation
========================================================
Welcome to the Domino Server Install Program.
Type h for help on how to use this program.
Press TAB to begin the installation.
--------------------------------------------------------
Type h for help
Type e to exit installation
Press TAB to continue to the next screen.
--------------------------------------------------------
You are asked to select the setup type.
2. Select Setup type. For example:
Select Setup type: [Domino Enterprise Server]
3. Complete the installation with the following considerations in mind. For example:
■The default program directory is set to /opt/lotus. You may over write it to
another directory. For example, /export/home/WWW/lotus.
■The default data directory is set to /local/notesdata1. You may also over write
this to something else. For example, /export/home/WWW/lotus/data1.
■Over write Domino UNIX user to own data directory. The default user is set to
notes. You may change it to a valid UNIX user. For example, gct or root.
■Over write "The UNIX user for this directory must be a member of this group".
The default group is set to notes. You may change it to a valid UNIX group
name. For example: oblix.
34.3 Setting Up the First Domino Web Server
After successfully installing, you must set up the first Domino server.
Note: Be sure to put Domino data directory in your $PATH before
you proceed from here.
Enabling SSL (Optional)
Configuring Lotus Domino Web Servers for 10g WebGates 34-3
To set up first Domino server
1. Run /opt/lotus/bin/http httpsetup.
By default, Domino will use port 8081.
2. Ensure that port 8081 is not already in use.
3. Launch your browser and enter the URL that follows. For example:
http://hostname:8081
4. Follow instructions on the screen and keep the following in mind.
■Check HTTP to get the Web server.
■Ensure the designated Administrator has a first and last name.
■Keep passwords simple, and record them in a safe location. For example,
oracleoracle.
5. Run all commands as the UNIX user that you've configured for this Domino Web
server.
34.4 Starting the Domino Web Server
After successfully setting up the first Domino Web server, you must start it.
To start Domino server
1. Run /opt/lotus/bin/server.
2. Launch your browser and enter the following URL.
For example:
http://hostname:80/names.nsf
You will be prompted for login name and password.
3. Select Server-Server.
4. Select your intended server.
5. Select Edit Server.
6. Select Ports, select Internet Ports, then click Web.
7. Change the value for TCP/IP port number to your desired port number.
8. Click Save and Close to save all your changes.
9. Restart server /opt/lotus/bin/server.
34.5 Enabling SSL (Optional)
Enabling SSL is not mandatory for the WebGate. However, if you need to generate a
keyring file (.kyr) and its corresponding stash file (.sth) from the Lotus Notes client on
a Windows system to the UNIX system, use the steps that follow.
To generate the keyring and stash files
1. Launch the Lotus Notes Client on your Windows system.
WARNING: Do not run as root.
Installing a Domino Security (DSAPI) Filter
34-4 Administrator's Guide for Oracle Access Management
For example:
File, select Databases, then click Open
2. Select Server Certificate Admin.
3. Create the key ring file.
4. Create the certificate request.
5. Install the trusted root certificate into the key ring file.
6. Install the certificate into the key ring file.
7. Copy or ftp the newly created keyring file and stash file from the Windows system
to your UNIX computer.
8. Store both files in your Domino data directory.
To enable SSL
1. Launch your browser and enter the following URL.
For example:
http://hostname:port/names.nsf
You will be prompted for login name and password
2. Select Server-Server.
3. Select your intended server.
4. Select Edit Server.
5. Select Ports, select Internet Ports, then click Web.
6. In the SSL Key file name field, enter the absolute path to the keyring file.
7. Change the SSL Port number value to your desired port number.
8. Enable SSL port status.
9. Select Client Certificate "Yes" for Client Certificate authentication.
10. Click Save and Close to save all your changes.
11. Restart the Web server.
For example:
/opt/lotus/bin/server
34.6 Installing a Domino Security (DSAPI) Filter
The Domino security API filter, DSAPI, is an authentication method that enables you
to register a DLL with the Domino Web server. In this case, the Web server calls the
WebGate DLL to authenticate the user when a request for authentication occurs rather
than using SSL or basic authentication.
Authentication within Domino is optional with the Access Manager DSAPI filter. You
can implement certain aspects of authentication that the default Web server does not
support.
Task overview: Completing WebGate and filter installation
1. Before you install the WebGate on a Domino Web server, complete all steps
described earlier.
Installing a Domino Security (DSAPI) Filter
Configuring Lotus Domino Web Servers for 10g WebGates 34-5
2. Complete the WebGate installation and Web server update as described in
"Locating and Installing the Latest 10g WebGate for Access Manager 11g" on
page 30-14.
3. Set
ObWebGateInstallDir=$WEBGATE_INSTALL_DIR
in your
notes.ini
file.
4. See "Completing the WebGate Installation" on page 34-5 and choose one of the two
options discussed there.
34.6.1 Completing the WebGate Installation
To ensure the Domino Web Server can use the WebGate DLL, you need to edit the
enter the name or names of the DLL/DLLs (DSAPI libraries) to be called for
authentication in the DSAPI filter file names field of the HTTP tab under the Internet
Protocols tab in the Server document.
There are two ways to install the filter:
■Through a Web browser and names.nsf (option 1)
■Through a Lotus Notes workstation and the Address Book (option 2)
Option 1: To setup the DSAPI filter to access names.nsf
1. Go to the names.nsf URL and log in. For example:
http://hostname:port/names.nsf
2. Click the Server-Servers link.
A Java applet will be loaded.
3. Select a server from those listed.
4. Click the Edit Server link to go to Edit mode.
5. Click the Internet Protocols link.
By default, the HTTP tab is selected and information is displayed in Edit mode.
6. Look for DSAPI where it says "DSAPI filter file names:", then type in the absolute
path to the libwebgate.so file.
7. Save your changes.
8. Restart the Domino http server task.
Option 2: To access the Address Book through Lotus Notes
1. Open Domino Name and Address book. For example, select:
File, Database, Open, then click Address Book
2. Switch to server view and open the server document.
3. Edit the server document.
4. Click the Internet Protocols tab.
By default, the HTTP tab is selected and information is displayed in Edit mode.
Note: Relative paths will be based on the Domino executable
directory. DSAPI filter libraries will be called to handle events in the
order they appear in this list.
Installing a Domino Security (DSAPI) Filter
34-6 Administrator's Guide for Oracle Access Management
5. Look for DSAPI where it says "DSAPI filter file names:", then type in the absolute
path to the libwebgate.so file.
6. Save your changes.
7. Restart the Domino http server task.
Part VIII
Part VIII
Managing the Adaptive Authentication
Service and Oracle Mobile Authenticator
The Adaptive Authentication Service is a One Time Password Authenticator that
provides multifactor authentication in addition to the standard user name and
password type authentication.
This part contains the following chapters:
■Chapter 35, "Introducing the Adaptive Authentication Service"
■Chapter 36, "Configuring the Oracle Mobile Authenticator"
35
Introducing the Adaptive Authentication Service 35-1
35
Introducing the Adaptive Authentication
Service
[25]
The Adaptive Authentication Service offers stronger multifactor (also referred to as
second factor) authentication for sensitive applications that require additional security
in addition to the standard user name and password type authentication. Multifactor
authentication involves more than one stage when verifying the identity of an entity
attempting to access services from a server or on a network. For example, when
multifactor authentication is enabled and configured, the traditional user name and
password is the first factor. Additional security is enforced by adding a One Time Pin
(OTP) step, or an Access Request (Push) Notification step as a second factor in the
authentication process.
The following sections contain more details about the Adaptive Authentication Service
and Access Manager Second Factor Authentication.
■Using the Adaptive Authentication Service
■Working with the Adaptive Authentication Service
■Understanding Adaptive Authentication Service and OMA Configurations
■Configuring the Adaptive Authentication Service
35.1 Using the Adaptive Authentication Service
The Adaptive Authentication Service offers the ability to add multiple steps to the
authentication process. Additional security may be enforced by adding a OTP step, or
an Access Request (Push) Notification step after initial user authentication. This may
or may not involve the use of the Oracle Mobile Authenticator, a mobile device app
that uses Time-based One Time Password and push notifications to authenticate users
within the second factor authentication scheme.
The Adaptive Authentication Service has to be licensed and explicitly enabled in order
to use it. Once the proper product license is procured you can enable the Adaptive
Authentication Service using the Oracle Access Management Console. From the Oracle
Access Management Console, the Adaptive Authentication Service can be enabled or
disabled from the Available Services link on the Configuration Launch Pad. These
section links contain more details.
Note: installing Oracle Adaptive Access Manager is not required
since the Adaptive Authentication Service uses a set of libraries that
makes a OTP step feasible using the Oracle Mobile Authenticator.
Working with the Adaptive Authentication Service
35-2 Administrator's Guide for Oracle Access Management
■Section 3.2, "Enabling or Disabling Available Services"
■Section 2.4, "Understanding the Oracle Access Management Console"
For an introduction to the Adaptive Authentication Service and how it works, see the
next section, Working with the Adaptive Authentication Service.
35.2 Working with the Adaptive Authentication Service
The Adaptive Authentication Service offers second factor authentication. This second
factor can be a One Time Pin (OTP) or an Access Request (or push) Notification. After
an initial successful user/password authentication, a Second Factor Authentication
page is displayed from which the user selects their preferred method of second factor
authentication. The options are:
■OTP from Oracle Mobile Authenticator
■OTP through SMS
■OTP through Email
■Access Request Notification from Oracle Mobile Authenticator
Figure 35–1 is a screenshot of the Second Factor Authentication page in which the user
has selected the OTP Through Email option. In this case, the user receives the OTP via
a configured Email address.
Figure 35–1 Second Factor Authentication Preferred Method Page
If the selected option is either OTP From Oracle Mobile Authenticator or Access
Request Notification from Oracle Mobile Authenticator, the Adaptive Authentication
Service works in tandem with the Oracle Mobile Authenticator (OMA), a mobile
device app that uses Time-based One Time Password and push notifications to
authenticate users within the second factor authentication scheme. In advance of using
the OTP from OMA or Access Request Notification from OMA options, a user must
download a supported authenticator app to a mobile device (for example, Oracle
Mobile Authenticator to an Apple iPhone) and configure it by clicking a link provided
by the Access Manager administrator. (The OMA app is not needed if using the OTP
through Email or OTP through SMS options.)
Working with the Adaptive Authentication Service
Introducing the Adaptive Authentication Service 35-3
The following sections contain more details on each option and how the Oracle Mobile
Authenticator works.
■Understanding the One Time Password Option
■Understanding the Access Request (Push) Notification Option
■Using the Oracle Mobile Authenticator with OTP And Access Request
35.2.1 Understanding the One Time Password Option
Let’s assume the Adaptive Authentication Service is enabled and configured for
second factor authentication. When the user accesses a resource protected by Access
Manager, a page is displayed that requests a user name and password. If these initial
credentials are authenticated successfully, a Second Factor Authentication Preferred
Method Page page is displayed and the user selects from one of the options. In this use
case, the user selects one of the OTP options and receives a OTP through SMS/Email
or generated and displayed by the OMA app. The user enters the OTP in the OTP
login page. Figure 35–2 is a screenshot of the OTP login page.
Figure 35–2 One Time Password Login Page
Once the OTP is successfully validated by Access Manager, the user will be directed to
the protected resource. On failure of any of the OTP options, an error message will be
displayed, and the user will be returned to the same OTP page.
Note: The Oracle Mobile Authenticator mobile device app must be
configured to retrieve a secret key required to generate a OTP.
Information on the secret key is in Section 35.4.1, "Generating a Secret
Key for the Oracle Mobile Authenticator." Information on configuring
the OMA is in Chapter 36, "Configuring the Oracle Mobile
Authenticator."
Working with the Adaptive Authentication Service
35-4 Administrator's Guide for Oracle Access Management
The following sections have additional details on how the user may receive the OTP.
■Using OTP through Email/SMS
■Using OTP from Oracle Mobile Authenticator
35.2.1.1 Using OTP through Email/SMS
In cases where OTP through Email or SMS is chosen, Access Manager will send a OTP
to the configured email address or phone number respectively. The user then enters
the received OTP and Access Manager will validate it. On a successful validation, the
user will be directed to the protected resource.
The Adaptive Authentication Service expects that the required email address or phone
number is configured in the appropriate field as documented in Configuring the
Adaptive Authentication Plug-in. When using the OTP with Email or SMS option, the
OTP is accessible from any device where the email address can be accessed or from the
SMS app associated with the specified phone number, respectively.
35.2.1.2 Using OTP from Oracle Mobile Authenticator
In the use case where a OTP will be generated and displayed by the OMA app on a
mobile device, the app must be configured with the Access Manager server details.
Following this configuration, the user authenticates with Access Manager using the
proper credentials and Access Manager will return a secret key. This secret key is
unique to each user and known only to Access Manager and the OMA. The secret key
is used to generate the OTP. See Section 35.4.1, "Generating a Secret Key for the Oracle
Mobile Authenticator" for information on how to populate this secret key with the
required data.
After Access Manager generates a OTP for the user using the secret key, the OTP is
pushed to the OMA. The user then enters the OTP in the One Time Pin Login Page. If
the OTP generated by Access Manager matches the OTP entered by the user, access to
the protected resource is allowed. If the OTP entries do not match, access is not
allowed. See Using the Oracle Mobile Authenticator with OTP And Access Request for
more details.
35.2.2 Understanding the Access Request (Push) Notification Option
Again let’s assume the Adaptive Authentication Service is enabled and configured for
second factor authentication. When the user accesses a resource protected by Access
Note: Access Manager validates the OTP using the Time-based One
Time Password (TOTP) algorithm. TOTP is a two-factor authentication
scheme specified by the Internet Engineering Task Force (IETF) under
RFC 6238 and used by the Adaptive Authentication Service. TOTP is
an extension of the HMAC-based One Time Password algorithm and
supports a time-based moving factor (a value that must be changed
each time a new password is generated).
Note: The OMA mobile app is not used for the OTP through Email
or OTP through SMS options.
Note: The OMA refreshes the OTP every 30 seconds so the OTP
entered by a user is valid only for that period of time.
Working with the Adaptive Authentication Service
Introducing the Adaptive Authentication Service 35-5
Manager, a page is displayed that requests a user name and password. If these initial
credentials are authenticated successfully, a Second Factor Authentication Preferred
Method Page page is displayed and the user selects from one of the options. In this use
case, the user selects Access Request Notification from Oracle Mobile Authenticator.
Figure 35–3 is a screenshot of the Second Factor Authentication Preferred Method Page
with Access Request Notification selected.
Figure 35–3 Access Request Notification Preferred Method Page
When the user selects Access Request Notification from the Second Factor
Authentication Preferred Method Page, Access Manager sends an Access Request
Notification to either the Apple Push Notification Server or the Google Notification
Server depending upon the user’s configured device. The notification server then
pushes a notification to the mobile device and the user will approve or deny it. Based
on a successful response, the user will be directed to the protected resource. On failure,
an error message will be displayed and the user will be returned to the same OTP
page. Figure 35–4 is a screenshot of the Access Request Notification message displayed
during this process.
Note: This is a push notification option which works in tandem with
the OMA. See Using the Oracle Mobile Authenticator with OTP And
Access Request for more details.
Understanding Adaptive Authentication Service and OMA Configurations
35-6 Administrator's Guide for Oracle Access Management
Figure 35–4 Access Request Notification Wait Screen
35.2.3 Using the Oracle Mobile Authenticator with OTP And Access Request
Depending on the selected option, the Adaptive Authentication Service will need to
work in tandem with the Oracle Mobile Authenticator (OMA), a mobile device app
that uses Time-based One Time Password and push notifications to authenticate users
with the second factor authentication scheme. To receive the OTP or Access Request
Notification using the OMA, a user downloads it to an Apple or Android mobile
device and configures it by clicking a link provided by the Access Manager
administrator. Access Manager and OMA must share a secret key. See Section 35.4.1,
"Generating a Secret Key for the Oracle Mobile Authenticator" for details on the secret
key. For information on configuring OMA, see Chapter 36, "Configuring the Oracle
Mobile Authenticator."
35.3 Understanding Adaptive Authentication Service and OMA
Configurations
You need to configure the Adaptive Authentication Service and, depending on the
option, the OMA.
■To configure the Adaptive Authentication Service, perform the procedures
documented in Section 35.4, "Configuring the Adaptive Authentication Service."
■For information on configuring the OMA, see Chapter 36, "Configuring the Oracle
Mobile Authenticator."
35.4 Configuring the Adaptive Authentication Service
The following configurations are for using the Adaptive Authentication Service. It is
assumed that you have installed Access Manager, a WebGate and Oracle HTTP Server
(OHS). Some of these configurations are specific to one or the other Adaptive
Authentication Service options.
■Generating a Secret Key for the Oracle Mobile Authenticator
Note: The OMA app is not needed if using the OTP through Email
or OTP through SMS options as discussed in Using OTP through
Email/SMS.
Configuring the Adaptive Authentication Service
Introducing the Adaptive Authentication Service 35-7
■Configuring Mobile OAuth Services to Protect the Secret Key
■Configuring the Adaptive Authentication Plug-in
■Setting Credentials for UMS, iOS and Android
■Creating a Java KeyStore for iOS Access Request (Push) Notifications
■Configuring Host Name Verifier for Android Access Request (Push) Notifications
■Configuring Access Manager for VPN Use Case
35.4.1 Generating a Secret Key for the Oracle Mobile Authenticator
A secret key needs to be shared between Access Manager and the OMA app.
Businesses can generate secret keys in different ways so the means in which the secret
key is generated is not important. The following RESTful endpoint is used to generate
the secret key for a user in the Oracle Access Management identity store.
http://<HOST>:<PORT>/ms_oauth/resources/userprofile/secretkey
In the case of OMA online configuration (which is Oracle’s recommended method of
configuration), OMA uses the RESTful endpoint to store the key for a user in the
identity store. In the cases of OMA manual configuration or Google Authenticator, the
administrator sets up a web application which allows the user to generate a secret key
also using above mentioned RESTful endpoint. The secret key is stored as a String in
an LDAP attribute in the identity store and the name of this attribute must is passed to
the business in the RESTful endpoint configuration before they generate the secret key.
For more details, see Section 36.1, "Understanding Oracle Mobile Authenticator
Configuration."
35.4.2 Configuring Mobile OAuth Services to Protect the Secret Key
Using the Oracle Access Management Console, follow this procedure to enable the
Mobile and Social Service and update the User Profile Service to protect the REST
Secret Key endpoint using the Basic Authentication Scheme.
1. From the Configuration Launch Pad, click Available Services.
2. Click Enable to enable Mobile and Social, if not already.
3. From the Mobile Security Launch Pad, click Mobile OAuth Services.
4. Click DefaultDomain under Mobile OAuth Identity Domains.
5. From the Resource Servers tab, click UserProfile under User Profile Services.
6. Expand the Resource URIs.
7. From the
/secretkey
tab, expand Attributes.
8. Change the value of
basicauth.allowed
to true.
9. Click Apply.
35.4.3 Configuring the Adaptive Authentication Plug-in
Access Manager provides the Adaptive Authentication Plug-in to be used for
two-factor authentication. Use this procedure to configure the Adaptive
Authentication Plug-in using the Oracle Access Management Console.
1. Login to the Oracle Access Management Console as System Administrator.
Configuring the Adaptive Authentication Service
35-8 Administrator's Guide for Oracle Access Management
2. From the Application Security Launch Pad, click Authentication Plug-ins in the
Plug-ins panel.
3. From the Authentication Plug-in tab, type Adaptive in the quick search box above
the Plug-in Name column and hit Enter.
The AdaptiveAuthenticationPlugin is displayed.
4. Change the properties displayed under Plug-in Details:
AdaptiveAuthenticationPlugin as applicable to your environment.
Table 35–1 describes the properties.
Table 35–1 Adaptive Authentication Plugin Properties
Property Description Default Value
Required for
Challenge Method
IdentityStoreRef Identity store name UserIdentityStore1 All
TotpSecretKeyAttribut
e
Name of the user attribute
in which the secret key is
stored.
Attribute
description
OTP using OMA,
Time based OTP
TotpTimeWindow The number of OTP codes
generated by the mobile
device that Access Manager
will accept for validation.
Since the mobile device
generates a new OTP every
30 seconds, if the value is 3,
Access Manager will accept
the current and last three
OTPs generated by the
mobile device.
3OTP using OMA,
Time based OTP
PushAPNsProdServer If set to true, the APNS
production server will be
used to send notifications.
false Access Request
Notifications (iOS)
PushProxyHost Name of the proxy host if
notifications are to sent to
the server using a proxy.
Access Request
Notifications
PushProxyPort Proxy port if notifications
are to sent to the server
using a proxy.
80 Access Request
Notifications
PushProxyProtocol Proxy protocol https:// Access Request
Notifications
UmsAvailable When Adaptive
Authentication Service
requires UMS to send Email
and SMS, set to true.
false SMS, Email
UmsClientUrl URL of UMS web service SMS, Email
PhoneField Attribute in the identity
store where the user phone
number is stored
mobile SMS
EmailField Attribute in the identity
store where the user email
address is stored
mail Email
Configuring the Adaptive Authentication Service
Introducing the Adaptive Authentication Service 35-9
5. Click Save.
6. Update the same properties as applicable in the AdaptiveAuthenticationModule
by clicking Authentication Modules under Plug-ins in the Access Manager Launch
Pad.
From the Authentication Modules tab, search for AdaptiveAuthenticationModule.
Not all properties listed in Table 35–1 will be available.
35.4.4 Setting Credentials for UMS, iOS and Android
Use the WLST command line script to set the credentials for the Oracle User
Messaging Service (UMS), the iOS certificate or the Android API key. These credentials
are used by the OAM Server in the process of sending SMS/Email and push
notifications. Table 35–2 contains information for the items which are needed to
complete the procedure in this section.
1.
cd <MW_HOME>/oracle_common/common/bin
2.
./wlst.sh
3.
connect()
4. Enter the WebLogic user name and password when prompted.
5. Press Enter to accept the default URL or modify the host and port as necessary and
press Enter.
Totp_Enabled
Email_Enabled
Sms_Enabled
Push_Enabled
Controls the options
displayed in the UI. If
enabled and user is not
registered for Push, not
setup for TOTP, or doesn’t
have email/phone
populated in id store, those
options won’t be displayed.
For example if user has not
registered for TOTP and
Push but has email
populated then Email will
be the only option shown.
true
NOTE: Properties
should be set to
false only when the
Administrator
wants to disable a
particular feature
for all users.
Table 35–2 Server Side Configuration for Adaptive Authentication Service
Configuration Information Challenge Method
iOS
Certificate/Password
https://developer.apple.com/libr
ary/mac/documentation/Networking
Internet/Conceptual/RemoteNotifi
cationsPG/Chapters/ApplePushServ
ice.html
Access Request (Push)
notification using iOS
API Key
https://developers.google.com/we
b/updates/2015/03/push-notificat
ons-on-the-open-web?hl=en
Access Request (Push)
notification using Android
UMS Credential UMS credentials that OAM will use
to establish the connection to UMS
Web service.
Email/SMS
Table 35–1 (Cont.) Adaptive Authentication Plugin Properties
Property Description Default Value
Required for
Challenge Method
Configuring the Adaptive Authentication Service
35-10 Administrator's Guide for Oracle Access Management
6. Run one or more of the following commands to set credentials for the UMS server,
iOS or Android depending on your deployment.
■For OTP for email/SMS only:
createCred(map="OAM_CONFIG", key="umsKey", user="<UMS SERVER USER NAME>",
password="<UMS SERVER PASSWORD>")
For example:
createCred(map="OAM_CONFIG", key="umsKey", user="weblogic",
password="password")
■For Access Request (Push) Notifications on iOS only:
createCred(map="OAM_CONFIG", key="pushApnsCertKey", user="apnskey",
password="<CERTIFICATE STORE PASSWORD>")
For example:
createCred(map="OAM_CONFIG", key="pushApnsCertKey", user="apnskey",
password="password")
See Creating a Java KeyStore for iOS Access Request (Push) Notifications for
additional information when using iOS.
■For Access Request (Push) Notifications on Android only:
createCred(map="OAM_CONFIG", key="omaApiKey", user="omaApiKey",
password="<API KEY VALUE>")
For example:
createCred(map="OAM_CONFIG", key="omaApiKey", user="omaApiKey",
password="ADDGFDGDFGRTERSDFSDFSDFTYERTERTASDASDASD")
7. Verify the keys by logging into Fusion Middleware Control, navigating to Domain
> Security > Credentials, and checking the OAM_CONFIG map for the keys input
using the commands.
35.4.5 Creating a Java KeyStore for iOS Access Request (Push) Notifications
When using Access Request Notifications on iOS, create a Java KeyStore (JKS) by
using the cert file and key file. Once the JKS is created, rename it as
APNsCertificate.jks
and put it in the
<domain>/config/fmwconfig
directory of the
Oracle Access Management installation.
Note: Replace <UMS SERVER USER NAME>, <UMS SERVER
PASSWORD>, <CERTIFICATE STORE PASSWORD> and <API KEY
VALUE> with values specific to your environment. Do not change the
values for any parameters in these commands but those listed and
marked as variables.
Note: For information on how to update, delete or otherwise manage
credentials using Fusion Middleware Control, see Oracle Fusion
Middleware Securing Applications with Oracle Platform Security Services.
Configuring the Adaptive Authentication Service
Introducing the Adaptive Authentication Service 35-11
The JKS should contain the user's locally generated private key and the Apple Push
Notification service (APNs) certificate downloaded from the Apple Developer Center.
The following sample commands generate and import the certificate.
openssl x509 -in aps_production.cer -inform DER -out aps_production.pem
-outform PEM
openssl pkcs12 -nocerts -in OMAKey.p12 -out OMAKey.pem
openssl pkcs12 -export -inkey OMAKey.pem -in aps_production.pem
-out iOS_prod.p12
keytool -import -keystore APNsCertificate.jks -file aps_production.cer
-alias PushCert
keytool -importkeystore -destkeystore APNsCertificate.jks
-deststoretype JKS -srcstoretype PKCS12 -srckeystore iOS_prod.p12
These commands assume:
■aps_production.cer to be the name of the APNs certificate downloaded from the
Apple Developer Center.
■OMAKey.p12 is the user's locally generated private key.
Also see Setting Credentials for UMS, iOS and Android.
35.4.6 Configuring Host Name Verifier for Android Access Request (Push) Notifications
If you are setting up Android for Access Request notification, use the WebLogic
console to update the WebLogic Managed Server for host name verification. This step
is required for Access Request notification configuration on Android only. It allows the
verification of host names represented using wildcards; for example, *.googleapis.com.
1. Navigate to base_domain -> Summary of Environment -> Summary of Servers ->
oam_server1.
2. Click the SSL tab.
3. Expand Advanced and select the Hostname verification entry to configure the
Hostname Verifier.
4. Enter
weblogic.security.utils.SSLWLSWildcardHostnameVerifier
as the
Custom Hostname Verifier.
5. Click Save.
6. Restart the oam_server1.
35.4.7 Configuring Access Manager for VPN Use Case
This use case procedure illustrates how to configure Access Manager when a user will
be accessing a protected resource using VPN software.
Note: The section Maintain Your Certificates, Identifiers, and Profiles at
the following Apple URL provides relevant information about app
distribution certificates and APNs.
https://developer.apple.com/library/ios/documentation/IDEs/C
onceptual/AppDistributionGuide/Introduction/Introduction.htm
l
Configuring the Adaptive Authentication Service
35-12 Administrator's Guide for Oracle Access Management
1. Login to the Oracle Access Management Console as System Administrator.
2. From the Application Security Launch Pad, click Application Domains in the
Access Manager panel.
The Application Domain tab is displayed.
3. Click Search to display all available Application Domains.
4. Click the Application Domain name that contains the resource being protected.
The Application Domain opens in a new tab.
5. Click Authentication Policies in the Application Domain tab.
6. Click the name of the Authentication Policy that is being used to protect the
particular resource for which two factor authentication is being configured.
The appropriate Authentication Policy opens in a new tab.
7. Click Advanced Rules in the Authentication Policy tab.
8. Add a new rule by clicking the plus sign (+) under Post Authentication.
The Add Rule dialog is displayed.
9. Enter a Rule Name and the following jython script.
location.clientIP.startswith(’10.’)
See Section 22.10.2, "Using Context Data for Advanced Rules" for details.
10. Select the AdaptiveAuthenticationScheme Authentication Scheme from the If
Condition is True drop-down list.
This Authentication Scheme will be used when the defined condition is true.
11. Click Add and then Apply to complete the procedure.
36
Configuring the Oracle Mobile Authenticator 36-1
36
Configuring the Oracle Mobile Authenticator
[26]
The Oracle Mobile Authenticator is a mobile device app that uses Time-based One
Time Password (TOTP) and push notifications to authenticate users with a two-factor
authentication scheme. The Oracle Mobile Authenticator mobile device app must be
configured to retrieve the secret key required to generate a One Time Password (OTP).
The following sections contain configuration details when using the Oracle Mobile
Authenticator app on an iOS or Android mobile device.
■Understanding Oracle Mobile Authenticator Configuration
■Using the Oracle Mobile Authenticator App on iOS
■Using the Oracle Mobile Authenticator App on Android
■Configuring the Google Authenticator App
■Using a QR Code for Configuration
36.1 Understanding Oracle Mobile Authenticator Configuration
The Oracle Mobile Authenticator (OMA) app can retrieve a secret key required to
generate a OTP or register with Access Manager to receive push notifications.
Provisioning the secret key can be done online or offline however registering for push
notifications can only be done while online.
■Online Configuration uses the REST web services and the Mobile OAuth Services
described in Section 35.4.1, "Generating a Secret Key for the Oracle Mobile
Authenticator" and Section 35.4.2, "Configuring Mobile OAuth Services to Protect
the Secret Key." Once enabled, the OMA app can invoke this service to get a secret
key or register for push notifications. To invoke the REST web services, OMA
needs to know its location URL. In this case, the Oracle Access Management
administrator creates a web page to configure the OMA. When the user taps on
the web page’s link (provided via e-mail), it launches the OMA, passes the
location URL to the app and the REST web services location is configured. The
format of the location URL is as follows.
oraclemobileauthenticator://settings?ServiceName::=<name_of_service>
&ServiceType::=SharedSecret/Notification/Both&
SharedSecretAuthServerType::=HTTPBasicAuthentication/OAuthAuthentication
&LoginURL::=http://<host>:<port>/secretKeyURL
&NotificationAuthServerType::= HTTPBasicAuthentication
Note: For details on the secret key, see Section 35.4.1, "Generating a
Secret Key for the Oracle Mobile Authenticator."
Understanding Oracle Mobile Authenticator Configuration
36-2 Administrator's Guide for Oracle Access Management
&PushPreferencesEndpoint::=http://<host>:<port>/preferencesURL
&ChallengeAnswerEndpoint::=http://<host>:<port>/challengeAnswerURL
&SenderID::=<senderID>
&OAuthClientID::=<clientID>
&OAMOAuthServiceEndpoint::=http://<host>:<port>/oauthserviceURL
&OAuthScope::=<OAuthScope>
Table 36–1 documents definitions for the location URL parameters.
Online configuration details are also documented in Configuring the Oracle
Mobile Authenticator for iOS and Configuring the Oracle Mobile Authenticator
for Android. OAuth configuration details are in Chapter 53, "Configuring OAuth
Services."
■Offline Configuration supports use cases in which the mobile device can not
connect to the REST end point or the parameters needed to generate the OTP are
different than the defaults. The Access Manager administrator sets up a web
Table 36–1 Location URL Parameter Definitions
Parameter Definition
ServiceName Name of the service. This name should be unique in OMA. If
another configuration with same name is sent then it will
prompt the user to overwrite the previous one
ServiceType The type of service provided by this configuration i.e. one-time
password, notification or a hybrid service which combines
both one-time password and notification. Value can be
SharedSecret, Notification or Both.
SharedSecretAuthServerType The type of authentication by which shared secret provisioning
REST endpoint is protected. Value can be
HTTPBasicAuthentication or OAuthAuthentication.
LoginURL The REST endpoint that provisions the shared secret for
generating one-time passwords. The value specified for the
LoginURL query parameter is based on the OAuth settings for
Oracle Mobile Authenticator.
NotificationAuthServerType The type of authentication by which notification registration
endpoint is protected. Currently only HTTP basic
authentication is supported thus the value is
HTTPBasicAuthentication.
PushPreferencesEndpoint The REST endpoint where push notification preferences should
be sent.
ChallengeAnswerEndpoint The REST endpoint where push notification responses should
be sent.
SenderID The Android sender ID for sending push notifications. The
SenderID is only required on Android; it is not required when
using iOS.
OAuthClientID OAuth client ID if SharedSecretAuthServerType is set for
OAuth
OAMOAuthServiceEndpoint OAM OAuth service endpoint to get OAuth profiles available
on the server.
OAuthScope The OAuth scope required to access the shared secret.
Note: Oracle recommends using online configuration.
Using the Oracle Mobile Authenticator App on iOS
Configuring the Oracle Mobile Authenticator 36-3
application which allows the user to generate or recreate a secret key. The user logs
into this web application and, after authentication, the user is allowed to view the
secret key and enter it in the OMA app manually. The secret key can also be
delivered via an offline configuration URL so the administrator has the option of
changing the OTP generation parameters (time step, hashing algorithm and the
like). The format of the offline configuration URL is:
oraclemobileauthenticator://settings?SharedSecretValue::=<secret_key>
&AccountName::=<username>&SharedSecretEncoding::=Base32/Base64String
&OTPAlgorithm::=TOTP
&HashingAlgorithm::=MD5/SHA-1/SHA-224/SHA-256/SHA-384/SHA-512
&OTPLength::=<lenght_of_OTP>&TimeStep::=<time_in_seconds>
Table 36–2 contains details regarding the parameters.
Offline configuration details are also documented in Configuring Oracle Mobile
Authenticator for Offline OTP Generation on iOS and Configuring Oracle Mobile
Authenticator for Offline OTP Generation on Android.
36.2 Using the Oracle Mobile Authenticator App on iOS
The following sections contain procedures for using OMA on an iOS mobile device.
■Configuring the Oracle Mobile Authenticator for iOS
■Initializing the Oracle Mobile Authenticator on iOS
■Copying a One-Time Password from the Oracle Mobile Authenticator on iOS
■Editing an Account on the Oracle Mobile Authenticator on iOS
■Deleting an Account on the Oracle Mobile Authenticator on iOS
■Responding to Access Request (Push) Notifications on iOS
■Displaying Access Request (Push) Notifications History on iOS
■Displaying Service Account Details on iOS
■Displaying Access Manager Registered Accounts on iOS
■Displaying the OMA Version on iOS
36.2.1 Configuring the Oracle Mobile Authenticator for iOS
This procedure configures the OMA on iOS to communicate with Access Manager. A
configuration URL is provided by the Access Manager administrator either by e-mail
Table 36–2 Offline Configuration URL Parameters
Parameter Description
SharedSecretValue Mandatory value is the secret key
AcountName Prompts the user for input if omitted
SharedSecretEncoding Default is Base32
OTPAlgorithm Default is TOTP
Hashing Algorithm Default is SHA-1
OTPLength Default is 6
TimeStep Default is 30 sec
Using the Oracle Mobile Authenticator App on iOS
36-4 Administrator's Guide for Oracle Access Management
or through a web page. Details about the URL are in Understanding Oracle Mobile
Authenticator Configuration.
1. Tap the configuration URL provided by the Access Manager administrator.
The app will open, display a unique service name to identify this app
configuration, and prompt the user to accept the new settings.
2. Tap Accept to apply the settings.
The OMA is configured to communicate with Access Manager.
36.2.2 Initializing the Oracle Mobile Authenticator on iOS
The OMA must authenticate and register an account with Access Manager. Be sure to
complete Configuring the Oracle Mobile Authenticator for iOS before attempting these
procedures. Any of the following procedures can be used to initialize the OMA.
■Initializing the Oracle Mobile Authenticator for OTP Generation on iOS
■Adding a OTP Generation Account Manually on iOS
■Initializing Oracle Mobile Authenticator for Access Request (Push) Notifications
Using Apple Push Notifications
■Initializing Oracle Mobile Authenticator for Access Request (Push) Notifications
and OTP Generation on iOS
■Configuring Oracle Mobile Authenticator for Offline OTP Generation on iOS
36.2.2.1 Initializing the Oracle Mobile Authenticator for OTP Generation on iOS
Once authenticated, the app receives a key from the server that will be used to
generate the OTP.
1. Tap the Sign In button.
The login screen will appear.
2. Select the OTP service name for which you are configuring second factor
authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for iOS.
3. Enter your user name and password and tap Submit.
If login is successful, you will be taken to the OTP screen for the newly added
account. If login is successful but an account with the same user name for the same
service already exists, you will be asked to enter a different user name. Once the
user name is unique, you will be taken to the OTP screen.
36.2.2.2 Adding a OTP Generation Account Manually on iOS
You can manually configure a OTP account by entering a unique account name and
key. This is the same account that would be created automatically in Initializing the
Oracle Mobile Authenticator for OTP Generation on iOS.
1. Tap Enter Provided Key.
2. Enter a unique account name and key.
If the name and key are valid, you will be taken to OTP screen for your new
account. If the name is not unique or the key is not valid, you will be prompted to
enter the information again.
Using the Oracle Mobile Authenticator App on iOS
Configuring the Oracle Mobile Authenticator 36-5
36.2.2.3 Initializing Oracle Mobile Authenticator for Access Request (Push)
Notifications Using Apple Push Notifications
The OMA must have the user’s consent to receive push notifications. It must also
register successfully with the Apple Push Notification Servers and get a unique device
token. Afterwards, the OMA can register with Access Manager to receive push
notifications.
1. Tap the Sign In button.
The login screen will appear.
2. Select the Push Notification service name for which you are configuring second
factor authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for iOS.
3. Enter your user name and password and tap Submit.
If authentication and registration is successful, you will be taken to the Accounts
page which will display all the accounts that have been configured for Push
Notifications.
36.2.2.4 Initializing Oracle Mobile Authenticator for Access Request (Push)
Notifications and OTP Generation on iOS
The OMA must have the user’s consent to receive push notifications. It must also
register successfully with the Apple Push Notification Servers and get a unique device
token. Afterwards, the OMA can register with Access Manager to receive push
notifications.
1. Tap the Sign In button.
The login screen will appear.
2. Select the service name for which you are configuring second factor
authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for iOS.
3. Enter your user name and password and tap Submit.
If authentication and registration is successful, you will be taken to the OTP screen
for the newly added account. If login is successful but a OTP account with the
same user name for the same service already exists, you will be asked to enter a
different user name. Once the user name is unique you will be taken to the OTP
screen. Note that the newly added account will have small globe icon on the top
left corner signifying that this account is also configured for push notifications.
36.2.2.5 Configuring Oracle Mobile Authenticator for Offline OTP Generation on
iOS
The OMA can also be configured with a URL that contains the key used for generating
a OTP. This allows for OTP generation when the mobile app is offline. This
configuration URL contains the secret key so it should be delivered on a secure
channel.
1. Tap on the offline configuration URL.
This will open the OMA. If there are no OTP accounts configured with the same
user name defined by the URL, the account will be added and the user will be
Using the Oracle Mobile Authenticator App on iOS
36-6 Administrator's Guide for Oracle Access Management
taken to the OTP screen. If there are user name conflicts, the user will be prompted
to enter a new, unique user name.
2. Enter the displayed OTP in the corresponding login page to complete
authentication.
36.2.3 Copying a One-Time Password from the Oracle Mobile Authenticator on iOS
Use this procedure to copy a OTP from the OMA.
1. Tap on the account from which you want to copy the OTP.
The Edit, Copy and Delete icons are displayed.
2. Tap the Copy icon on the left to copy the one-time password to the clipboard.
3. Paste the one-time password in the corresponding login page to complete
authentication.
36.2.4 Editing an Account on the Oracle Mobile Authenticator on iOS
Use this procedure to edit an account on the OMA.
1. Tap on the account you want to edit.
The Edit, Copy and Delete icons are displayed.
2. Tap the Edit icon in the middle to edit an account.
A new screen in which you can edit the user name and secret key is displayed.
3. Edit the name and/or key.
4. Tap Update Account to complete the modification.
36.2.5 Deleting an Account on the Oracle Mobile Authenticator on iOS
Use this procedure to delete an account on the OMA.
1. Tap on the account you want to delete.
The Edit, Copy and Delete icons are displayed.
2. Tap the Delete icon on the right to delete an account.
You will be prompted for confirmation.
3. Tap Delete to confirm and delete.
36.2.6 Responding to Access Request (Push) Notifications on iOS
The OMA can receive push notifications from Access Manager if the push notification
option is selected when configuring two factor authentication. An administrator can
use this procedure to respond to the notifications received on the mobile device.
1. Tap the notification alert on the mobile device.
The OMA app will come to the foreground and display notification details. This
includes a user name, the resource being accessed, access time and IP address. A
timer depicting how much time you have to respond to this notification is also
displayed.
2. Tap Allow or Deny to control access to the resource.
Using the Oracle Mobile Authenticator App on Android
Configuring the Oracle Mobile Authenticator 36-7
OMA will send the resource to Access Manager and remove the notification
information screen.
36.2.7 Displaying Access Request (Push) Notifications History on iOS
You can see the notifications which were received by the OMA and the decision taken
for that particular access request.
1. Tap on three dots icon in the top left corner.
2. Tap on Notifications button.
All the notifications that have been received by Oracle Mobile Authenticator will
be shown.
3. Tap on any of the notifications to see the details.
36.2.8 Displaying Service Account Details on iOS
You can display the services with which the OMA has been configured. This
corresponds to the unique service name defined in Configuring the Oracle Mobile
Authenticator for iOS.
1. Tap the three dots icon in the top left corner.
2. Tap the Configurations button.
All the services that have been configured using this OMA will be displayed.
3. Tap a specific configuration to display the details.
A screen will be displayed that will show all the details of the selected
configuration. You can swipe from right to left to delete the configuration.
36.2.9 Displaying Access Manager Registered Accounts on iOS
You can see all the accounts that are added to the OMA and check the account type
(OTP, notification or a combination of both). This corresponds to accounts configured
using one of the procedures in Initializing the Oracle Mobile Authenticator on iOS.
1. Tap the three dots icon in the top left corner.
2. Tap the Accounts button.
All the accounts that currently exist in the OMA will be displayed. Swipe from
right to left to delete any account.
36.2.10 Displaying the OMA Version on iOS
You can display the version number of the OMA running on your mobile device.
1. Tap the three dots icon in the top left corner.
2. Tap the About button.
An alert will display the OMA version.
36.3 Using the Oracle Mobile Authenticator App on Android
The following sections contain procedures for using OMA on an Android mobile
device.
■Configuring the Oracle Mobile Authenticator for Android
Using the Oracle Mobile Authenticator App on Android
36-8 Administrator's Guide for Oracle Access Management
■Initializing the Oracle Mobile Authenticator on Android
■Copying a One-Time Password from the Oracle Mobile Authenticator on Android
■Editing an Account on the Oracle Mobile Authenticator on Android
■Deleting an Account on the Oracle Mobile Authenticator on Android
■Responding to Access Request (Push) Notifications on Android
■Displaying Access Request (Push) Notifications History on Android
■Displaying Service Account Details on Android
■Displaying Access Manager Registered Accounts on Android
■Displaying the OMA Version on Android
36.3.1 Configuring the Oracle Mobile Authenticator for Android
This procedure configures the OMA on Android to communicate with Access
Manager. A configuration URL is provided by the Access Manager administrator
either by e-mail or through a web page. Details about the URL are in Understanding
Oracle Mobile Authenticator Configuration.
1. Tap the configuration URL provided by the Access Manager administrator.
The app will open, display a unique service name to identify this app
configuration, and prompt the user to accept the new settings.
2. Tap Accept to apply the settings.
The OMA is configured to communicate with Access Manager.
36.3.2 Initializing the Oracle Mobile Authenticator on Android
The OMA must authenticate and register an account with Access Manager. Be sure to
complete Configuring the Oracle Mobile Authenticator for Android before attempting
these procedures. Any of the following procedures can be used to initialize the OMA.
■Initializing the Oracle Mobile Authenticator for OTP Generation on Android
■Adding a OTP Generation Account Manually on Android
■Initializing Oracle Mobile Authenticator for Access Request (Push) Notifications
Using Google Cloud Messaging
■Initializing Oracle Mobile Authenticator for Access Request (Push) Notifications
and OTP Generation on Android
■Configuring Oracle Mobile Authenticator for Offline OTP Generation on Android
36.3.2.1 Initializing the Oracle Mobile Authenticator for OTP Generation on Android
Once authenticated, the app receives a key from the server that will be used to
generate the OTP.
1. Tap the Sign In button.
The login screen will appear.
2. Select the service name for which you are configuring second factor
authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for Android.
Using the Oracle Mobile Authenticator App on Android
Configuring the Oracle Mobile Authenticator 36-9
3. Enter your user name and password and tap Submit.
If login is successful, you will be taken to the OTP screen for the newly added
account. If login is successful but an account with the same user name for the same
service already exists, you will be asked to enter a different user name. Once the
user name is unique, you will be taken to the OTP screen.
36.3.2.2 Adding a OTP Generation Account Manually on Android
You can manually configure a OTP account by entering a unique account name and
key. This is the same account that would be created automatically in Initializing the
Oracle Mobile Authenticator for OTP Generation on Android.
1. Tap Enter Provided Key.
2. Enter a unique account name and key.
If the name and key are valid, you will be taken to OTP screen for your new
account. If the name is not unique or the key is not valid, you will be prompted to
enter the information again.
36.3.2.3 Initializing Oracle Mobile Authenticator for Access Request (Push)
Notifications Using Google Cloud Messaging
The OMA must register successfully with the Google Cloud Messaging (Push
Notification) servers and get a unique registration token. This registration token is sent
to Access Manager to complete the push notification setup. Once complete, the OMA
can register with Access Manager to receive push notifications.
1. Tap the Sign In button.
The login screen will appear.
2. Select the service name for which you are configuring second factor
authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for Android.
3. Enter your user name and password and tap Submit.
If authentication and registration is successful, you will be taken to the Accounts
page which will display all the accounts that have been configured for Push
Notifications.
36.3.2.4 Initializing Oracle Mobile Authenticator for Access Request (Push)
Notifications and OTP Generation on Android
The OMA must register successfully with the Google Cloud Messaging (Push
Notification) Servers and get a unique registration token. This registration token is
sent to Access Manager to complete the push notification setup. Afterwards, the OMA
can register with Access Manager to receive push notifications.
1. Tap the Sign In button.
The login screen will appear.
2. Select the service name for which you are configuring second factor
authentication.
This is the unique service name defined in Configuring the Oracle Mobile
Authenticator for Android.
3. Enter your user name and password and tap Submit.
Using the Oracle Mobile Authenticator App on Android
36-10 Administrator's Guide for Oracle Access Management
If authentication and registration is successful, you will be taken to the OTP screen
for the newly added account. If login is successful but a OTP account with the
same user name for the same service already exists, you will be asked to enter a
different user name. Once the user name is unique you will be taken to the OTP
screen. Note that the newly added account will have small globe icon on the top
left corner signifying that this account is also configured for push notifications.
36.3.2.5 Configuring Oracle Mobile Authenticator for Offline OTP Generation on
Android
The OMA can also be configured with a URL that contains the key used for generating
a OTP. This allows for OTP generation when the mobile app is offline. This
configuration URL contains the secret key so it should be delivered on a secure
channel.
1. Tap on the offline configuration URL.
This will open the OMA. If there are no OTP accounts configured with the same
service name defined by the URL, the account will be added and user will be taken
to the OTP screen. If there are user name conflicts, the user will be prompted to
enter a new, unique service name.
2. Enter the displayed OTP in the corresponding login page to complete
authentication.
36.3.3 Copying a One-Time Password from the Oracle Mobile Authenticator on Android
Use this procedure to copy a OTP from the OMA.
1. Long press on the account from which you want to copy the OTP.
Three icons are displayed in the top/ action bar.
2. Tap the Copy icon on the left to copy the one-time password to the clipboard.
3. Paste the one-time password in the corresponding login page to complete
authentication.
36.3.4 Editing an Account on the Oracle Mobile Authenticator on Android
Use this procedure to edit an account on the OMA.
1. Long press on the account you want to edit.
Three icons are displayed in the top/ action bar.
2. Tap the Edit icon in the middle to edit an account.
A new screen in which you can edit the user name and secret key is displayed.
3. Edit the name and/or key.
4. Tap Save to complete the modification.
36.3.5 Deleting an Account on the Oracle Mobile Authenticator on Android
Use this procedure to delete an account on the OMA.
1. Long press on the account you want to delete.
Three icons are displayed in the top/ action bar.
2. Tap the Delete icon on the right to delete an account.
Using the Oracle Mobile Authenticator App on Android
Configuring the Oracle Mobile Authenticator 36-11
You will be prompted for confirmation.
3. Tap Delete to confirm and delete.
36.3.6 Responding to Access Request (Push) Notifications on Android
The OMA can receive push notifications from Access Manager if the push notification
option is selected when configuring two factor authentication. An administrator can
use this procedure to respond to the notifications received on the mobile device.
1. Tap the notification alert on the mobile device.
The OMA app will come to the foreground and display notification details. This
includes a user name, the resource being accessed, access time and IP address. A
timer depicting how much time you have to respond to this notification is also
displayed.
2. Tap Allow or Deny to control access to the resource.
OMA will send the resource to Access Manager and remove the notification
information screen.
36.3.7 Displaying Access Request (Push) Notifications History on Android
You can see the notifications which were received by the OMA and the decision taken
for that particular access request.
1. Tap on menu in the action bar.
2. Tap on the Notifications menu item.
All the notifications that have been received by Oracle Mobile Authenticator will
be shown.
3. Tap on any of the notifications to see the details.
36.3.8 Displaying Service Account Details on Android
You can display the services with which the OMA has been configured. This
corresponds to the unique service name defined in Configuring the Oracle Mobile
Authenticator for Android.
1. Tap on menu in the action bar.
2. Tap the Configurations menu item.
All the services that have been configured using this OMA will be displayed.
3. Tap a specific configuration to display the details.
A screen will be displayed that will show all the details of the selected
configuration. You can select each configuration to see the details. You can delete a
configuration by selecting the delete item from the menu items in the action bar.
36.3.9 Displaying Access Manager Registered Accounts on Android
You can see all the accounts that are added to the OMA and check the account type
(OTP, notification or a combination of both). This corresponds to accounts configured
using one of the procedures in Initializing the Oracle Mobile Authenticator on
Android.
1. Tap on the menu in the action bar.
Configuring the Google Authenticator App
36-12 Administrator's Guide for Oracle Access Management
2. Tap the Accounts menu item.
All the accounts that currently exist in the OMA will be displayed. You can long
press on an account to edit or delete it.
36.3.10 Displaying the OMA Version on Android
You can display the version number of the OMA running on your mobile device.
1. Tap the menu in the action bar.
2. Tap the About menu item to display the OMA version.
36.4 Configuring the Google Authenticator App
The Google Authenticator app only supports manual configuration. To initiate
configuration in the Google Authenticator app, the user creates an account for
two-factor authentication using the app. After account creation, the user manually
enters the secret key received from the resource owner. (For details on the secret key,
see Section 35.4.1, "Generating a Secret Key for the Oracle Mobile Authenticator.")
Additionally, ensure that TOTP is enabled at the bottom of the Google Authenticator
screen. Google Authenticator generates the OTP code in an offline, disconnected
mode; it does not interact with Access Manager.
36.5 Using a QR Code for Configuration
A Quick Response (QR) code can be used to configure the OMA. The OMA scans the
QR code for either online configuration or offline configuration details.
■In the case of online configuration, it gets the URL against which the user will be
authenticated and registers the OMA app for said user. After a successful
authentication and registration, the OMA gets the shared secret from the OAM
server to generate the TOTP.
■In the case of offline configuration, it is assumed that the customer develops a web
application and a user is authenticated by said application. The OMA scans the
QR code which must have the shared secret, shared secret encoding information
and optionally the OTP validity duration, the hashing algorithm to be used for
TOTP or the length of the OTP (5 digits/6 digits).
The QR code needs to be created from any of the following configuration URLs.
■oraclemobileauthenticator://settings?LoginURL::=http://OAMhost:port//ms_
oauth/resources/userprofile/secretkey
■oraclemobileauthenticator://settings?AuthServerType::=HTTPBasicAuthentication&
&LoginURL::=http://OAMhost:port/ms_
oauth/resources/userprofile/secretkey&&ServiceName::=MyBank
■oraclemobileauthenticator://settings?AuthServerType::=OAuthAuthentication&&Lo
ginURL::=http://OAMhost:port/ms_
oauth/resources/userprofile/secretkey&&ServiceName::=OAuth&&OAuthClient
ID::=8d91cb4821dd417286ca973045e9e25a&&OAMOAuthServiceEndpoint::=http:
//OAMhost:port/ms_oauth/oauth2/endpoints/oauthservice
The mobile phone user needs to go to the "Add Account" screen and select the "Scan a
barcode" option. After positioning the QR code in front of the phone’s camera, the
OMA app will update its configuration. See "Understanding Oracle Mobile
Authenticator Configuration" for additional configuration URLs.
Part IX
Part IX
Managing Oracle Access Management
Identity Federation
Part VII contains the following chapters:
■Chapter 37, "Introducing Identity Federation in Oracle Access Management"
■Chapter 38, "Managing Identity Federation Partners"
■Chapter 39, "Managing Settings for Identity Federation"
■Chapter 40, "Managing Federation Schemes and Policies"
37
Introducing Identity Federation in Oracle Access Management 37-1
37
Introducing Identity Federation in Oracle
Access Management
[27]
A federation is defined as "an association formed by merging several groups or parties".
A federated environment (as defined in the identity management realm) is one in
which organizations that provide services and identity data (business partners) have
established trust in order to share access to a set of protected resources while
protecting the same from unauthorized access. Oracle Identity Federation enables
business partners to achieve this by providing the mechanism with which companies
can form a federation and securely share services and data across their respective
security domains.
With the 11g Release 2 (11.1.2.3) of Oracle Access Management, the standalone Oracle
Identity Federation product has begun it's integration with Oracle Access Manager.
This chapter introduces the integrated Identity Federation and includes the following
sections.
■Integrating Identity Federation with Access Manager
■Deploying Identity Federation with Oracle Access Management
■Understanding How Identity Federation Works
■Using Identity Federation
■Initiating Federation SSO
■Exchanging Identity Federation Data
■Administrating Identity Federation
■Enabling Identity Federation
37.1 Integrating Identity Federation with Access Manager
The Oracle Identity Management framework supports either of the following
approaches to cross-domain single sign-on. You cannot mix-and-match these
approaches as each stands on its own.
1. Beginning with the 11g Release 2 (11.1.2), the Oracle Access Management Access
Manager server (OAM Server) has been integrated with an Oracle Access
Management Identity Federation server. All configuration for the Identity
Federation server is performed using the Oracle Access Management Console.
2. Previous, separate releases of Oracle Identity Federation (11.1.1) and Oracle Access
Manager can still be deployed to provide federation capabilities. Both servers
must be configured and managed for this integration. This approach existed in 11g
Release 1 (11.1.1) and is still available.
Deploying Identity Federation with Oracle Access Management
37-2 Administrator's Guide for Oracle Access Management
Benefits of using the new Identity Federation 11g Release 2 (11.1.2.3) server integrated
with Access Manager include:
■Eliminating the need to install and maintain separate servers.
■Simplifying post-install configuration of the federation features, particularly when
accessing those features through the Oracle Access Management Console.
■Improving the scalability of the two services working together.
■Providing enhanced diagnostics and troubleshooting.
37.2 Deploying Identity Federation with Oracle Access Management
From a functional perspective, the components in an 11g Release 2 (11.1.2.3) scenario
using the Identity Federation service (when a user attempts to log in to a protected
resource using a Web browser) include:
■The Access Manager server contains all the components needed to provide access
management services in the federated context, including:
–a credential collector
–a federation authentication plugin
–the Identity Federation engine to generate and process assertions
–a federation data cache
■Oracle WebLogic Server hosts and provides key infrastructure services, including:
–the authorization engine, which interacts with Oracle Entitlement Server
–federation data including circle of trust details and other configuration
–the Coherence map store
■Data stores, including the identity store and Coherence database, maintain the
identity data needed for authentication tasks. Identity Federation supports the
Access Manager common user store and provides multiple identity store support.
Federation data for persistent account linking can be stored in a database.
37.3 Understanding How Identity Federation Works
A federation can comprise any number of identity providers and service providers.
One common federated network topology is referred to as the hub-and-spoke model.
In this topology, there is either a single service provider accepting authentication from
multiple identity providers, or a single identity provider authenticating users for
Note: The topics in this book presume familiarity with federation
and how it works. See "Introduction to Oracle Identity Federation" in
the Oracle Fusion Middleware Administrator's Guide for Oracle Identity
Federation for background and conceptual information. This current
document is limited to describing Oracle Identity Federation
functionality as it has been integrated with Access Manager in 11g
Release 2 (11.1.2.3).
Note: Calls are routine HTTP calls.
Using Identity Federation
Introducing Identity Federation in Oracle Access Management 37-3
multiple service providers. An instance of Identity Federation in a federated network
can serve as either an identity provider, a service provider, or both.
■A service provider (SP) is a commercial or not-for-profit organization that offers a
web-based service such as a news portal, a financial repository, or retail outlet.
When configured as the SP in a federated network and a user wants to access a
resource protected by an authentication engine such as Oracle Access Manager,
Identity Federation redirects the user to an IdP for global authentication. The IdP
will obtain credentials, authenticate the user, and redirect the user back to the
Identity Federation server instance - which retrieves the asserted identity from the
IdP and redirects the authenticated user to the authentication engine which
provides access to the protected resource.
■An identity provider (IdP) is a service provider that stores identity profiles.
(Identity providers might also offer services above and beyond those related to
identity profile storage.) When configured as the IdP in a federated network and a
user wants to access a protected resource, the resource's SP directs the user to the
Identity Federation server instance - which uses the Access Manager
authentication engine to obtain credentials and authenticate the user. Following
successful authentication, the Identity Federation instance can assert the user's
identity to the resource's SP - which then authenticates the user itself and provides
access to the requested resource.
The integrated Identity Federation server can operate as an IdP or an SP. See
Chapter 38, "Managing Identity Federation Partners" for information on configuring
Identity Federation to operate in one of these provider modes and communicate with
remote partners in the federation.
37.4 Using Identity Federation
In SP-initiated SSO, the federated SSO process begins when the SP sends an
authentication request to the IdP. In IdP-initiated SSO, the IdP sends the SP an
unsolicited assertion response (in the absence of an authentication request from the
SP). Supported runtime flows in both modes include SSO, Logout (initiated from a
remote federation partner or Access Manager protected application) and Attribute
Query. The following sections have more information.
■Achieving SSO
■Logging Out
■Authorizing
■Forcing Authentication
■Indicating a Passive Identity Provider
■User and Assertion Mapping
■Platform Dependencies
Note: If the Administrator terminates a user session using the Oracle
Access Management Console, the logout is not propagated to any
remote identity providers involved in the session. This could result in
a logged-out user being automatically re-authenticated to Access
Manager through Identity Federation.
Using Identity Federation
37-4 Administrator's Guide for Oracle Access Management
37.4.1 Achieving SSO
When the Identity Federation (acting as an IdP) is performing federated SSO with an
SP, the Access Manager server authenticates the user or ensures an authenticated user
doesn't need to be challenged due to inactivity. Additionally, the Access Manager
server will check that any requested federation authentication method specified by the
SP does not require a challenge based on authentication level. The Authentication
Scheme mappings to the authentication methods will determine this. (If the SP does
not specify a Federation Authentication Method, the IdP will use the one specified for
the SP partner in the defaultschemeid property.) See Initiating Federation SSO for
details.
37.4.2 Logging Out
With Identity Federation, a logout operation is dissociated from the authentication
operation. Logout can be initiated by user the (Access Manager server) or a partner in
the federation.
■When initiated by the user accessing the Access Manager Logout service, Access
Manager kills the user's Access Manager session and displays a logout page that
will instruct the various WebGate agents to remove the user cookies. Access
Manager then redirects the user to the Identity Federation Logout service which
notifies each partner involved in this session by either redirecting the user with a
Logout Request message via HTTP Redirect or HTTP POST or by directly sending
a Logout Request message via SOAP. Identity Federation then kills the OIF session
and redirects the user to the defined return URL.
■When initiated by the user on a web site from a partner in the federation, the
partner redirects the user to the Identity Federation server which marks the user
session as logging out. Identity Federation then redirects the user to the Access
Manager server which kills the user's Access Manager session. Access Manager
then displays a logout page that will instruct the various WebGate agents to
remove the user cookies, and redirects the user back to Identity Federation to
resume the Federation logout process by notifying each partner involved in this
session (except the one who first redirected the user) by either redirecting the user
with a Logout Request message via HTTP Redirect or HTTP POST or by directly
sending a Logout Request message via SOAP. Identity Federation then kills the
OIF session and redirects the user with a Logout Response message to the partner
who first redirected the user to the Identity Federation server.
37.4.3 Authorizing
When the Identity Federation server acts as an IdP, it has the need to issue an Identity
Token to the SP during the Federation SSO operation. The Identity Token will contain
user information as well as session information. By default, the authorization feature is
turned off. It can be enabled or disabled using the
configureFedSSOAuthz
WLST
command. You also need to create a resource of type TokenServiceRP (with the
Resource URL set to the SP Partner ID) and a Token Issuance Policy to which the
Resource is added. The Token Issuance Policy indicates the conditions under which
the token should be issued.
37.4.4 Forcing Authentication
SAML 2.0 and OpenID 2.0 provide a way for a SP to indicate during Federation SSO
whether the user should be challenged by the IdP, even if a valid user session already
exists. In this case, the SP will send an authentication request with a parameter
indicating that the IdP should re-challenge the user or force authentication.
Initiating Federation SSO
Introducing Identity Federation in Oracle Access Management 37-5
37.4.5 Indicating a Passive Identity Provider
SAML 2.0 and OpenID 2.0 provide a way for the SP to indicate during Federation SSO
whether the Identity Provider should interact with the user. In this case, the SP will
send an authentication request with a parameter indicating that the IdP should not
interact with the user or is passive. The IdP recognizes the parameter and returns to
the SP:
■An error if the IdP must interact with the user but cannot because of this
parameter.
■A Federation Assertion that indicates whether the user has a valid session.
37.4.6 User and Assertion Mapping
In Identity Federation, after a SP validates the SAML assertion created by it's IdP
partner, it can map the assertion to the local user in one of the following ways.
■By mapping the SAML subject to a user record with a user attribute (for example,
mail
).
■By mapping a SAML Assertion Attribute to a user record with a user attribute (for
example, the SAML Assertion Attribute
emailAddress
mapped to
mail
).
■By mapping one or more attributes contained in the SAML assertion's
AttributeStatement
element or the SAML subject with an LDAP query. You must
configure both the SAML attribute name and the user attribute to which it is
mapped.
37.4.7 Platform Dependencies
This architecture leverages the Oracle Fusion Middleware platform for the Credential
Store Framework (CSF). CSF securely stores keystore passwords as well as server
credentials such as HTTP Basic Authentication usernames and passwords.
37.5 Initiating Federation SSO
The following sections contain details about initiating the Federation SSO process.
■IdP Initiated Federation SSO Service
■SP Initiated Federation SSO Service
37.5.1 IdP Initiated Federation SSO Service
When Identity Federation is working as an IdP, the URL for initiating Federation SSO
is:
http://public-oam-host:public-oam-port/oamfed/idp/initiatesso
The query parameters are:
■providerid: name of the SP partner with which to perform Federation SSO or the
issuer ID / provider ID of the SP partner with which to perform Federation SSO.
(required)
■returnurl: the SP URL where the user will be redirected after a successful
Federation SSO (optional)
Exchanging Identity Federation Data
37-6 Administrator's Guide for Oracle Access Management
■acsurl: the SAML 2.0 Assertion Consumer Service URL where Identity Federation
will redirect the user with the SAML 2.0 Assertion. This URL must be declared in
the SP SAML 2.0 Metadata. (optional)
37.5.2 SP Initiated Federation SSO Service
When Identity Federation is working as an SP, the URL for initiating Federation SSO
is:
http://public-oam-host:public-oam-port/oamfed/sp/initiatesso
The query parameters are:
■providerid: name of the IdP partner with which to perform Federation SSO or the
issuer ID / provider ID of the IdP partner with which to perform Federation SSO.
(required)
■returnurl: the URL where the user will be redirected after a successful Federation
SSO (optional)
37.6 Exchanging Identity Federation Data
The integrated Identity Federation server supports the transport and receipt of request
and response messages using either the Security Access Markup Language (SAML) 2.0
specifications, SAML 1.1, OpenID 2.0 or WS-Federation 1.1. The following sections
contain more information.
■Using SAML 2.0
■Using SAML 1.1
■Using OpenID 2.0
■Using WS-Federation 1.1
37.6.1 Using SAML 2.0
SAML uses an eXtensible Markup Language (XML) framework to define a simple
request-response protocol in order to achieve interoperability between vendor
platforms that provide SAML assertions. A SAML requester sends a SAML Request
element to a responder. Similarly, a SAML responder returns a SAML Response
element to the requester.
Within the SAML 2.0 protocol, Identity Federation supports the functionality
described in the following sections.
■SAML 2.0 Bindings for SSO and Federation
■SAML 2.0 Bindings for Single Logout
■SAML 2.0 NameID Formats
■Securing SAML 2.0 Data
■SAML 2.0 Service Details
Note: The specification describing how SAML might be used in a
given context is referred to as a SAML profile. The specification
describing how a SAML assertion and/or message is conveyed in, or
transported over, another protocol is referred to as a SAML Binding.
Exchanging Identity Federation Data
Introducing Identity Federation in Oracle Access Management 37-7
37.6.1.1 SAML 2.0 Bindings for SSO and Federation
SSO and Federation relies on SAML artifacts and assertions to relay authentication
information. The following bindings are supported for the exchange of data regarding
SSO and federation.
■The HTTP Artifact Binding uses the Artifact Resolution Protocol and the SAML
SOAP Binding (over HTTP) to resolve a SAML message by reference. The IdP will
store the Assertion in its repository and redirect the user to the SP with a string
(artifact) that references the stored Assertion. The SP will retrieve the Assertion by
connecting to the IdP directly over SOAP/HTTP and presenting the artifact
■The HTTP POST Binding relies on an HTML form to communicate authentication
information between providers. For example, the service provider may use HTTP
Redirect to send a request while the identity provider uses HTTP POST to transmit
the response. The IdP can also redirect the user to the SP in an HTML FORM that
contains the Assertion itself.
■The Reverse SOAP binding (PAOS) is only supported when Access Manager is
configured as an IdP. In this flow, the client sends a SOAP request containing a
SAML 2.0 Authn Request message to the IdP. The IdP authenticates the user
locally, and returns a SOAP response containing a SAML 2.0 Assertion. The client
then presents the results to the remote SP.
37.6.1.2 SAML 2.0 Bindings for Single Logout
Single Logout defines how providers notify each other of logout events. This message
exchange terminates all sessions when a logout occurs at the SP or IdP. The following
profiles are supported for exchanging data regarding single logout.
■The HTTP Redirect profile relies on HTTP redirects between providers. For
example, the IdP redirects the user to the SP using a 302 redirect operation with
the URL containing the Logout Request/Response message. This profile can be
used for sending and receiving data regarding single logout.
■The HTTP POST profile occurs when the IdP redirects the user to the SP using an
HTML FORM containing the Logout Request/Response message. This profile can
be used for sending and receiving data regarding single logout.
■The SOAP Binding Profile allows the IdP to connect directly with the SP and send
a Logout Request message. During logout, the IdP redirects the user to the various
SPs in a sequential manner. The SP will respond with a Logout Response message.
This profile relies on asynchronous SOAP over HTTP messaging calls between
providers and can be used only for sending data regarding single logout.
37.6.1.3 SAML 2.0 NameID Formats
The Name Identifier Mapping defines how an SP can obtain name identifiers assigned
to a principal that has authenticated in the name space of a different SP. When a
principal authenticated to one SP requests access to a second site, the second SP can
use this protocol to obtain the name identifier and communicate with the first SP about
the principal - even though no federation for the principal exists between them. The
SAML 2.0 NameID formats listed in Table 37–1 are supported in both IdP and SP
mode.
Table 37–1 Supported SAML 2.0 NameID Formats
NameID Format Description
urn:oasis:names:tc:SAML:1.1:nameid-format:
unspecified
SP/IdP will use the applicable user attribute to
populate/process the NameID value
Exchanging Identity Federation Data
37-8 Administrator's Guide for Oracle Access Management
37.6.1.4 Securing SAML 2.0 Data
Regarding the security of identity data transported using the SAML 2.0
specifications,the following is true.
■All outgoing Assertions will be signed.
■All outgoing responses containing Assertions will not be signed.
■All outgoing requests/responses not containing Assertions will be signed.
■The signing certificate will not be included in the messages.
■Identity Federation (acting as the IdP) will not require signatures on any messages
except when specified in the SP Partner metadata.
■NameIDs, attributes and Assertions will not be encrypted.
■Information on the default XML Encryption algorithm is located at
http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/Overview.html#aes12
8-cbc
■The hashing algorithm for signatures is SHA-1 by default. Identity Federation can
be configured to use SHA-256.
37.6.1.5 SAML 2.0 Service Details
The SAML 2.0 Metadata for the IdP and SP is contained in a single XML document
and can be retrieved using either the Oracle Access Management Console or by
accessing either of the following URLs:
http://public-oam-host:public-oam-port/oamfed/idp/metadata
http://public-oam-host:public-oam-port/oamfed/sp/metadata
urn:oasis:names:tc:SAML:1.1:nameid-format:
emailAddress
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format:
X509SubjectName
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format:
WindowsDomainQualifiedName
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format:
kerberos
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format:
persistent
SP/IdP will use either:
■A user attribute to populate the NameID
value
■A user attribute (such as DN) to set the
value (same for every operations)
■A random value and will store that value
in the Federation Data Store (only this
mode will require the use of a Federation
Data Store)
urn:oasis:names:tc:SAML:2.0:nameid-format:
transient
IdP will generate a random value
custom value When this NameID format is used, OIF/IdP will
use a user attribute to populate the NameID
value
Table 37–1 (Cont.) Supported SAML 2.0 NameID Formats
NameID Format Description
Exchanging Identity Federation Data
Introducing Identity Federation in Oracle Access Management 37-9
The certificates used for signature and encryption operations are published via the
SAML 2.0 Metadata. The certificates can be retrieved by using a Service URL that
specifies the Key ID of the key/certificate entry as defined in the Keystore Settings.
(See Section 39.5, "Defining Keystore Settings for Federation.") For example,
http://public-oam-host:public-oam-port/oamfed/idp/cert?id=osts_signing
The Provider ID and the Issuer ID of the IdP and SP profiles are identical and can be
retrieved from the applicable Provider Partner profile using the Oracle Access
Management Console.
Table 37–2 documents the SAML 2.0 URLs for use when Identity Federation is
configured to act as an IdP.
Table 37–3 documents the SAML 2.0 URLs for use when Identity Federation is
configured to act as an SP.
37.6.2 Using SAML 1.1
Although the standards address the same use case, SAML 2.0 and SAML 1.1 get there
in different ways. The most important type of SAML 1.1 request is a query. A SP
makes a query directly to an IdP over a secure back channel (using SOAP). Within the
SAML 1.1 protocol, Identity Federation supports the features described in the
following sections.
Table 37–2 SAML 2.0 URLs for Identity Federation Acting As Identity Provider
Description URL
Single Sign On Service URL
for HTTP Redirect binding
http://public-oam-host:public-oam-port/oamfed/idp/samlv20
Single Sign On Service URL
for HTTP POST binding
http://public-oam-host:public-oam-port/oamfed/idp/samlv20
Single Sign On Service URL
for SOAP binding
http://public-oam-host:public-oam-port/oamfed/idp/soap
Artifact Resolution Service
URL for SOAP binding
http://public-oam-host:public-oam-port/oamfed/idp/soap
Single Logout Service URL
for HTTP Redirect binding
http://public-oam-host:public-oam-port/oamfed/idp/samlv20
Single Logout Service URL
for HTTP POST binding
http://public-oam-host:public-oam-port/oamfed/idp/samlv20
Attribute Authority Service
URL for SOAP binding
http://public-oam-host:public-oam-port/oamfed/aa/soap
Table 37–3 SAML 2.0 URLs for Identity Federation Acting as Service Provider
Description URL
Assertion Consumer Service
URL for Artifact binding
http://public-oam-host:public-oam-port/oam/server/fed/sp/s
so
Assertion Consumer Service
URL for HTTP POST
binding
http://public-oam-host:public-oam-port/oam/server/fed/sp/s
so
Single Logout Service URL
for HTTP Redirect binding
http://public-oam-host:public-oam-port/oamfed/sp/samlv20
Single Logout Service URL
for HTTP POST binding
http://public-oam-host:public-oam-port/oamfed/sp/samlv20
Exchanging Identity Federation Data
37-10 Administrator's Guide for Oracle Access Management
■SAML 1.1 Profiles for Web Browser SSO
■SAML 1.1 Logout Profile
■SAML 1.1 NameID Formats
■Securing SAML 1.1 Data
■SAML 1.1 Service Details
37.6.2.1 SAML 1.1 Profiles for Web Browser SSO
SAML 1.1 profiles rely on pushing SAML artifacts and assertions to an SP to relay
authentication information. The following profiles are supported.
■The Browser/Artifact Profile passes a SAML assertion from the IdP to the SP by
reference (through the browser using HTTP Redirect). This artifact is subsequently
dereferenced through a back-channel exchange in which the SP retrieves the
assertion from the IdP using SAML over SOAP over HTTP.
■The Browser/POST Profile passes an SSO assertion to an SP through the browser
using HTTP POST. We say that the identity provider "pushes" the assertion to the
service provider.
37.6.2.2 SAML 1.1 Logout Profile
The SAML 1.1 specifications do not define a logout profile thus Identity Federation is
not able to notify remote partners regarding a user logging out.
37.6.2.3 SAML 1.1 NameID Formats
When a principal authenticated to one SP requests access to a second site, the second
SP can obtain the name identifier and communicate with the first SP regarding the
principal - even though no federation for the principal exists between them. The
SAML 1.1 NameID formats listed in Table 37–4 are supported in both IdP and SP
mode.
37.6.2.4 Securing SAML 1.1 Data
Regarding the security of identity data transported using the SAML 1.1
specifications,the following is true.
■All outgoing Assertions will be signed.
Table 37–4 Supported SAML 1.1 NameID Formats
NameID Format Description
urn:oasis:names:tc:SAML:1.1:nameid-format:
unspecified
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format:
emailAddress
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format:
X509SubjectName
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format:
WindowsDomainQualifiedName
SP/IdP will use the applicable user attribute to
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format:
kerberos
SP/IdP will use the applicable user attribute to
populate/process the NameID value
custom value When this NameID format is used, OIF/IdP will
use a user attribute to populate the NameID
value
Exchanging Identity Federation Data
Introducing Identity Federation in Oracle Access Management 37-11
■All outgoing responses containing Assertions will not be signed.
■The signing certificate will not be included in the messages.
■Identity Federation (acting as the IdP) will not require signatures on any messages.
■The hashing algorithm for signatures is SHA-1 by default. Identity Federation can
be configured to use SHA-256.
37.6.2.5 SAML 1.1 Service Details
The certificates used for signature and encryption operations can be retrieved by using
a Service URL that specifies the Key ID of the key/certificate entry as defined in the
Keystore Settings. (See Section 39.5, "Defining Keystore Settings for Federation.") For
example,
http://public-oam-host:public-oam-port/oamfed/idp/cert?id=osts_signing
The Provider ID and the Issuer ID of the IdP and SP profiles are identical and can be
retrieved from the applicable Provider Partner profile using the Oracle Access
Management Console.
Table 37–5 documents the SAML 1.1 URLs for use when Identity Federation is
configured to act as an IdP.
Table 37–6 documents the SAML 1.1 URL for use when Identity Federation is
configured to act as an SP.
37.6.3 Using OpenID 2.0
OpenID 2.0 allows users to create accounts with a preferred OpenID IdP and use the
account as the basis for signing on to any website that accepts OpenID authentication.
Identity data is communicated through the exchange of an OpenID identifier (a URL
or XRI chosen by the end-user) and the IdP provides OpenID authentication. Within
the OpenID protocol, Identity Federation supports the functionality described in the
following sections.
■OpenID 2.0 Authentication/SSO
■OpenID 2.0 Logout
■OpenID 2.0 NameID Format
■Securing OpenID 2.0 Data
■Using OpenID 2.0 Extensions
Table 37–5 SAML 1.1 URLs for Identity Federation Acting As Identity Provider
Description URL
Single Sign On Service
URL
http://public-oam-host:public-oam-port/oamfed/idp/samlv11sso
Artifact Resolution
Service URL
http://public-oam-host:public-oam-port/oamfed/idp/soapv11
Table 37–6 SAML 1.1 URL for Identity Federation Acting as Service Provider
Description URL
Assertion Consumer
Service URL
http://public-oam-host:public-oam-port/oam/server/fed/sp/sso
Exchanging Identity Federation Data
37-12 Administrator's Guide for Oracle Access Management
■OpenID 2.0 Service Details
37.6.3.1 OpenID 2.0 Authentication/SSO
OpenID 2.0 allows a user to sign into a new web site using a special OpenID URL. For
example, if you have a blog at myblog.com, you might have created the OpenID URL,
yourname.myblog.com. Then if you navigate to a second web site that accepts OpenID
logins and click on the OpenID button, you can type in the URL and click to log in.
The second SP discovers the OpenID IdP URL with this OpenID identifier. When the
OpenID IdP redirects the authenticated user to the SP, it includes the OpenID
Assertion which contains the result of the operation, the NameID of the user and
(optional) attributes.
37.6.3.2 OpenID 2.0 Logout
The OpenID 2.0 specifications do not define a logout profile thus Identity Federation is
not able to notify remote partners regarding a user logging out.
37.6.3.3 OpenID 2.0 NameID Format
OpenID defines the NameID as being a random string thus Identity Federation will
use one of the following as the value for the NameID.
■A hashed user attribute (such as DN)
■A generated, random value that will be stored in the Federation Data Store; this
mode requires the use of a Federation Data Store
37.6.3.4 Securing OpenID 2.0 Data
Regarding the security of identity data transported using the OpenID 2.0
specifications,the following is true.
■All outgoing Assertions will be signed.
■The default Association Algorithm is HMAC SHA-1.
■The default Session Agreement Algorithm is Diffie-Hellmann SHA-1.
37.6.3.5 Using OpenID 2.0 Extensions
OpenID is an extensible specification. The following extensions are available when
using the integrated Identity Federation.
■Attribute Exchange (AX): If enabled, a SP can request attributes to be included in
the OpenID Assertion response. The IdP can include the requested attributes or
attributes configured to be in the response. (Default: enabled)
■Provider Authentication Policy Extension (PAPE): If enabled, advanced
authentication methods can be defined and specified. This might include, for
example, a phishing-resistant authentication method or multi-factor
authentication. (Default: disabled)
■GSA Level 1: identifier in the OpenID Assertion indicating if this server is
compliant with the
http://www.idmanagement.gov/schema/2009/05/icam/openid-trust-level1.pdf
policy. If enabled and if PAPE is enabled, OIF will include this policy in the
OpenID response (Default: disabled)
■Level Of Assurance (LOA): identifier in the OpenID Assertion indicating if this
server is compliant with the
http://csrc.nist.gov/publications/nistpubs/800-63/SP800-63V1_0_2.pdf policy. If
Exchanging Identity Federation Data
Introducing Identity Federation in Oracle Access Management 37-13
enabled, OIF/IdP will use the mapping between Level of Assurance and
schemeID to determine the value to use for LOA in the OpenID response (see 2.5.2
for more information) (Default: disabled)
■No Private Identifier Information (NoPII): identifier in the OpenID Assertion
indicating if this server is compliant with the
http://www.idmanagement.gov/schema/2009/05/icam/no-pii.pdf policy. Note,
if enabled, OIF will not include attributes in the OpenID Assertion
■Persistent Personal Identifier (PPID): identifier in the OpenID Assertion indicating
if this server is compliant with the
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidenti
fier policy. If enabled and if PAPE is enabled, OIF will include this policy in the
OpenID response (Default: disabled)
■Registration (SReg): extension for attributes in the OpenID Assertion. If enabled,
the SP can request attributes to be included in the response, and the IdP can
include requested attributes or attributes configured to be in the response (Default:
disabled)
■UI Extension (UIExt): extension for UI. In OIF/IdP, support for this extension is
limited to advertisement in the XRDS metadata (Default: disabled)
37.6.3.6 OpenID 2.0 Service Details
The following URL is the realm of the OpenID 2.0 SP component.
http://public-oam-host:public-oam-port
Table 37–7 documents the OpenID 2.0 URLs for use when Identity Federation is
configured to act as an IdP.
Table 37–8 documents the OpenID 2.0 URLs for use when Identity Federation is
configured to act as an SP.
37.6.4 Using WS-Federation 1.1
Access Manager now supports features of the WS-Federation 1.1 protocol.
WS-Federation 1.1 partners can be created using the new
addWSFed11IdPFederationPartner
and
addWSFed11SPFederationPartner
WLST
commands. After creating the partners, the profiles can be configured using the
existing WLST Identity Federation commands. For details, see the Oracle Fusion
Table 37–7 OpenID 2.0 URLs for Identity Federation Acting As Identity Provider
Description URL
Single Sign On Service
URL
http://public-oam-host:public-oam-port/oamfed/idp/openidv20
Discovery Service URL http://public-oam-host:public-oam-port/oamfed/idp/openidv20
Table 37–8 OpenID 2.0 URLs for Identity Federation Acting as Service Provider
Description URL
Single Sign On Service
URL
http://public-oam-host:public-oam-port/oam/server/fed/sp/sso
Discovery Service URL http://public-oam-host:public-oam-port/oamfed/sp/openidv20
Realm URL http://public-oam-host:public-oam-port
Administrating Identity Federation
37-14 Administrator's Guide for Oracle Access Management
Middleware WebLogic Scripting Tool Command Reference for Identity and Access
Management.
37.7 Administrating Identity Federation
Identity Federation integrated with Access Manager can be administered with a
combination of configurations using the Oracle Access Management Console and
Oracle WebLogic Scripting Tool (WLST) commands. Use the Oracle Access
Management Console to enable the Identity Federation service, manage IdP and SP
partner profiles, and work with federated authentication schemes and policies. Use the
WLST utilities to manage additional server and partner configuration properties.
The Oracle Access Management Console enables Administrators to manage
configuration related to the federation service and partners. Table 37–9 summarizes
the types of information that you can configure for Identity Federation using Oracle
Access Management Console.
Table 37–10 outlines the tasks required to implement identity federation using the
Oracle Access Management Console.
Note: Partial administration of the WS-Federation 1.1 partners is
available using the Oracle Access Management Console.
Note: Not all WLST command functionality is duplicated in the
Oracle Access Management Console and not all console functionality
is duplicated on the command line.
Table 37–9 Configuring Identity Federation Settings
Configuring ... Description
Federation Administrators Administrators who can manage federated partners and related
configuration.
Federation Service Enable and disable the Identity Federation service in Access Manager. See
"Enabling Identity Federation" on page 37-15.
Federation Settings Manage basic Identity Federation service configuration properties. See
Chapter 39, "Managing Settings for Identity Federation".
Providers for Federation IdP partners are managed within the context of administering Identity
Federation as a SP. Conversely, SP partners are managed within the context
of administering Identity Federation as an IdP. See Section 38.3,
"Administering Identity Federation As A Service Provider" or Section 38.4,
"Administering Identity Federation As An Identity Provider.".
Authentication Schemes and
Modules for Federation
Manage federation authentication schemes. See "Using Authentication
Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)" on
page 40-2.
Policies for Use with
Federation
Manage policies for use with federation partners. See "Managing Access
Manager Policies for Use with Identity Federation" on page 40-9.
Table 37–10 Implementing Identity Federation
Task Reference
Enable the Identity Federation service. Section 37.8
Configure federation settings. Section 39.3
Identity IdP and/or SP partners, and configure attributes for them. Section 38.3
Enabling Identity Federation
Introducing Identity Federation in Oracle Access Management 37-15
37.8 Enabling Identity Federation
Identity Federation is an authentication module in Oracle Access Management so both
the Access Manager service and Identity Federation must be enabled. Figure 37–1
illustrates the Available Services page in Oracle Access Management Console with the
Access Manager service and Identity Federation aleady enabled. Use this page to
enable (or disable) Identity Federation together with the Access Manager service.
Figure 37–1 Available Services Page
Configure an authentication or authorization policy. Chapter 40
Protect a resource with this policy. Chapter 25
Note: Once enabled, it is possible to enable or disable specific
Federation features such as IdP, SP, Attribute Authority and/or
Attribute Requester. Use the
configureFederationService()
WLST
command as documented in Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
Table 37–10 (Cont.) Implementing Identity Federation
Task Reference
Enabling Identity Federation
37-16 Administrator's Guide for Oracle Access Management
To enable the Identity Federation service with Access Manager
1. Log in to the Oracle Access Management Console.
https://hostname:port/oamconsole/
2. From the Welcome page, under Configuration, click Available Services.
3. Enable Identity Federation: Click Enable beside Identity Federation (or confirm
that the green Status check mark displays).
A Confirmation window is displayed.
4. Click OK.
5. Enable Access Manager: Click Enable beside Access Manager (or confirm that the
green Status check mark displays).
A Confirmation window is displayed.
6. Click OK.
38
Managing Identity Federation Partners 38-1
38
Managing Identity Federation Partners
This chapter introduces the concept of federation partners (service providers and
identity providers) in Oracle Access Management Identity Federation. This chapter
includes the following sections:
■Understanding Federation And Partners
■Managing Federation Partners
■Administering Identity Federation As A Service Provider
■Administering Identity Federation As An Identity Provider
■Using Attribute Mapping Profiles
■Mapping Federation Authentication Methods to Access Manager Authentication
Schemes
■Using the Attribute Sharing Plug-in for the Attribute Query Service
■Using the Federation Proxy
■Using WLST for Identity Federation Administration
38.1 Understanding Federation And Partners
The topics in this chapter assume some familiarity with the federation and partner
concepts described in the Oracle Fusion Middleware Administrator's Guide for Oracle
Identity Federation. The current chapter also assumes that you have performed
Section 37.8, "Enabling Identity Federation" as described.
The integrated Identity Federation server supports the transport and receipt of request
and response messages using either the Security Access Markup Language (SAML) 2.0
specifications, SAML 1.1, OpenID 2.0 or WS-Federation 1.1. Thus, Identity Provider
(IdP) and Service Provider (SP) partners can be created with any of these protocols
defined. SAML and OpenID partners can be defined using the Oracle Access
Management Console as described in Creating Remote Identity Provider Partners and
Creating Remote Service Provider Partners. WS-Federation partners can be created
using WLST commands as described in the Oracle Fusion Middleware WebLogic Scripting
Tool Command Reference for Identity and Access Management.
38.2 Managing Federation Partners
This 11g Release 2 (11.1.2.2) of the integrated Identity Federation provides the ability to
be configured as a Service Provider (SP) or an Identity Provider (IdP). Following this
provider definition, remote providers (whether service or identity) partnered in
Administering Identity Federation As A Service Provider
38-2 Administrator's Guide for Oracle Access Management
Federation SSO need to be managed as well. Towards this end, Identity Federation
developed the configuration hierarchy concepts of a partner and a partner profile.
■A partner profile refers to settings specific to a partner type (IdP or SP) or a protocol
version (SAML 2.0, SAML 1.1, OpenID 2.0). It is a configuration group that
represents a sets of common properties that apply to all partners that reference it.
It contains mostly secondary configuration objects such as Authentication Method
mappings, cryptographic settings (SHA-1 vs SHA-256) and the like.
■A partner refers to the configuration for a specific organization partnered in the
Federation SSO process. Each partner is associated with a partner profile. The
partnerprofileid
property in a Partner entry defines the partner profile to which
this partner is assigned. If the
partnerprofileid
property is not defined, the
default Partner Profile for the Partner (based on the Partner type and the Partner
protocol) will be used.
All Partners associated with the same Partner Profile will share its defined settings
unless they are specifically overridden for a partner at the Partner configuration level.
A Partner configuration overrides a Partner Profile configuration which, in turn,
overrides a global configuration.
Partner profiles are only manageable using WLST commands. Each new partner
created will be bound to one of the default partner profiles listed in Table 38–1. To
assign a new partner profile to a partner, use the
setFedPartnerProfile()
WLST
command after creating the partner. See Section 38.9, "Using WLST for Identity
Federation Administration" for details.
38.3 Administering Identity Federation As A Service Provider
When the integrated Identity Federation is configured as an SP, you must define any
remote IdP partners as trusted by creating and managing profiles that contain details
regarding each remote IdP. To begin administration of the integrated Identity
Federation server as an SP, click the Service Provider Administration link under
Identity Federation from the Launch Pad in the Oracle Access Management Console.
This section provides the following topics.
■Creating Remote Identity Provider Partners
■Managing the Remote Identity Provider Partners
38.3.1 Creating Remote Identity Provider Partners
Use the New Identity Provider Page to define an identity provider (IdP) partner record
for Access Manager. You can specify service details manually or load them from a
metadata file.
Table 38–1 Default Partner Profiles
Default Partner Profile Description
saml20-idp-partner-profile SAML 2.0 Partner Profile for IdP partners
saml20-sp-partner-profile SAML 2.0 Partner Profile for SP partners
saml11-idp-partner-profile SAML 1.1 Partner Profile for IdP partners
saml11-sp-partner-profile SAML 1.1 Partner Profile for SP partners
openid20-idp-partner-profile OpenID 2.0 Partner Profile for IdP partners
openid20-sp-partner-profile OpenID 2.0 Partner Profile for SP partners
Administering Identity Federation As A Service Provider
Managing Identity Federation Partners 38-3
Figure 38–1 shows the Create Identity Provider Partner page when service details are
configured by loading an XML metadata file.
Figure 38–1 New Identity Provider Page, Service Details Loaded from Metadata
Figure 38–2 shows the Create Identity Provider Partner page when service details are
configured by entering values manually.
Administering Identity Federation As A Service Provider
38-4 Administrator's Guide for Oracle Access Management
Figure 38–2 New Identity Provider Page, Service Details entered Manually
Table 38–2 describes each element on the New Identity Provider page.
Table 38–2 Identity Provider Partner Settings
Element Description
Name This is the provider name.
Description This is a brief description of the provider. (Optional).
Protocol This is the provider protocol (SAML 1.1, SAML 2.0 and so on).
Service Details This drop-down enables you to choose whether to enter service details
manually or load from metadata.
Metadata File This field appears if loading metadata from a file. Click Browse to
select a file to use. Applies to SAML 2.0 only.
Issuer ID This is the issuer ID of the provider. Applies to SAML 2.0 and SAML
1.1 only.
Administering Identity Federation As A Service Provider
Managing Identity Federation Partners 38-5
Succinct ID This is the succinct ID of the provider. This element is required if using
the artifact profile. Applies to SAML 2.0 and SAML 1.1 only.
SSO Service URL This is the URL address to which SSO requests are sent.
SOAP Service URL This is the URL address to which a SOAP service request is sent. This
element is required if using artifact profile.
Logout Request Service URL This is the URL address to which a logout request is sent by the
provider. This element is required if using the logout feature. Applies
to SAML 2.0 only.
Logout Response Service URL This is the URL address to which a logout response is sent. This
element is required if using the logout feature. Applies to SAML 2.0
only.
Signing Certificate This is the signing certificate used by the provider. You can specify it in
pem
and
der
formats. Applies to SAML 2.0 and SAML 1.1 only.
User Identity Store This is the identity store in which the IdP's users will be located and
mapped. Identity Federation supports multiple identity stores, defined
on a per-partner basis. Optionally, if no user identity store is selected,
the default Access Manager store is used.
User Search Base DN This is the base search DN used when looking up user records.
(Optional.) If omitted, the default user search base DN configured for
the selected user identity store is used.)
Mapping Option This setting indicates how an incoming assertion is mapped to a user
in the identity store. Select one of the following:
■Map Assertion Name ID to User ID Store Attribute
Enter the identity store attribute to which the assertion NameID
will be mapped.
■Map Assertion Attribute to User ID Store Attribute
Enter assertion attribute and the identity store attribute to which
it will be mapped.
■Map Assertion to User Record Using LDAP Query
Enter an LDAP query with placeholders for incoming data. You
may use:
- an attribute from the SAML assertion's
AttributeStatement
element, referenced by its name prefixed and suffixed with the
%
character
- the SAML assertion subject's
NameID
, referenced by
%fed.nameidvalue%
- the identity provider's partner name, referenced by
%fed.partner%.
For example, an LDAP query to map an incoming assertion based
on two assertion attributes (lastname and email) would be
(&(sn=%lastname%)(mail=%email%)).
Enable Basic HTTP
Authentication
Check this box to accept HTTP basic credentials. (Advanced element,
available only in provider Edit mode.)
Attribute Mapping Profile Indicates the attribute profile to which the partner is bound.
Service Details Indicates which of the following options Identity Federation (the RP)
uses to perform Federation SSO with the IdP. Applies to OpenID 2.0
only.
■By discovering the IdP SSO URLs via the IdP XRDS metadata
available at the Discovery Service URL.
■By using the specified static OpenID login endpoint which is the
IDP SSO service URL.
Discovery URL Defines the location where the IdP publishes its XRDS metadata.
Applies to OpenID 2.0 only.
Endpoint URL Defines the IdP SSO Service location. Applies to OpenID 2.0 only.
Table 38–2 (Cont.) Identity Provider Partner Settings
Element Description
Administering Identity Federation As A Service Provider
38-6 Administrator's Guide for Oracle Access Management
To Define SAML 2.0 Identity Providers for Federation
Take these steps to define a new SAML 2.0 identity provider (IdP):
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Identity Provider Partner from the Create
(+) drop-down list in the Federation section.
3. In the Service Details field, select Load from provider metadata. (SAML 2.0 is
typically configured with metadata.)
4. A new field named Metadata File appears. Click Browse.
5. Select the metadata file of interest.
6. The metadata is loaded from the file.
7. Click Save to create the Identity Provider definition.
To Define SAML 1.1 Identity Providers for Federation
Take these steps to create a new SAML 1.1 identity provider (IdP):
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Identity Provider Partner from the Create
(+) drop-down list in the Federation section.
3. In the Service Details field, select Enter Manually.
4. Fill in the New Identity Provider page using values for your environment
(Table 38–2). The information you provide depends on the protocol chosen for the
provider and other factors.
5. Click Save to create the identity provider definition.
Enable Global Logout Indicates whether or not Identity Federation should notify the remote
partner when the user is signing off during the logout flow. Applies to
SAML 2.0 only.
HTTP POST SSO Response
Binding
Indicates whether the SAML Assertion should be sent back from the
IdP using the HTTP POST Binding or the Artifact Binding. Applies to
SAML 2.0 only.
Authentication Request NameID
Format
Indicates the NameID format that Identity Federation will request
from the IdP during the Federation SSO operation. If none is selected,
a NameID format is not specified in the request. Applies to SAML 2.0
only.
Note: For IdP functionality, use the 11g Release 1 (11.1.1) Oracle
Identity Federation server. For details, see Oracle Fusion Middleware
Administrator's Guide for Oracle Identity Federation.
Table 38–2 (Cont.) Identity Provider Partner Settings
Element Description
Administering Identity Federation As A Service Provider
Managing Identity Federation Partners 38-7
To Define OpenID 2.0 Identity Providers for Federation
In 11g Release 2 (11.1.2.3) the Identity Federation supports OpenID, and acts as an
OpenID RP/SP. OpenID Providers can be registered as IdP partners. Authentication
schemes created using these OpenID partners protect Access Manager resources using
authentication services provided by the OpenID identity providers. Take these steps to
create a new OpenID 2.0 identity provider (IdP).
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Identity Provider Partner from the Create
(+) drop-down list in the Federation section.
3. Fill in the values appropriate for your environment either manually or by
uploading a metadata file.
The information you provide depends on the protocol chosen for the provider and
other factors.
4. Click Save to create the identity provider definition.
Google IdP Partners
Take these steps to add Google as an OpenID 2.0 IdP.
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Identity Provider Partner from the Create
(+) drop-down list in the Federation section.
3. From the Launch Pad, click Service Provider Administration under Identity
Federation.
4. Select OpenID 2.0 from the Protocol drop down menu.
5. Select Google provider default settings from the Service Details drop down
menu.
6. Click Save to create the identity provider definition.
The partner is configured so that the SP requests the assertion attributes listed in
Table 38–3 from the Google IdP and maps them to the corresponding session attribute
names:
Note: Some SAML 1.1 configuration parameters are not exposed
through the Oracle Access Management Console. The values of these
parameters can be modified using the
updatePartnerProperty
WLST
command. For details, see the Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
Table 38–3 Attributes for Google OpenID Partner
Assertion Attribute Name Session Attribute Name
http://axschema.org/contact/country/home country
http://axschema.org/contact/email email
http://axschema.org/namePerson/first firstname
http://axschema.org/pref/language language
http://axschema.org/namePerson/last lastname
Administering Identity Federation As A Service Provider
38-8 Administrator's Guide for Oracle Access Management
The Google partner uses
mail
as the user mapping attribute, so that an incoming
http://axschema.org/contact/email
attribute should match the
mail
attribute of the
user in the user identity store.
Yahoo IdP Partners
Take these steps to add Yahoo as an OpenID 2.0 IdP.
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Identity Provider Partner from the Create
(+) drop-down list in the Federation section.
3. Select OpenID 2.0 from the Protocol drop down menu.
4. Select Yahoo provider default settings from the Service Details drop down menu.
5. Click Save to create the identity provider definition.
The partner is configured so that the SP requests the assertion attributes listed in
Table 38–4 from the Yahoo IdP and maps them to the corresponding session attribute
names:
The yahoo partner uses
mail
as the user mapping attribute, so that an incoming
http://axschema.org/contact/email
attribute should match the
mail
attribute of the
user in the user identity store.
To Enable OpenID Simple Registration
By default, Identity federation uses the Attribute Exchange extension to obtain user
identity attributes from an OpenID IdP. However, if you need to use the older Simple
Registration (SREG) extension, you can enable it by running the following WLST
commands:
putBooleanProperty("/spglobal/openid20axenabled", "false")
putBooleanProperty("/spglobal/openid20sregenabled", "true")
To Disable OpenID Simple Registration
To switch from the Simple Registration (SREG) extension to the Attribute Exchange
extension to obtain user identity attributes from an OpenID IdP:
putBooleanProperty("/spglobal/openid20axenabled", "true")
putBooleanProperty("/spglobal/openid20sregenabled", "false")
38.3.2 Managing the Remote Identity Provider Partners
You can use the following procedure to manage an existing IdP for Identity
Federation.
Table 38–4 Attributes for Yahoo OpenID Partner
Assertion Attribute Name Session Attribute Name
http://axschema.org/contact/country/home country
http://axschema.org/contact/email email
http://axschema.org/namePerson/first firstname
http://axschema.org/pref/language language
http://axschema.org/namePerson/last lastname
Administering Identity Federation As A Service Provider
Managing Identity Federation Partners 38-9
To Search for Existing Identity Providers
Follow these steps:
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, click Identity Provider Management in the Federation
section.
3. In the Search section of the page, enter appropriate search criteria for identity
provider(s). The characters "
*
" (asterisk) and "
.
" (period) are supported as search
wildcards. See Table 38–5 for details about the search parameters.
4. Click Search.
5. The search results are displayed in a table.
Table 38–5 describes the parameters by which providers can be searched.
Figure 38–3 Searching for Identity Providers
To Update Identity Providers for Federation
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, click Identity Provider Management in the Federation
section.
3. Search for the provider you wish to update. See "To Search for Existing Identity
Providers" for details.
4. Select the provider of interest from the search results table.
Table 38–5 Elements Used for IdP Provider Search
Element Description
Partner Name Searches for a specific partner name.
Provider ID Searches by provider ID.
Status Searches providers matching a status.
Description Searches by provider description.
Protocol Searches for providers that use a specified protocol.
Administering Identity Federation As An Identity Provider
38-10 Administrator's Guide for Oracle Access Management
5. Click the pencil icon to display the provider update page. The page is divided into
sections for: Service Information, Signing Certificates, User Mapping, and
Advanced.
6. Update the provider information. See Table 38–2 for details.
For information on configuring HTTP Basic Authentication to protect SOAP URLs
after it has been enabled, see the Oracle Fusion Middleware Administrator's Guide for
Oracle Identity Federation.
7. Click Save to update the Identity Provider definition.
38.4 Administering Identity Federation As An Identity Provider
When the integrated Identity Federation is configured as an IdP, you must define any
remote SP partners as trusted by creating and managing profiles that contain details
regarding each remote SP. This section provides the following topics.
■Creating Remote Service Provider Partners
■Managing the Remote Service Provider Partners
38.4.1 Creating Remote Service Provider Partners
Use the Service Provider Partner page to define a partner profile when Identity
Federation is configured as an IdP. You can specify service details manually or load
them from a metadata file.
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Create Service Provider Partner from the Create
(+) drop-down list in the Federation section.
3. Enter values for the parameters.
Table 38–6 describes each element on the Create Service Provider page.
Table 38–6 Service Provider Partner Settings
Element Description
Name This is the provider name.
Enable Partner Select whether this partner is currently participating in the federation.
Description This is a brief description of the provider. (Optional).
Protocol This is the provider protocol (SAML 1.1, SAML 2.0 or OpenID 2.0).
Service Details Select whether to enter service details manually or load from metadata. If
selecting the latter, browse for the metadata file. Applies to SAML 2.0 only.
Metadata File This field appears if loading metadata from a file. Click Browse to select a
file to use. Applies to SAML 2.0 only.
Provider ID The provider ID or issuer ID of the remote Service Provider. Applies to
SAML 2.0 and SAML 1.1 only.
Assertion Consumer URL A URL to which Assertion responses are sent. Applies to SAML 2.0 and
SAML 1.1 only.
Load Signing Certificate Upload the signing certificate used by this SP. Only visible when Enter
Manually is selected. Applies to SAML 2.0 and SAML 1.1 only.
Logout Request URL A URL to which logout requests are sent. Applies to SAML 2.0 only.
Logout Response URL A URL to which responses to logout requests are sent. Applies to SAML 2.0
only.
Administering Identity Federation As An Identity Provider
Managing Identity Federation Partners 38-11
4. Click Save to create the remote SP partner profile.
38.4.2 Managing the Remote Service Provider Partners
To edit and manage the profiles of remote SP partners, search for the profile and make
changes to the attribute values.
To Search for Existing Service Provider Partner Profiles
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, click Service Provider Management in the Federation
section.
3. In the Search section of the page, enter appropriate search criteria for identity
provider(s). The characters "
*
" (asterisk) and "
.
" (period) are supported as search
wildcards. See Table 38–5 for details about the search parameters.
4. Click Search.
5. Select the appropriate partner in the Search Results table and click Edit in the
toolbar.
Load Encryption Certificate Upload the encryption certificate used by this SP. Only visible when Enter
Manually is selected. Applies to SAML 2.0 only.
NameID Format Indicates which NameID format should be used for this SP. Applies to
SAML 2.0 and SAML 1.1 only. See Section 37.6.1, "Using SAML 2.0" and
Section 37.6.2, "Using SAML 1.1" respectively for details on the NameID
format.
NameID Value Indicates how to populate the NameID Value. Applies to SAML 2.0 and
SAML 1.1 only.
■If User ID Store Attribute is selected, specify the user attribute to be
used.
■If Expression is specified, enter the expression to be used
Attribute Mapping Profile Indicates the attribute mapping profile to which the partner is bound.
Applies to SAML 2.0 and SAML 1.1 only.
User Identity Store This is the identity store in which the IdP's users will be located and
mapped. Identity Federation supports multiple identity stores, defined on a
per-partner basis. If no user identity store is selected, the default store
defined for Access Manager is used.
User Search Base DN This is the base search DN used when looking up user records. (Optional. If
omitted, the default user search base DN configured for the selected user
identity store is used.)
Enable Global Logout Indicates whether or not OIF should notify the remote partner when the
user is signing off, during the logout flow. Applies to SAML 2.0 only.
SSO Response Binding Indicates whether the SAML Assertion should be sent back from the IdP
using the HTTP POST Binding or the Artifact Binding, Applies to SAML 2.0
and SAML 1.1 only.
Encrypt Assertion Indicates whether or not the Assertion should be encrypted for this partner.
Applies to SAML 2.0 only.
Realm The URL identifying an OpenID SP. Applies to OpenID 2.0 only.
Endpoint URL The URL to which the IdP will redirect the user with the OpenID Assertion.
Applies to OpenID 2.0 only.
Table 38–6 (Cont.) Service Provider Partner Settings
Element Description
Using Attribute Mapping Profiles
38-12 Administrator's Guide for Oracle Access Management
A new tab is activated that displays the partner's attributes. In addition to the
attributes documented in Table 38–6, the following advanced attributes can be
modified.
■Enable Global Logout
■Encrypt Assertion
■SSO Response Binding (HTTP POST or Artifact)
6. Click Save to keep the changes.
38.5 Using Attribute Mapping Profiles
Identity Federation (when configured as an SP) supports the capability to request
attributes from an IdP during the Federation process. To configure for this, map the
name of an attribute from the incoming Assertion to a local attribute that will be
available in the Access Manager session (
$session.attr.fed.attr.ATTR_NAME
, for
example). An IdP Attribute Mapping Profile contains these mappings.
Similarly, Identity Federation (when configured as an IdP) supports including
attributes in an SSO Assertion or allowing SP partners to request that attributes be
placed in the SSO Assertion. Configuring Identity Federation as an IdP involves
setting up an SP Attribute Mapping profile that defines the name of the attribute in the
SSO assertion, the expression to be used to populate the attribute value, and whether
or not to always send the attribute in the SSO Assertion.
Each partner type (IdP or SP) references an Attribute Mapping Profile that defines the
applicable mappings. It indicates how to map attributes for that partner to attributes
defined in the Identity Federation server. If a partner does not have an Attribute
Mapping Profile defined, the default Attribute Mapping Profile (based on the partner
type) will be used. There is a default Attribute Mapping Profile for each provider type.
■SP Attribute Mapping Profile: Each SP partner profile will reference an SP
Attribute Mapping Profile. A default SP Attribute Mapping Profile will be used if
none is configured. See Section 38.5.1, "Using the SP Attribute Mapping Profile"
for details.
■IdP Attribute Mapping Profile: Each IdP partner profile will reference an IdP
Attribute Mapping Profile. A default IdP Attribute Mapping Profile will be used if
none is configured. See Section 38.5.2, "Using the IdP Attribute Mapping Profile"
for details.
38.5.1 Using the SP Attribute Mapping Profile
When the Identity Federation instance is configured as an IdP, the SP Attribute
Mapping Profile allows the administrator to define which message attributes
(included in an incoming or outgoing Identity Federation message) map to which
Access Manager session attributes. An expression is used to find the value for the
Note: If using SAML 1.1, you can include a certificate in the
signature. See Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference for details.
Note: The protocol used by the provider must support the feature;
for example, OpenID 2.0.
Using Attribute Mapping Profiles
Managing Identity Federation Partners 38-13
Access Manager attribute when including it in an Assertion or outgoing message.
Table 38–7 documents some sample SP attribute mappings.
Always Send indicates if the attribute should be sent even when it has not been
specifically requested. If an attribute has to be included in an outgoing Assertion
irrespective of whether it has been requested, Always Send should be set to true. If
Always Send is false, this attribute will not be included in the Assertion unless
requested. When an SP sends a request, message attributes are looked up and the
mapping value for this message attribute is calculated by evaluating its expression.
When creating or modifying an SP partner profile (as documented in Section 38.4.1,
"Creating Remote Service Provider Partners"), the available Attribute Mapping Profiles
are displayed in a drop-down list.
sp-attribute-profile
is the default profile. Select
the default or click the green plus sign to create a custom mapping profile. When
creating a new Attribute Mapping for an SP partner, the expressions documented in
Table 38–8 can be embedded in the value string of the attribute. These expressions will
be replaced by their runtime values.
Table 38–7 Sample SP Attribute Mappings
Message Attribute Access Manager Session Attribute Always Send
mail $user.attr.mail
firstname $user.attr.givenname true
lastname $user.attr.sn true
authn-level $session.authn_level true
Note: The Value expression will use the OAM Policy Expression
Language as documented in Section 25.13, "Introduction to Policy
Responses for SSO." More than one message attribute can have the
same value expression.
Table 38–8 Attribute Mapping Value Expressions
Value Type Accepted Values Expression
request httpheader.HTTP_HEADER_
NAME
HTTP_HEADER_NAME being the name of
an HTTP Header stored as
$request.httpheader.HTTP_HEADER_
NAME
cookie.COOKIE_NAME COOKIE_NAME being the name of a
cookie stored as $request.cookie.COOKIE_
NAME
client_ip stored as $request.client_ip
session authn_level stored as $session.authn_level
authn_scheme stored as $session.authn_scheme
count stored as $session.count
creation stored as $session.creation
expiration stored as $session.expiration
attr.ATTR_NAME ATTR_NAME being the name of an Access
Manager Session Attribute stored as
$session.attr.ATTR_NAME
Using Attribute Mapping Profiles
38-14 Administrator's Guide for Oracle Access Management
38.5.2 Using the IdP Attribute Mapping Profile
When the Identity Federation instance is configured as an SP, the IdP Attribute
Mapping Profile allows the administrator to define which attributes (included in an
incoming or outgoing Identity Federation message) map to which Access Manager
session attributes. The profile allows for the inclusion of the following data:
■Message Attribute: the name of the attribute in the incoming/outgoing Federation
messages.
■Access Manager Session Attribute: the name by which the attribute is known to
the local Access Manager server.
user userid stored as $user.userid
id_domain stored as $user.id_domain
guid stored as $user.guid
groups stored as $user.groups
attr.ATTR_NAME ATTR_NAME being the name of an LDAP
User Attribute stored as $user.attr.ATTR_
NAME
expression
(Based on the
identifiers
defined above
and qualified
with the type
of data)
- request:
■$request.httpheader.HTTP_
HEADER_NAME
■$request.cookie.COOKIE_
NAME
■$request.client_ip
-
■HTTP_HEADER_NAME being the
name of an HTTP Header
■COOKIE_NAME being the name of a
cookie
■
- session:
■$session.authn_level
■$session.authn_scheme
■$session.count
■$session.creation
■$session.expiration
■$session.attr.ATTR_NAME
-
■
■
■
■
■
■ATTR_NAME being the name of an
Access Manager Session Attribute
- from user:
■$user.userid
■$user.id_domain
■$user.guid
■$user.groups
■$user.attr.ATTR_NAME
■can be any string, with '.'
(dot) characters, spaces
characters (like
"$user.userid" or
"$user.attr.givenname
$user.attr.sn" or "This is the
number of sessions:
$session.count")
-
■
■
■
■
■ATTR_NAME being the name of an
LDAP User Attribute
■
Table 38–8 (Cont.) Attribute Mapping Value Expressions
Value Type Accepted Values Expression
Mapping Federation Authentication Methods to Access Manager Authentication Schemes
Managing Identity Federation Partners 38-15
■Request From Partner: Indicates if this attribute is sent in the Request made to the
IdP (a value for this attribute is requested by the SP).
Table 38–9 documents sample IdP attribute mappings.
In a protocol where a SP can specify which attributes are required in a response from
the IdP, a Message Attribute name is sent in the request to the IdP. In cases when the
SP receives an assertion or response from an IdP, the Attributes from the assertion are
stored in the Access Manager session. If no Access Manager value is specified, the
Message Attribute is stored.
When creating or modifying an IdP partner profile (as documented in Section 38.3.1,
"Creating Remote Identity Provider Partners"), the Attribute Mapping Profile is
displayed with a drop-down list. The
idp-attribute-profile
is the default profile.
Select the default or click the green plus sign to create a custom mapping profile.
The Ignore Umapped Attributes checkbox (in the configuration screen) indicates how
to deal with Assertion Attributes not present (or that are present but have no value in
the Access Manager Session Attribute column). If this checkbox is not checked, all
Assertion Attributes that are not present in the table (or don't have a value mapped to
Access Manager) will be stored in the Access Manager session with the same attribute
name it had in the Assertion. If checked, any Assertion Attribute not present in the
table (or with no value mapped to Access Manager) will be ignored and not added to
the Access Manager session.
38.6 Mapping Federation Authentication Methods to Access Manager
Authentication Schemes
A Federation Authentication Method (FAM) is an identifier representing an
authentication mechanism in Federation messages. This identifier can either be well
known (such as the identifiers defined in the SAML specifications like
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
or
urn:oasis:names:tc:SAML:1.0:am:password
) or it can be an arbitrary identifier
agreed upon between the two communicating partners.
In its responsibilities as an IdP, Identity Federation generates an Assertion (SAML or
OpenID) that might contain information on how the user was authenticated. During
the Assertion generation process, the IdP will retrieve the Authentication Scheme with
which the user was authenticated and attempt to map it to a FAM. If such a mapping
exists, the IdP will include the FAM in the outgoing Assertion. If no mapping exists,
the IdP will include the defined Authentication Scheme as the FAM in the Assertion.
Table 38–9 Sample IdP Attribute Mappings
Message Attribute Access Manager Session Attribute Request for Inclusion
mail email true
givenname true
sn surname
uid uid
Note: When the Identity Federation instance is configured as an SP it
can request attributes only if the federation protocol used supports it.
OpenID 2.0 supports this feature; SAML 2.0 and SAML 1.1 do not.
Mapping Federation Authentication Methods to Access Manager Authentication Schemes
38-16 Administrator's Guide for Oracle Access Management
Table 38–10 lists the default, out-of-the-box mappings between FAMs and Access
Manager Authentication Schemes.
More details are in the following sections.
■Understanding Federation SSO As An IdP
■Understanding Federation SSO As An SP
■Configuring an Alternate Authentication Scheme
■Using WLST For Mapping Administration
38.6.1 Understanding Federation SSO As An IdP
When Identity Federation acts as an IdP, it processes incoming Authentication Request
messages sent by SP partners. These messages might specify a FAM with which the
user should be challenged by Access Manager (the IdP). If the Authentication Request
contains a FAM, the IdP will attempt to map it to an Access Manager Authentication
Scheme. If such a mapping is defined, Access Manager will authenticate the user using
that scheme - only if the user needs to be challenged. The user would need to be
challenged if, for example, the session timed out or does not exist or, the
authentication level of the current session is lower than the level of the mapped
Authentication Scheme or, the user has not yet been authenticated by Access Manager.
If no mapping is defined, the IdP will return an error to the SP indicating that the FAM
is unknown.
When the IdP Authentication Module invokes Access Manager to challenge the user, it
will determine the Authentication Scheme to be used for the operation in one of the
following ways:
Note: Session attributes can be used in proxy mode when a mapping
is not defined. Identity Federation (when acting as an IdP) can use
session attributes for the FAM value when creating the assertion, if
both protocols are equivalent.
Table 38–10 Default Federation Authentication Method and Access Manager
Authentication Scheme Mappings
Protocol Mapping
saml20-sp-partner-profile urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTranspor
t to:
■LDAPScheme (scheme used if the SP Partner requests
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTran
sport)
■FAAuthScheme
■BasicScheme
■BasicFAScheme
saml11-sp-partner-profile urn:oasis:names:tc:SAML:1.0:am:password to:
■LDAPScheme (scheme used if the SP Partner requests
urn:oasis:names:tc:SAML:1.0:am:password)
■FAAuthScheme
■BasicScheme
■BasicFAScheme
Mapping Federation Authentication Methods to Access Manager Authentication Schemes
Managing Identity Federation Partners 38-17
■The SP requests a specific means to authenticate the user with a Federation
Authentication Request.
■The SP settings in the IdP configuration that define a default scheme. The Partner
configuration is checked first, followed by the Partner Profile configuration and
finally the global default Authentication Scheme defined in the IdP configuration
(LDAPScheme).
After authentication, the IdP creates an Assertion and maps the Access Manager
Authentication Scheme (and appropriate level) to a FAM, if such a mapping exists. The
FAM is set as the Authentication Context. If no mapping exists, Identity Federation
sends the default Access Manager Authentication Scheme as the Authentication
Context. Following this process, the user is redirected back to Identity Federation.
38.6.2 Understanding Federation SSO As An SP
When acting as an SP in a Federation SSO process, Identity Federation processes an
incoming Assertion generated by an IdP partner. This process results in the creation of
an Access Manager session for the user and the mapping of the FAM contained in the
Assertion to the default SchemeID/Access Manager authentication scheme. Identity
Federation provides the authentication level, if set, that should be used when Access
Manager creates the user session. (By default, the Authentication Level of the Access
Manager session will be set to the Authentication Level of the defined
FederationScheme.) The FAM will be saved as a session attribute.
The administrator can define a mapping where the SP will create an Access Manager
session with a level set to the mapped Authentication Level for the FAM contained in
the Assertion. This provides a way to reflect the strength of the mechanism with which
the user was originally authenticated by the IdP.
38.6.3 Configuring an Alternate Authentication Scheme
During a Federation SSO operation, the IdP invokes the Access Manager
Authentication Module to challenge the user when required; for example, if the user is
not authenticated in Access Manager, has an Access Manager session that has been
inactive too long or timed out or, if the Service Provider indicates (with a Federation
Authentication Request) that the IdP must re-challenge the user. For certain clients, an
IdP might be required to use another Authentication Scheme to challenge a user
besides the default one. This is especially true for mobile phones when an
administrator might want to challenge a user with an Authentication Scheme that is
different than the one used for computer-based browsers; for example, instead of an
HTTP Basic Authentication Scheme, a scheme designed for mobile clients would be
used.
Identity Federation (when working as an IdP) can be configured to evaluate whether
an alternate Authentication Scheme should be used instead of the configured one by
examining the HTTP Header sent by the user's browser. Identity Federation evaluates
based on the following configurable settings:
■A setting indicating which HTTP Header attribute is sent by the user's browser.
■A setting containing a regular expression that will evaluate the value of the above
HTTP Header attribute.
Note: By default, the Partner and Partner Profile configurations do
not define a default Authentication Scheme. As such, the global
default Authentication Scheme is in effect: LDAPScheme.
Using the Attribute Sharing Plug-in for the Attribute Query Service
38-18 Administrator's Guide for Oracle Access Management
■A setting containing the alternate Authentication Scheme to use.
An alternate Authentication Scheme is only configurable using WLST commands and
not the Oracle Access Management Console. For information on the
setSPPartnerAlternateScheme
and
setSPPartnerProfileAlternateScheme
WLST
commands, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
38.6.4 Using WLST For Mapping Administration
All Authentication Method/Scheme/Level mappings are configured using the WLST
commands. This can be done either at the partner level or, if not defined at the partner
level, at the partner profile level. See Section 38.9, "Using WLST for Identity Federation
Administration" for details.
38.7 Using the Attribute Sharing Plug-in for the Attribute Query Service
Identity Federation provides an attribute sharing plug-in to enable Access Manager to
request user attributes from an IdP. In this interaction, the SP is an <AttributeQuery>
requestor and the IdP is an <AttributeQuery> responder. The Attribute Sharing
Plug-in depends on the Attribute Query Service, a request/response protocol
transported using SOAP.
Identity Federation (when configured as an SP) can send a SAML 2.0
<AttributeQuery> to the IdP in response to a SOAP call. The plug-in can be configured
as a step in an Authentication Scheme. It can be invoked after authentication (by
another plug-in) to fetch attributes for the authenticated user and set them into the
Access Manager session. The following sections contain additional details.
■Understanding the Plug-in and Query Service Design
■Configuring for Attribute Sharing
38.7.1 Understanding the Plug-in and Query Service Design
Identity Federation must be configured as an SP to request user attributes from a
remote IdP. From a high level, the design of the Attribute Sharing plug-in is illustrated
in Figure 38–4.
Note: If the SP requested a specific Authentication Scheme,
evaluation does not apply.
Note: The Attribute Sharing Plug-in leverages the AttributeQuery
requestor service to implement (a superset of) the X.509
Authentication Based Attribute Sharing Profile (XASP) in the context
of Access Manager authentication flows.
Using the Attribute Sharing Plug-in for the Attribute Query Service
Managing Identity Federation Partners 38-19
Figure 38–4 Attribute Sharing Plug-in Design
The Attribute Sharing plug-in can be part of an Access Manager Custom
Authentication Module and is invoked after a user has been authenticated. The
Attribute Sharing plug-in will fetch the user attributes by invoking the Identity
Federation Java API, setting the attributes into the Access Manager session and
transforming the Java arguments into an Attribute Request that can be processed by
the SP. The Identity Federation SP receives the Attribute Request (at an exposed SOAP
endpoint), determines the attributes being requested and sends an (optionally) signed
and encrypted SAML 2.0 <AttributeQuery> using the requested attribute names over
a SOAP/HTTP/SSL channel to the IdP's Attribute Responder Service.
The Attribute Responder Service (at the remote IdP) receives the <AttributeQuery>,
decrypts it (verifying the signature if necessary) and determines (from its local policy)
if the SP is authorized to request the attributes. If so, it retrieves the attributes from a
user repository, constructs and (optionally) signs and encrypts an <Assertion> (with
an <AttributeStatement> containing the attribute values) and returns a <Response>
with the assertion to the SP. On receiving the <Response>, the SP decrypts the
assertion, verifies (if necessary) its signature, extracts the attributes from the assertion
and set the information in the Access Manager session. The following sections contain
more details.
■Using the SP Attribute Requester
■Using the IdP Attribute Responder
■Using the SOAP Endpoint
38.7.1.1 Using the SP Attribute Requester
The Attribute Requester Service processes the SOAP Attribute Request and returns a
SOAP Attribute Response. (See Section 38.7.1.3, "Using the SOAP Endpoint" for
details.) The Attribute Request will contain a SubjectDN and a list of other requested
attributes and their values. The Attribute Requester Service identifies the IdP from
Note: When invoking the Attribute Sharing plug-in, the framework
will provide the following for inclusion in the <AttributeQuery>:
■User ID of the authenticated user or SubjectDN if available
■Partner ID user session attribute (available only if the Federation
Authentication plug-in was used to authenticate user)
■Tenant Name
■IdP Name if the plug-in was created specifically for an IdP
Using the Attribute Sharing Plug-in for the Attribute Query Service
38-20 Administrator's Guide for Oracle Access Management
which to fetch attributes by extracting one of the following (searched for in the order
listed) from the request.
1. The partner/IdP name if the request comes from the Federation engine.
2. The IdP configured in the plug-in used for authentication.
3. The request's Subject DN to determine which IdP will get the query from the
configured SubjectDN-IdP map. Map the SubjectDN from most specific (cn=Joe
User,ou=Finance,o=Company,c=US) to least specific (c=US).
4. The default IdP.
Following this discovery, the Attribute Requester Service retrieves the SOAP Attribute
Responder Service endpoint URL from the IdP's metadata and creates a list of
attributes to fetch by processing the attributes in the request through the Attribute
Mapping profile.
A SAML Attribute Query is generated with the attribute list and sent to the IdP's
SOAP endpoint. Once a response is received, the subject is verified and the each
attribute is extracted from the Assertion, its value is found and both attribute and
value are cached. Finally, an Attribute Response SOAP message is constructed and
returned to the caller. Example 38–1 is a sample SOAP Attribute Request.
Example 38–1 Sample SOAP Attribute Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<attrreq:AttributeRequest TargetIDP="adc.example.com"
xmlns:attrreq="http://www.example.com/fed/ar/10gR3">
<attrreq:Subject
Format="oracle:security:nameid:format:emailaddress">alice@example.com
</attrreq:Subject>
<attrreq:Attribute Name="cn">
</attrreq:Attribute>
</attrreq:AttributeRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example 38–2 is a sample SOAP attribute response.
Example 38–2 Sample SOAP Attribute Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:ns2="http://www.w3.org/2005/08/addressing"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:enc="http://www.w3.org/2001/04/xmlenc#"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:wst14="http://docs.oasis-open.org/ws-sx/ws-trust/200802"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity"
xmlns:mdext="urn:oasis:names:tc:SAML:metadata:extension"
xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"
Note: Attribute Mapping profile specified for the target IdP will be
used to change any incoming attribute names as well as add any
attributes that are configured as
send-with-sso
(always requested) in
the Attribute Mapping for this IdP.
Using the Attribute Sharing Plug-in for the Attribute Query Service
Managing Identity Federation Partners 38-21
xmlns:ns11="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:ns14="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:xrds="xri://$xrds" xmlns:xrd="xri://$xrd*($v*2.0)"
xmlns:tns="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
xmlns:ns18="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
xmlns:ns19="urn:oasis:names:tc:SAML:1.0:protocol"
xmlns:ns20="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsse11="http://docs.oasis-open.org/wss/
oasis-wss-wssecurity-secext-1.1.xsd"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"
xmlns:orafed-arxs="http://www.oracle.com/fed/ar/10gR3"
xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"
xmlns:ns31="urn:oasis:names:tc:SAML:profiles:v1metadata"
xmlns:ecp="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp">
<soap:Body><orafed-arxs:AttributeResponse CacheFor="899">
<orafed-arxs:Status>Success</orafed-arxs:Status>
<orafed-arxs:Subject Format="oracle:security:nameid:format:emailaddress">
alice@example.com</orafed-arxs:Subject>
<orafed-arxs:Attribute Name="cn">
<orafed-arxs:Value>alice</orafed-arxs:Value>
</orafed-arxs:Attribute>
</orafed-arxs:AttributeResponse>
</soap:Body>
</soap:Envelope>
38.7.1.2 Using the IdP Attribute Responder
The Identity Federation IdP Attribute Responder receives the SAML Attribute Query
and returns a SAML response with an Attribute Statement that contains values for the
requested attributes. The IdP first identifies the requester as an SP partner and then
confirms that the user is in the user data store by searching on the NameId or
SubjectDN value. It then uses the Attribute Mapping profile of the SP partner to
retrieve values for each of the requested attributes. Finally, it constructs and returns a
SAML response containing an Attribute Statement with attribute values.
38.7.1.3 Using the SOAP Endpoint
The Attribute Requester Service on the SP exposes a SOAP interface for client requests.
The SOAP service is available on the SP at the following URL:
Note: The Attribute Responder uses the SP partner's Attribute
Mapping profile to retrieve values. An empty value is returned for an
attribute if there is no mapping present in the Attribute Mapping
profile. If the value expression contains variables in the namespace of
a session or request, this also evaluates to an empty string. Value
Expressions in the Attribute Mapping Profile can only use variables in
the namespace of
user.attr
to be evaluated correctly.
Using the Attribute Sharing Plug-in for the Attribute Query Service
38-22 Administrator's Guide for Oracle Access Management
http://<SP-managed-server>:<SP-port>/oamfed/ar/soap
38.7.2 Configuring for Attribute Sharing
The Attribute Sharing Plug-in can optionally be provided with the configuration
parameters documented in Table 38–11.
The Attribute Sharing Plug-in can also access the attributes documented in
Table 38–12. These attributes may be present in the Access Manager session during its
operation.
The following sections have additional details on parameters and how they determine
how the Attribute Sharing process.
■NameID
■NameID Format
■IdP
■RequestedAttributes
Table 38–11 Configuration Parameters for Attribute Sharing Plug-in
Parameter Description
NameIDValueAttribute The name of the session attribute from which the user's nameID
can be retrieved.
NameIDFormatAttribute The name of the attribute that contains the value to be used as
the nameID format.
AttributeAuthorityAttribute The name of the attribute that contains the value used as the IdP
to which the SP will send the <AttributeQuery>.
RequestedAttributes This parameter can be used to specify attributes to be requested
in the URL query format; for example,
attr1&attr2&attr3=value1
. In this case, attr1 and attr2 will be
fetched but attr3 will be present in the response ONLY if one of
its values is value1.
DefaultNameIDFormat The nameID format to be used if it is undetermined from the
other parameters and session attributes.
DefaultAttributeAuthority The default IdP partner from whom to request the user's
attributes.
Table 38–12 Session Attributes Accessible To Attribute Sharing Plug-in
Attribute Description
fed.partner If Federation was used to authenticate the user, this value is used to
determine the IdP used. The same IdP would then be used for
Attribute Sharing.
fed.nameidformat If Federation was used to authenticate the user, the value of this
attribute is used to determine the NameID format.
fed.nameidvalue If Federation was used to authenticate the user, the value of this
attribute is used to determine the NameID of the user. If present in
the session, it will be used as the DN to locate the user in the SP's
identity store.
KEY_USERNAME_DN If this value is present, it will be used as the DN to locate the user in
the SP's identity store.
Using the Attribute Sharing Plug-in for the Attribute Query Service
Managing Identity Federation Partners 38-23
38.7.2.1 NameID
This is the name identifier of the user for whom the SP is requesting attributes. To
determine the NameID, the following searches will be conducted in order.
In the Attribute Sharing plug-in
1. If the NameIDValueAttribute is specified, retrieve the value of the specified
attribute from the session and use it as the NameID.
2. If NameIDValueAttribute is not specified, use the value of
fed.nameidvalue
for
the NameID.
3. If undetermined by the above, the Attribute Sharing Plug-in will invoke the
Federation Engine with a null/empty NameID and the UserID (specified in the
KEY_USERNAME_DN session attribute) is sent to the SP Attribute Requester.
In the Attribute Requester (SP)
1. If the NameID is in the Request, use its value for the user's nameID.
2. If a NameID is undetermined but a UserID is present (which occurs when
invoking the Authentication Plug-in), retrieve the value of the
defaultattrrequestnameiduserattribute
attribute (found in the SP
configuration for this IdP) and use it as the NameID.
3. When using SAML 2.0 only: If a NameID is not determined and SSO is configured
for Simple NameID mapping, use the
nameiduserattribute
attribute (found in
the SP configuration for this IdP). For example, if the value of this attribute is
$user.attr.mail
, extract the name of the user from this attribute and use it as the
NameID.
4. If a NameID is still undetermined, an error is thrown.
38.7.2.2 NameID Format
This is the format of the user's NameID. To determine the NameID format, the
following searches will be conducted in order.
In the Attribute Sharing plug-in
1. If the NameIDFormatAttribute parameter (Table 38–11) is specified, retrieve the
value of the specified attribute and use it as the NameID format.
2. Use the value of the
fed.nameidformat
attribute (Table 38–12) as the NameID
format.
3. Use the value of the
DefaultNameIDFormat
(Table 38–11) as the NameID format.
4. If NameID Format is still undetermined, the Attribute Sharing plug-in will invoke
Federation with a null/empty NameID Format.
In the Attribute Requester (SP)
1. Use the NameID Format specified in the request.
2. Use the value of the
defaultattrrequestnameidformat
attribute (found in the SP
configuration for this IdP).
3. When using SAML 2.0 only: If the NameID Format is still undetermined, use the
value of the
defaultauthnrequestnameidformat
attribute (found in the SP
configuration for this IdP).
4. If a NameID Format is still undetermined, an error is thrown.
Using the Federation Proxy
38-24 Administrator's Guide for Oracle Access Management
38.7.2.3 IdP
This is the IdP partner to which the attribute request should be sent. To determine the
IdP partner, the following searches will be conducted in order.
In the Attribute Sharing plug-in
1. If the AttributeAuthorityAttribute (Table 38–11) is specified, retrieve its value and
use it as the IdP name.
2. Use the value of the
fed.partner
attribute (Table 38–12) as the IdP name.
3. Use the value of the
DefaultAttributeAuthority
parameter (Table 38–11) as the
IdP name.
4. If the IdP is still undetermined, the Attribute Sharing plug-in will invoke
Federation with a null/empty NameID Format.
In the Attribute Requester (SP)
1. Use the IdP name included with the request sent to the Attribute Sharing plugin.
2. When using x509 only: look up the dn-idp mapping to determine the IdP for this
user DN.
3. Use the value of the
defaultattrauthority
attribute (found in the SP
configuration).
4. Use the value of the
defaultssoidp
attribute (found in the SP configuration).
5. If an IdP name is still undetermined, an error is thrown.
38.7.2.4 RequestedAttributes
These are the attributes to be requested from the Attribute Authority. To determine the
attributes, the following searches will be conducted in order.
In the Attribute Sharing plug-in
If the
RequestedAttributes
parameter (Table 38–11) is defined, use the attributes
specified. If none are specified, no attributes are sent.
In the Attribute Requester (SP)
1. If the
RequestedAttributes
parameter (Table 38–11) is defined, use the attributes
specified.
2. Append (or add) attributes to the
request from partner(send-with-sso)
attribute in the IdP partner profile.
In the Attribute Responder (IdP)
1. If the <AttributeQuery> from the SP contains requests for specific attribute values,
return values for those attributes.
2. If no attribute values are requested, return any attributes specified as
Always Send
(send-with-sso)
in the SP attribute profile configuration.
38.8 Using the Federation Proxy
When configured as an IdP, Identity Federation can enable the Federation Proxy to
receive an Authentication Request from a remote SP partner. Rather than
authenticating the user locally, the IdP begins a second Federation SSO flow (SP2) with
a second, remote IdP (IdP2). IdP2 then authenticates the user, creates an Assertion and
Using WLST for Identity Federation Administration
Managing Identity Federation Partners 38-25
redirects the user back to the Federation Proxy (IdP/SP2). The proxy validates the
Assertion, identifies the user and resumes the first Federation SSO flow by creating a
second Assertion and redirecting the user back to the original SP. With Federation
Proxy, the first IdP is proxying the authentication to the second IdP.
To use Federation IdP Proxy, the administrator configures Identity Federation to use
FederationScheme for authentication rather than a local scheme (like LDAPScheme or
BasicScheme). At runtime, if the user needs to be authenticated using the
FederationScheme, Identity Federation will act as an SP and start the Federation SSO
flow with a remote IdP.
For information on how to enable Federation Proxy using the
useProxiedFedAuthnMethod
WLST command, see the Oracle Fusion Middleware
WebLogic Scripting Tool Command Reference.
38.9 Using WLST for Identity Federation Administration
Identity Federation uses WLST commands for administration. There are commands
for managing authentication mappings, partner profiles and SAML 1.1 that do not
have applicable administrative fields for configuration in the Oracle Access
Management Console. For information on these and other WLST commands, see the
Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and
Access Management.
Note: The Federation Proxy does not refer to the HTTP Proxy
settings listed under Federation Settings. That is used by Identity
Federation to connect to remote servers when a firewall is present.
Note: There is an option to include the proxied Federation
authentication method used by the second IdP in the Assertion
created for the first SP. This is only possible if the Federation SSO
operation between SP2 and IdP2 use the same protocol as the one
used between SP1 and IdP1.
Using WLST for Identity Federation Administration
38-26 Administrator's Guide for Oracle Access Management
39
Managing Settings for Identity Federation 39-1
39
Managing Settings for Identity Federation
This chapter introduces the settings that must be configured for use by Oracle Access
Management Identity Federation. This chapter includes the following sections:
■Prerequisites
■Introduction to Federation Settings
■Managing General Federation Settings
■Managing Proxy Settings for Federation
■Defining Keystore Settings for Federation
■Exporting Metadata
39.1 Prerequisites
The topics in this chapter presume that you have performed tasks in Chapter 38,
"Managing Identity Federation Partners".
39.2 Introduction to Federation Settings
This section introduces the federation settings that must be configured to enable the
Identity Federation functionality available from the Oracle Access Management
Console.
Figure 39–1 shows the Federations Settings page as it appears in the Oracle Access
Management Console. This page is the same whether you choose Identity Federation
Service Settings from the Welcome page, Configuration panel, or you display the
Federation section of the System Configuration tab and choose Federation Settings.
Managing General Federation Settings
39-2 Administrator's Guide for Oracle Access Management
Figure 39–1 Identity Federation Service Settings Page
Table 39–1 outlines the types of federation settings you can configure.
39.3 Managing General Federation Settings
This topic is divided as follows:
■About Managing General Federation Settings
■Managing General Federation Settings
39.3.1 About Managing General Federation Settings
You view and manage general federation properties on the Federation Settings page of
the console.
Table 39–1 Federation Settings in the Console
Elements Description
General General federation settings include basic information about
the provider and the keys used to send assertions.
See Also: Managing General Federation Settings
Proxy Proxy settings enable you to set up a proxy server for
federation.
See Also: Managing Proxy Settings for Federation
Keystore Keystore settings enable you to create aliases (a short hand
notation) for keys in the keystore.
See Also: Defining Keystore Settings for Federation
Managing Proxy Settings for Federation
Managing Settings for Identity Federation 39-3
Figure 39–1 shows the General section of the Federation Settings page. Table 39–2
describes each element on the General section of the Federation Settings page.
39.3.2 Managing General Federation Settings
General settings include basic information about a provider.
Prerequisites
None.
To set or modify General settings for Federation
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, Select Federation from the drop-down list in the
Settings section.
3. On the Federation Settings page, enter General Settings values for your
(Table 39–2).
4. Click Apply to save your changes.
5. Proceed to "Managing Proxy Settings for Federation".
39.4 Managing Proxy Settings for Federation
This topic is organized in the following sections.
■About Proxy Settings for Federation
■Managing Proxy Settings for Identity Federation
39.4.1 About Proxy Settings for Federation
A proxy may be required when Identity Federation needs to directly connect to the
federation partner, such as in a SAML artifact SSO operation. You view and manage a
proxy configured for use with federation partners on the Federation Settings page of
the console.
Table 39–2 General Federation Settings
Element Description
Provider ID This is the provider ID of this federation server. For example,
http://foo.example.com/fed
.
Signing Key This key is used to sign assertions.
Encryption Key This key is used to decrypt incoming messages.
Custom Trust Anchor File Specifies a keystore that contains trusted root certificates use in
federation. The default trust store is
$DOMAIN_HOME/config/fmwconfig/amtruststore
.
In most cases, the default trust anchor should be enough. If necessary,
specify the location of an alternate keystore to use.
Note: When you use a custom trust anchor keystore, it will not be
replicated automatically across the cluster. You must manage
replication of this keystore.
Export SAML 2.0 Metadata After changes to the General settings, you must export the metadata
for use by federation partners.
See Also: Exporting Metadata
Defining Keystore Settings for Federation
39-4 Administrator's Guide for Oracle Access Management
Figure 39–1 illustrates the Federation Proxy Settings section of the Federation Settings
page. Table 39–3 describes each element on the Federation Proxy Settings section of the
Federation Settings page.
39.4.2 Managing Proxy Settings for Identity Federation
Skip Step 1 if viewing the Federation Settings page.
Prerequisites
None.
To set or modify Proxy settings for Federation
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, Select Federation from the drop-down list in the
Settings section.
3. On the Federation Settings page, evaluate current proxy settings values against
those needed for your environment.
4. Fill in the Proxy settings using values for your environment (Table 39–3).
5. Click Apply to save your changes.
6. Proceed to "Defining Keystore Settings for Federation".
39.5 Defining Keystore Settings for Federation
This topic is organized in the following sections.
■About Managing Keytore Settings for Identity Federation
■Managing Identity Federation Encryption/Signing Keys
39.5.1 About Managing Keytore Settings for Identity Federation
You view and manage keystores configured for use with federation partners on the
Federation Settings page of the console. Figure 39–2 illustrates the expanded
Federation Proxy Settings section of the Federation Settings page.
Table 39–3 Federation Proxy Settings
Element Description
Enable Proxy Checking the box enables the proxy server.
When the box is unchecked, the Proxy function is disabled and related
fields are inaccessible for editing.
Host This element specifies the proxy hostname.
Port This element specifies the proxy port number.
Non-proxy Hosts This is a list of hosts for which the proxy should not be used. Use ';' to
separate multiple hosts.
Username This is the proxy user name to use when connecting to the proxy.
Password This is the proxy password to use when connecting to the proxy.
Defining Keystore Settings for Federation
Managing Settings for Identity Federation 39-5
Figure 39–2 Keystore Settings
Table 39–4 describes each element on the Keystore Settings section of the Federation
Settings page.
39.5.2 Managing Identity Federation Encryption/Signing Keys
As described in Chapter 5, Identity Federation uses keys in the following keystore to
store encryption and signing certificates:
$DOMAIN_HOME/config/fmwconfig/.oamkeystore
Task overview: Managing Identity Federation Encryption/Signing Keys
■Resetting the System (.oamkeystore) and Trust (amtruststore) Keystore Password
■Adding a New Key Entry to the System Keystore (.oamkeystore)
39.5.2.1 Resetting the System (.oamkeystore) and Trust (amtruststore) Keystore
Password
Use the following procedure to reset the password that protects the keystores as well
as the key entries which use the same password as the keystore.
Note that the keystores were created and configured by the IM/OAMAM/OSTS
installer, and the password and the key entries password were randomly generated.
Table 39–4 Keystore Settings for Federation
Element Description
Keystore Location This element specifies the keystore path.
Key ID This is the unique key ID.
Description This element provides a brief description of the key, such as its usage
type.
Alias This element specifies the key alias.
Note: You can choose one of the aliases that is available in the keystore
using the drop-down.
Password This element specifies the key password.
Note: AM denotes Access Manager, STS denotes Security Token
Service, and IF denotes Identity Federation in this discussion.
Defining Keystore Settings for Federation
39-6 Administrator's Guide for Oracle Access Management
The WLST
resetKeystorePassword
method allows you to set the .oamkeystore
password and any key entries with a password identical to the .oamkeystore password
to a new value. The command:
■updates the .oamkeystore password
■updates the key entries in the .oamkeystore which had the same password as the
keystore
■updates the OAMAM/STS/IF configuration to reflect the change
■updates the amtruststore password if the keystore is protected by the same
password as the .oamkeystore (default)
To set the system keystore (.oamkeystore) password:
1. Enter the WLST scripting environment.
2. Connect to the WebLogic Server AdminServer, using the
connect()
command.
3. Navigate to the domain runtime tree:
domainRuntime()
.
4. Execute the following command:
resetKeystorePassword()
5. Enter and confirm the password.
39.5.2.2 Adding a New Key Entry to the System Keystore (.oamkeystore)
You can add a new key entry into the system keystore (.oamkeystore) using the
keytool
command to create and add the new key entry. Once the entry has been
added, it must be defined in the Identity Federation settings configuration screen so
that it can be used to sign assertions and decrypt incoming messages.
This topic provides the following procedures to add a new entry to the system
keystore to sign SAML assertions or decrypt XML-encrypted data not covered by WSS:
■Adding a New Entry in the .oamkeystore
■Adding a New Entry in the Identity Federation Settings
■Configuring the Signing and Encryption Key
39.5.2.2.1 Adding a New Entry in the .oamkeystore
Prerequisites
The system keystore (.oamkeystore) password has been reset.
To configure a new entry:
1. Locate keytool.
2. Use keytool to:
■ generate a self-signed certificate, or
■generate a certificate request, export the request to a remote Certificate
Authority (CA), and finally import the certificate issued by the CA.
39.5.2.2.2 Adding a New Entry in the Identity Federation Settings
The steps are as follows:
1. In the Oracle Access Management Console, click Federation at the top of the
window.
Exporting Metadata
Managing Settings for Identity Federation 39-7
2. In the Federation console, Select Federation from the drop-down list in the
Settings section.
3. On the Federation Settings page, navigate to the Keystore table.
4. Add a row.
5. Enter a key ID that will be used to reference this key when configuring Identity
Federation.
6. Select the alias of the key entry stored in .oamkeystore.
7. Enter the key password.
8. Click Apply.
39.5.2.2.3 Configuring the Signing and Encryption Key
Once the key has been added to the keystore table, you can configure Identity
Federation to use the key. The steps are as follows:
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, Select Federation from the drop-down list in the
Settings section.
3. Navigate to the General section.
4. Select the Signing Key from the list of available key entries that were defined in
the keystore table.
5. Select the encryption key from the list of available key entries that were defined in
the keystore table.
6. Click Apply.
Identity Federation will now use those keys to sign and decrypt messages.
39.6 Exporting Metadata
After changes to the general settings, you can export the metadata for use by
federation partners.
To Export SAML 2.0 Metadata
Take these steps to export the metadata:
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, Select Federation from the drop-down list in the
Settings section.
3. On the Federation Settings page, click Export SAML 2.0 Metadata.
4. A dialog box appears where you must specify the file for the exported metadata.
5. Click Save to save your new metadata file.
Exporting Metadata
39-8 Administrator's Guide for Oracle Access Management
40
Managing Federation Schemes and Policies 40-1
40
Managing Federation Schemes and Policies
[28]
To enable Oracle Access Management Access Manager to work with federation
providers, you define one or more authentication schemes. The defined schemes will
authenticate users that request access to resources protected by Access Manager.
This chapter introduces authentication schemes and policies that may be configured
for Oracle Access Management Identity Federation.
■Using Identity Federation and Access Manager Together
■Using Authentication Schemes and Modules for Identity Federation 11g Release 2
(11.1.2.2)
■Using Authentication Schemes and Modules for Oracle Identity Federation 11g
Release 1
■Managing Access Manager Policies for Use with Identity Federation
■Testing Identity Federation Configuration
■Using the Default Identity Provisioning Plug-in
■Configuring the Identity Provider Discovery Service
■Configuring the Federation User Self-Registration Module
■Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
40.1 Using Identity Federation and Access Manager Together
The use of federation features within Access Manager varies depending on the release.
When integrating with Identity Federation:
■11g Release 1 (11.1.1) sites, and those upgrading from 11g Release 1 (11.1.1) to 11g
Release 2 (11.1.2), can use the integration described in Oracle Fusion Middleware
Integration Guide for Oracle Identity Management Suite.
■Sites with new 11g Release 2 (11.1.2) installations can leverage federation features
using the Oracle Access Management Console.
Note: For Identity Federation concepts, background and high-level
flows, see Chapter 3, Deploying Oracle Identity Federation, of Oracle
Fusion Middleware Administrator's Guide for Oracle Identity Federation
Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)
40-2 Administrator's Guide for Oracle Access Management
40.2 Using Authentication Schemes and Modules for Identity Federation
11g Release 2 (11.1.2.2)
This topic is divided as follows:
■About the FederationScheme Authentication Scheme
■About the FederationMTScheme
■About the FederationPlugin Authentication Module
■Managing Authentication with Identity Federation in 11g Release 2
40.2.1 About the FederationScheme Authentication Scheme
FederationScheme
is a general-purpose scheme for use with Identity Federation 11g
Release 2 (11.1.2.2). Figure 40–1 shows the Access Console page for
FederationScheme
:
Figure 40–1 FederationScheme
Table 40–1 describes the
FederationScheme
.
Table 40–1 FederationScheme Element Definitions
Element Description
Name This is the scheme name.
Description This is a brief description of the scheme.
Authentication Level This is the trust level of the authentication scheme.
Default This is a non-editable box that is checked when the Set as Default
button is clicked.
Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)
Managing Federation Schemes and Policies 40-3
40.2.2 About the FederationMTScheme
The
FederationMTScheme
authentication scheme is a scheme designed for use in
multi-tenancy environments.
40.2.3 About the FederationPlugin Authentication Module
FederationPlugin
provides a custom authentication module. Figure 40–2 is a screen
shot of the module’s Console page.
Figure 40–2 FederationPlugin Steps
Table 40–2 describes the attributes used to configure the FederationPlugin steps.
Challenge Method You may select a challenge method from those available in the
drop-down box.
Challenge Redirect URL This is the URL of another server to which user requests must be
redirected for processing.
Authentication Module This is the authentication module to use with the scheme.
Challenge URL This is the URL to which the credential collector will redirect for
credential collection. Not used by the federation plug-in.
Context Type This element is used to build the final URL for the credential collector.
Context Value This element is used to build the final URL for the credential collector.
The value depends on the context type.
Challenge Parameters This is the list of parameters, if any, to use with the challenge.
See Also: Table 22–21 for
FederationScheme
specifications.
Table 40–1 (Cont.) FederationScheme Element Definitions
Element Description
Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)
40-4 Administrator's Guide for Oracle Access Management
Orchestration enables you to specify the order of the steps within the plugin, and what
to do if each of those steps succeeds or fails. Figure 40–3 illustrates the orchestration of
the
FederationPlugin
, which is similar to the orchestration described in Table 22–14,
"Steps Orchestration Tab".
Figure 40–3 FederationPlugin Orchestration
Table 40–3 describes the attributes for the orchestration of the
FederationPlugin
.
40.2.4 Managing Authentication with Identity Federation in 11g Release 2
This section explains how to manage the
FederationScheme
; and
FederationPlugin
plug-in, a custom authentication module.
Prerequisites
None.
Table 40–2 FederationPlugin Steps
Element Description
Step Name This is the name of the step within the module.
Description This element contains a brief description of the step.
Plugin Name This element specifies the plugin associated with the step.
The value of FedSSOIdP is the IDP to be picked up by the authentication plugin.
Table 40–3 Orchestration of FederationPlugin
Element Description
Name This is the step name. The steps appear in this column in order
of execution, which can be modified with the Initial Step
drop-down.
Description This is a brief description of the step.
On Success This is the action to take upon successful completion of the
step, such as execution of next step in the orchestration.
On Error This is the action to take upon error, such as taking the
specified failure action.
On Failure This is the action to take upon step failure.
Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)
Managing Federation Schemes and Policies 40-5
To view or modify FederationScheme
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Schemes in the Access
Manager section.
3. Search for and open the
FederationScheme
authentication scheme.
4. Review
FederationScheme
details to ensure these are desired for your
deployment. Table 40–1 describes field details.
5. Click the Save button.
To view or modify FederationPlugin
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Plug-ins in the Plug-ins
section.
3. Search for and open the
FederationPlugin
authentication plug-in.
4. Review
FederationPlugin
details to ensure these are desired for your
deployment. Table 40–2 provides plugin step details.
5. Use the icons above the step table to add a step (+) or delete a step (x).
6. Modify the order of steps as needed using the Steps Orchestration tab. Table 40–3
provides orchestration details.
7. Click the Save button.
To Add an Authentication Policy with FederationScheme
Prerequisite: Any resource to be added to a policy must be defined within the same
Application Domain as the policy.
Take these steps to set up an authentication policy that uses
FederationScheme
, and
associate a resource that will be protected using this policy:
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Application Domains in the Access
Manager section.
3. Search for and open the target application domain.
4. In the application domain configuration page, click the Authentication Policies
tab.
5. Click Create and enter the following General Policy Details (Table 25–9,
" Authentication Policy Elements and Descriptions"):
■Name
■Authentication Scheme
6. Add these Global Policy Elements and Specifications:
■Description (optional)
■Success URL
■Failure URL
Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1
40-6 Administrator's Guide for Oracle Access Management
7. To add resources:
a. Click the Resources tab on the Authentication Policy page.
b. Click the Add button on the tab.
c. Choose a URL from the list.
d. Repeat these steps as needed to add more resources.
8. Click Apply to save changes and close the confirmation window.
9. Responses: See "Introduction to Policy Responses for SSO" on page 25-68 and
"Adding and Managing Policy Responses for SSO" on page 25-75.
Figure 40–4 shows the console page to define the authentication policy and associate
the policy to the resources.
Figure 40–4 Setting Up the Authentication Policy with FederationScheme
40.3 Using Authentication Schemes and Modules for Oracle Identity
Federation 11g Release 1
This section describes the authentication schemes and modules available for use with
the Oracle Identity Federation server in Oracle Fusion Middleware Release 11g R1
(11.1.1).
An authentication scheme is a named component that defines the challenge
mechanism required to authenticate a user. Each authentication scheme must also
include a defined authentication module.
■About Scheme OIFScheme
■About the OIFMTLDAPPlugin Authentication Module
Note: The schemes used for Identity Federation in 11g Release 2
(11.1.2.3) are described in Section 40.2.
See Also: For additional information about schemes, see
Section 22.9.
Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1
Managing Federation Schemes and Policies 40-7
■Managing Authentication with Oracle Identity Federation Release 11gR1
40.3.1 About Scheme OIFScheme
OIFScheme
and
OIFMTScheme
are used for integration with Oracle Identity Federation
11g Release 1 (11.1.1).
Figure 40–5 OIFScheme
Table 40–4 describes the scheme
OIFScheme
.
Note: See Section 40.2 for the schemes available with Identity
Federation 11g Release 2 (11.1.2.3).
Table 40–4 OIFScheme Definition
Element Description
Name This is the scheme name.
Description This is a brief description of the scheme.
Authentication Level This is the trust level of the authentication scheme.
Default This is a non-editable box that is checked when the Set as Default
button is clicked.
Challenge Method Use to select a challenge method from those available in the
drop-down box.
Challenge Redirect URL This is the URL of another server to which user requests must be
redirected for processing.
Authentication Module This is the authentication module to use with the scheme.
Challenge URL This is the URL the credential collector will redirect to for credential
collection.
Context Type Use this element to build the final URL for the credential collector.
Challenge Parameters This is the list of parameters, if any, to use with the challenge.
See Also: Table 22–21 for
OIFScheme
specifications.
Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1
40-8 Administrator's Guide for Oracle Access Management
40.3.2 About the OIFMTLDAPPlugin Authentication Module
The
OIFMTLDAPPlugin
module authenticates federated tenants through Identity
Federation and non-federated tenants with the identity store associated with Access
Manager.
Figure 40–6 OIFMTLDAPPlugin
Table 40–5 describes the steps for
OIFMTLDAPPlugin
.
40.3.3 Managing Authentication with Oracle Identity Federation Release 11gR1
This section explains how to manage
OIFScheme
; and
OIFMTLDAPPlugin
, a custom
authentication module for Identity Federation 11g Release 1 (11.1.1).
Prerequisites
None
To view or modify the OIFScheme Authentication Scheme
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
Table 40–5 OIFMTLDAPPlugin Steps
Element Description
Step Name This is the name of the step within the module.
Description This element contains a brief description of this step.
Plugin Name This element specifies the plugin associated with this step.
Plugin Parameters This element lists the parameters, if any, needed for plugin execution.
The parameter list varies with the plugin.
Managing Access Manager Policies for Use with Identity Federation
Managing Federation Schemes and Policies 40-9
2. In the Application Security console, click Authentication Schemes in the Access
Manager section.
3. Search for and open the
OIFScheme
authentication scheme.
4. Review
OIFscheme
details to ensure these are desired for your deployment. For
field details, see Table 40–4.
5. Click the Save button.
Prerequisites
None.
To view or modify the OIFMTLDAPPlugin Authentication Module
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Application Security console, click Authentication Modules in the Plug-ins
section.
3. Search for and open the
OIFMTLDAPPlugin
authentication module.
4. Review
OIFMTLDAPPlugin
details to ensure these are configured as desired for your
deployment. For field details, see Table 40–5.
5. Click the Save button.
To add an Authentication Policy with OIFScheme
The procedure for this task is the same as described in "To Add an Authentication
Policy with FederationScheme".
40.4 Managing Access Manager Policies for Use with Identity Federation
This section explains the use of policy responses in Access Manager in the context of
federation policies.
■About Policy Responses with Assertion Attributes for Identity Federation
■Defining Policy Responses with Assertion Attributes for Identity Federation
40.4.1 About Policy Responses with Assertion Attributes for Identity Federation
A policy can optionally contain one or more authentication responses, or authorization
responses, or both. You can configure the use of assertion attributes when setting up
Access Manager policy responses with Identity Federation.
You use assertion attributes in the following contexts:
■Authorization policy conditions
■Response attributes as HTTP headers
■Response attributes for identity context
Figure 40–7 shows the Response configuration tab for an authorization policy:
Managing Access Manager Policies for Use with Identity Federation
40-10 Administrator's Guide for Oracle Access Management
Figure 40–7 Authorization Policy Response Tab
Table 40–6 describes the elements for a policy response.
40.4.2 Defining Policy Responses with Assertion Attributes for Identity Federation
Use the Oracle Access Management Console to configure policy responses with
assertion attributes.
Background on Conditions and Responses for Identity Federation
Identity Federation conditions and responses must be specified separately because
they are used for different tasks.
A condition is used to control access to a resource within Access Manager.
For example, if the identity provider is sending a role assertion and the service
provider wished to only allow people who had a role of
sales
to access the resource,
you would add a condition wherein:
■the Condition Namespace would be "Session".
■the Name would be "fed.attr.role".
■the Operator is set to EQUALS.
Table 40–6 Policy Response Elements
Element Description
Name This is a unique name to distinguish this response from other
responses that use the same mechanism (type).
Type This is the mechanism used to convey the response form of the action
to be taken with the value string. Select Assertion Attribute.
Value This is the response expression, set as a variable. To provide the
federation data as response attributes in the authentication or
authorization policy, the values can reference:
■$session.attr.fed.nameidvalue for the name ID value
■$session.attr.fed.attr.AttributeName for any other assertion
attribute
Managing Access Manager Policies for Use with Identity Federation
Managing Federation Schemes and Policies 40-11
■value is "sales".
A response, on the other hand, enables you to pass an asserted attribute to the
application. For example, if you wanted to pass the asserted attribute
role
to a
back-end application in an HTTP header, you would:
■go to the Response tab.
■Add a Header, name
Role
(this is the name of the HTTP header).
■The value would be
$session.attr.fed.attr.role
.
Again, replace the role in this example to correspond to the actual SAML asserted
attribute.
Prerequisites
None.
To View or Configure Policy Responses with Assertion Attributes
1. Using the Oracle Access Management Console, search for the desired application
domain and open the desired policy to view or configure a response.
2. Select the Responses tab.
3. Click the relevant icon to add, delete or update a response.
4. When updating, review the response details to ensure these are desired for your
deployment. For field details, see Table 40–6.
5. Click the Save button.
Figure 40–8 shows an example of federation response attribute configuration:
Notes:
■Replace the role in this example to the actual SAML asserted
attribute.
■If you wanted to use the standard SAML NameID value as the
condition then the value would be "attr.fed.nameidvalue".
Testing Identity Federation Configuration
40-12 Administrator's Guide for Oracle Access Management
Figure 40–8 Adding a Federation Response Attribute to an AuthZ Policy
40.5 Testing Identity Federation Configuration
After performing the procedure described in the previous section, you have completed
all the steps to configure federation in SP mode. To recap, these steps are:
1. Enabling the Identity Federation service using Oracle Access Management
Console.
2. Creating an IdP partner or using an existing IdP partner.
3. Ensuring that IdP setup including SAML attributes, global logout, and nameID
format are configured.
4. Configuring an authentication/authorization policy that uses
FederationScheme
with federation response attributes; and
5. Protecting a resource with this policy.
To test this configuration, access the resource that is protected by the authentication
policy and verify that access is granted or denied according to the policy.
Test SP Module
Identity Federation provides a Test SP module which allows you to:
■test Federation SSO with an IdP Partner
■see the result of the Federation SSO operation as well as the assertion sent by the
Identity Provider
Follow these steps to enable or disable the Test SP Module:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
3. Move to the domain runtime location:
Testing Identity Federation Configuration
Managing Federation Schemes and Policies 40-13
domainRuntime()
4. Execute the following WLST command to enable the Test SP Module:
configureTestSPEngine("true")
5. Execute the following WLST command to disable the Test SP Module:
configureTestSPEngine("false")
To access the Test SP module and perform a federation SSO operation with an IdP
partner, perform the following steps:
1. Access the following service:
http(s)://oam-hostname:oam-port/oamfed/user/testspsso
2. Select the IdP with which to perform a federation SSO (note: only enabled IdP
partners are listed).
3. Start the federation SSO operation. The browser will be redirected to the IdP
Partner for authentication and redirected back to Identity Federation with a
federation response.
4. Identity Federation will process the federation assertion and the Test SP module
will display the result of the processing (note: no Access Manager session will be
created as a result of the operation).
Troubleshooting Error During Federation Configuration After Upgrade
IAM Suite is the OOTB Application Domain created when OAM 11.1.2 is installed.
This Application Domain can be renamed after installation but when upgrading OAM
to 11.1.2.2.0, it must be renamed back to IAM Suite otherwise the upgrade operation
will fail with the following error seen in the WLS admin logs.
java.lang.NullPointerException
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.FedR2PS2Bootstr
apHandler.createFedAuthnResource(FedR2PS2BootstrapHandler.java:505)
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.FedR2PS2Bootstr
apHandler.doBootstrap(FedR2PS2BootstrapHandler.java:151)
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.R2PS2BootstrapH
elper.doBootstrap(R2PS2BootstrapHelper.java:70)
at
oracle.security.am.common.policy.tools.PolicyComponentLifecycle.initialize(Pol
.
icyComponentLifecycle.java:99)
If the IAM Suite Application Domain has been renamed after installation, it is required
to rename it back to its original IAM Suite name prior to beginning the upgrade
process. After the upgrade process is complete, the name can be changed back to a
custom name.
Note: The Test SP Module should be disabled in a production
environment.
Using the Default Identity Provisioning Plug-in
40-14 Administrator's Guide for Oracle Access Management
40.6 Using the Default Identity Provisioning Plug-in
11g Release 2 (11.1.2.3) features a plug-in that you can optionally use to provision a
missing identity during a federated SSO operation.
■Why Use a Provisioning Plug-in?
■About the Default Provisioning Plug-in
■Using the Default Provisioning Plug-in
■Switching to a Custom Provisioning Plug-in
40.6.1 Why Use a Provisioning Plug-in?
When a federated SSO transaction is initiated, the processing flows as follows:
1. The IdP authenticates a user and sends an assertion to Oracle Access Management
Identity Federation.
2. Acting as SP, Identity Federation maps the user to the local identity store.
3. If the user does not exist in the local store, the mapping fails.
Resolving this issue requires the ability to provision the user so the transaction can
continue.
40.6.2 About the Default Provisioning Plug-in
To handle the identity mapping failure, Identity Federation supports the ability to set
up a plug-in, known as the default provisioning plug-in, to provision the missing user
in the identity store and enable the federated single sign-on to proceed.
The user is provisioned in the identity store associated with the IdP partner.
You can specify a list of attributes to use in provisioning the plug-in, as explained in
the next section.
40.6.3 Using the Default Provisioning Plug-in
You can enable this default provisioning plug-in from the plug-in configuration
interface. The steps are as follows:
1. From the plug-in configuration interface select
FedUserProvisioningPlugin
.
2. In the configuration parameters tab, set the following parameters:
■
KEY_USER_RECORD_ATTRIBUTE_LIST
- This is the list of attributes with which
the user should be provisioned. These attributes are available as part of the
assertion, for example:
mail
,
givenname
. (optional)
■
KEY_PROVIDERID_ATTRIBUTE_NAME
– This is the tenant ID attribute name in the
identity store which Identity Federation populates at run-time with the tenant
name. (optional)
■
KEY_USERID_ATTRIBUTE_NAME
– This is the attribute name to use for the
userid
value from the assertion attributes. (optional)
3. Enable user provisioning with the default plug-in by executing the WLST
command:
putBooleanProperty("/fedserverconfig/userprovisioningenabled","true")
Configuring the Identity Provider Discovery Service
Managing Federation Schemes and Policies 40-15
40.6.4 Switching to a Custom Provisioning Plug-in
A custom provisioning plug-in is also available with Identity Federation.
To switch from the default plug-in to the custom plug-in, follow the guidelines in
Developing a Custom User Provisioning Plug-in chapter of the Oracle Fusion
Middleware Developer's Guide for Oracle Access Management.
When using the custom plug-in, set the plug-in name with the WLST command:
putStringProperty("/fedserverconfig/userprovisioningplugin","CustomPlugin")
40.7 Configuring the Identity Provider Discovery Service
Identity provider discovery is a service that selects an identity provider (possibly
through interaction with the user) to use during SSO. While Identity Federation does
not provide an identity provider discovery service, it provides support for using such
a service to select an IdP, if one is not passed in the authentication request to the SP
during SP-initiated SSO.
For more information about IdP discovery refer to the specifications at:
http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery-c
s-01.pdf
When acting as a service provider, Identity Federation can be configured so that if an
SSO operation is initiated without the provider ID of the partner IdP, the user is
redirected to an IdP discovery service to select the identity provider with which to
perform SSO.
After the user selects an identity provider, the custom page resubmits the SSO request
with the chosen IdP to Identity Federation.
■Using the Bundled IdP Discovery Service
■Creating a custom IdP Discovery Service
■Disabling the use of an IdP Discovery Service
40.7.1 Using the Bundled IdP Discovery Service
Identity Federation provides a simple Identity Provider Discovery Service that can be
used to determine the Federation IdP Partner to be used at runtime during a
Federation SSO operation.
Follow these steps to configure IdP discovery:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
3. Move to the domain runtime location:
domainRuntime()
4. Execute the following WLST command to configure Identity Federation to use an
IdP Discovery Service:
putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "true")
Configuring the Identity Provider Discovery Service
40-16 Administrator's Guide for Oracle Access Management
5. Execute the following WLST command to configure Identity Federation to use the
default out-of-the-box IdP Discovery Service:
putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "true")
putStringProperty("/spglobal/idpdiscoveryserviceurl", "/oamfed/discovery.jsp")
40.7.2 Creating a custom IdP Discovery Service
You can configure Identity Federation to interact with a custom IdP Discovery Service
deployed remotely.
Follow these steps to configure Identity Federation to use a custom IdP discovery:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
3. Move to the domain runtime location:
domainRuntime()
4. Execute the following WLST command to configure Identity Federation to use an
IdP Discovery Service:
putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "true")
5. Execute the following WLST command to configure Identity Federation to use a
custom IdP Discovery Service (replace IDP_DISCOVERY_SERVICE_URL with the
fully qualified URL of the Discovery Service):
putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "false")
putStringProperty("/spglobal/idpdiscoveryserviceurl", "IDP_DISCOVERY_SERVICE_
URL")
At runtime, Identity Federation redirects to the IdP Discovery Service page with the
following parameters:
■
return
: This is the URL to which the page should send the new request containing
the chosen IdP provider ID to Identity Federation.
■
returnIDParam
: This is the name of the parameter to use to specify the chosen IdP
provider ID in the request sent to Identity Federation.
The discovery service gets the values of these parameters, displays a list of IdPs, and
sends a new request to Identity Federation specifying the chosen IdP Provider ID.
Example
The following is an example of an IdP discovery service page. This page allows the
user to select an identity provider (from the list of provider IDs: http://idp1.com,
http://idp2.com, http://idp3.com), and submit the chosen provider ID to Identity
Federation to continue the SSO flow.
Note: Check that the URL query parameter values are correctly
URL-encoded.
Configuring the Identity Provider Discovery Service
Managing Federation Schemes and Policies 40-17
<%@ page buffer="5kb" autoFlush="true" session="false"%>
<%@ page language="java" import="java.util.*, java.net.*"%>
<%
// Set the Expires and Cache Control Headers
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
// Set request and response type
request.setCharacterEncoding("UTF-8");
response.setContentType("text/html; charset=UTF-8");
String submitURL = request.getParameter("return");
String returnIDParam = request.getParameter("returnIDParam");
List idps = new ArrayList();
idps.add("http://idp1.com");
idps.add("http://idp2.com");
idps.add("http://idp3.com");
%>
<html>
<title>
Select an Identity Provider
</title>
<body bgcolor="#FFFFFF"><form method="POST" action="<%=submitURL%>" id="PageForm"
name="PageForm" autocomplete="off">
<center>
<table cellspacing="2" cellpadding="5" border="0" width="500">
<tr><td colspan="2" align="center">
Select an Identity Provider
</td></tr>
</tr>
<tr>
<td align="right">Provider ID</td>
<td>
<select size="1" name="<%=returnIDParam%>">
<%
Iterator idpIT = idps.iterator();
while(idpIT.hasNext())
{
String idp = (String)idpIT.next();
%>
<option value="<%=(idp)%>"><%=idp%></option>
<%
}
%>
</select>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="Continue"/>
</td>
</tr>
</table>
</center>
Configuring the Federation User Self-Registration Module
40-18 Administrator's Guide for Oracle Access Management
</form>
</body>
</html>
40.7.3 Disabling the use of an IdP Discovery Service
Follow these steps to configure Identity Federation to stop using an IdP discovery
service:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
3. Move to the domain runtime location:
domainRuntime()
4. Execute the following WLST command to configure Identity Federation to stop
using an IdP Discovery Service:
putBooleanProperty("/spglobal/idpdiscoveryserviceenabled", "false")
putBooleanProperty("/spglobal/idpdiscoveryservicepageenabled", "false")
putStringProperty("/spglobal/idpdiscoveryserviceurl", "/oamfed/discovery.jsp")
40.8 Configuring the Federation User Self-Registration Module
When Identity Federation is acting in Service Provider (SP) mode, the user assertion is
mapped to a local user record in the LDAP directory to complete the federated single
sign-on. If the mapping fails because the user performing the Federation SSO
operation does not have a local account, Identity Federation can be configured to
trigger a user self-registration flowto enable the user to create an account locally.
At runtime, when the Assertion mapping operation fails, if self-registration is enabled,
the user self-registration framework will:
■redirect the user to a self-registration page.
■the self-registration page will contain the following fields:
–username
–password
–confirm password
–first name
–last name
–email address
These fields might be pre-populated with data from the Assertion. Also, any field
used in the Assertion Mapping process cannot be edited: the user will not be able
to change the information used for the Assertion Mapping operation for security
reasons.
■Once the user creates the account, the Federation SSO flow will resume and result
with the creation of an Access Manager session. At that point, the user will be
redirected to the protected resource.
Configuring the Federation User Self-Registration Module
Managing Federation Schemes and Policies 40-19
Follow these steps to enable or disable the user self registration module:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
3. Move to the domain runtime location:
domainRuntime()
4. Execute the following WLST command to enable the user self-registration module:
putBooleanProperty("/fedserverconfig/userregistrationenabled", "true")
putStringProperty("/fedserverconfig/userregistrationurl",
"/oamfed/registration.jsp")
5. Execute the following WLST command to disable the user self-registration
module:
putBooleanProperty("/fedserverconfig/userregistrationenabled", "false")
putStringProperty("/fedserverconfig/userregistrationurl",
"/oamfed/registration.jsp")
You can configure Identity Federation to pre-populate the fields of the self-registration
page with the data contained in the Assertion. By default, the self-registration page
will populate those fields based on the following:
■first name: Identity Federation will use either the firstname or givenname
attributes contained in the Assertion. The userregistrationfirstnameattr
configuration property indicates the list of comma separated attributes that should
be used to populate this field. By default, that field is set to firstname,givenname.
■last name: Identity Federation will use either the lastname or sn attributes
contained in the Assertion. The userregistrationlastnameattr configuration
property indicates the list of comma separated attributes that should be used to
populate this field. By default, that setting is set to lastname,sn.
■email address: Identity Federation will use either the mail attribute contained in
the Assertion, or the Assertion's NameID (referenced by fed.nameidvalue). The
userregistrationemailattr configuration property indicates the list of comma
separated attributes that should be used to populate this field. By default, that
setting is set to mail,fed.nameidvalue.
■username: Identity Federation is not configured to use any Assertion attributes to
populate this field. The userregistrationusernameattr configuration property
indicates the list of comma separated attributes that should be used to populate
this field. By default, that setting is empty.
If the attributes or NameID are missing from the assertion, the fields will be empty.
To configure the userregistrationfirstnameattr, userregistrationlastnameattr,
userregistrationemailattr and userregistrationusernameattr properties:
1. Enter the WLST environment:
$OH/common/bin/wlst.sh
2. Connect to the Admin Server:
connect()
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
40-20 Administrator's Guide for Oracle Access Management
3. Move to the domain runtime location:
domainRuntime()
4. Execute the following WLST command to set the first name field rule:
putStringProperty("/fedserverconfig/userregistrationfirstnameattr",
"firstname,givenname")
5. Execute the following WLST command to set the last name field rule:
putStringProperty("/fedserverconfig/userregistrationlastnameattr",
"lastname,sn")
6. Execute the following WLST command to set the email address field rule:
putStringProperty("/fedserverconfig/userregistrationemailattr",
"mail,fed.nameidvalue")
7. Execute the following WLST command to set the username field rule:
putStringProperty("/fedserverconfig/userregistrationusernameattr",
"uid,fed.nameidvalue")
40.9 Integrating OAM Identity Provider With Microsoft Office 365 Service
Provider
This section describes how to administer OAM Identity Federation 11g R2PS2
(11.1.2.2.0) as an IdP for integration with Microsoft Office 365 when the latter is
configured as an SP leveraging the SAML 2.0 standard. After the integration
implementation, you can use an account in the Identity Repository to access all web
clients (including Office rich client apps connecting to SharePoint Online) and
email-rich clients that use basic authentication and a supported Exchange access
method such as IMAP, POP, Active Sync or MAPI. (The Enhanced Client Protocol end
point is required to be deployed). The deployment assumes:
1. OAM 11gR2PS2 has been installed and configured using SSL.
2. An account has been created using the Oracle Access Management Console that
defines the Administrator role for Office 365.
3. Windows PowerShell 2.0 and Microsoft Online Services Module have been
installed.
4. Get an available domain name to be used as the federated domain in Office 365.
Generally, this domain needs to be purchased.
The following sections contain the configuration details.
■Configuring Microsoft Office 365 for OAM Integration
Note: For non Web-based client integration:
■The OAM IdP endpoint must be accessible from the public
network.
■A trusted SSL certificate issued by a well known entity must be
used.
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
Managing Federation Schemes and Policies 40-21
■Configuring OAM for Microsoft Office 365 Integration
■Configuring Microsoft Office 365 for OAM Integration
40.9.1 Configuring Microsoft Office 365 for OAM Integration
Use the following procedure to configure Microsoft Office 365.
1. Add the domain name (for example, test.com) and verify it using the Office 365
Web administration center.
2. Define the authentication scheme for the domain as Federated by running the
Set-MsolDomainAuthentication
PowerShell command.
$dom="<domain name>"
$url="https://server_host:port/oamfed/idp/samlv20"
$uri="<entityID>"
$ecpUrl=https:// server_host:port/oamfed/idp/soap
$logouturl="https://server_host:port/oamfed/idp/samlv20"
$cert="MIIB/DCCAWWgAwIBAgI......."
Set-MsolDomainAuthentication -FederationBrandName $dom
-Authentication Federated -ActiveLogUri $ecpUrl -PassiveLogOnUri $url
-SigningCertificate $cert -IssuerUri $uri
-LogOffUri $logouturl -PreferredAuthenticationProtocol SAMLP
3. Create a user in the Federated domain by running the
New-MsolUser
PowerShell
command.
New-MsolUser -DisplayName <name> –UserPrincipalName
<name@domain_name> -UsageLocation <location>
-BlockCredential $false -ImmutableId <immutableid>
Values for UserPrincipalName and ImmutableId are required by Office 365 for
Federation. In the SAML assertion, the value of ImmutableId will be stored in the
SAML Subject using the "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
NameID format. The UserPrincipalName will be stored in the SAML Attribute
using the attribute name IDPEmail. In the OAM User Identity Store, the user entry
must use the same attributes to store the values of UserPrincipalName and
ImmutableId. Use the following:
■mail=<name@domain_name (UserPrincipalName)>
■uid=<immutableid>
4. Assign a license to the user to make the applications provided by Office 365
available to the user.
Note: The values for some of these parameters can be found in the
OAM Identity Provider metadata.
Note: If Office 365 has been before this integration, you can use an
existing user for testing. You must know the values of the
UserPrincipalName and ImmutableId attributes for the existing user.
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
40-22 Administrator's Guide for Oracle Access Management
40.9.2 Configuring OAM for Microsoft Office 365 Integration
Use the following procedures to configure OAM for integration with Microsoft Office
365.
■Configuring for Web and Non-Web Clients
■Additional Configurations for Non-Web Clients
40.9.2.1 Configuring for Web and Non-Web Clients
Use this procedure to configure for both Web and non-Web clients.
1. Log in to the Oracle Access Management Console.
2. Navigate to Available Services and enable the Identity Federation service.
3. Navigate to Identity Provider Administration.
4. Create a Service Provider Attribute Profile mapping.
5. Create a Service Provider Partner for Office 365 using the attributes and values
documented in Table 40–8.
Note: For details on how to use the WLST commands needed in this
procedure, see the Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.
Table 40–7 Message Attribute Mapping
Message Attribute Name Value Always Send
IDPEmail $user.attr.mail true
Table 40–8 Office 365 Service Provider Attribute Values
Name Office365
Protocol SAML 2.0
Service Details Load from provider metadata
Metadata File Can be downloaded from:
https://nexus.microsoftonline-p.com/federationmetadata/saml
20/federationmetadata.xml
For customers in China using the China-specific instance of
Office 365 download from:
https://nexus.partner.microsoftonline-p.cn/federationmetadata
/saml20/federationmetadata.xml
NameID Format persistent
NameID Value User ID Store Attribute + uid
Attribute Mapping Profile The profile created in step 2
User Identity Store Identity Store used
User Search Base DN The base DN for User search
SSO Response Binding HTTP POST
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
Managing Federation Schemes and Policies 40-23
6. Optionally, set the default Authentication Scheme for the service provider partner
using the setSPPartnerDefaultScheme WLST command.
By default, OAM uses LDAPScheme for user authentication. To use another
scheme, run the following command:
setSPPartnerDefaultScheme(<partner>, <authnScheme>)
See Section 40.9.2.2, "Additional Configurations for Non-Web Clients" if using
non-Web clients.
40.9.2.2 Additional Configurations for Non-Web Clients
Perform these additional configurations if using non-Web clients. These steps will not
impact Web-based integration.
1. Use the setSPPartnerAlternateScheme WLST command to set an alternative
Authentication Scheme for the Service Provider partner to handle HTTP Basic
authentication. For example:
setSPPartnerAlternateScheme(<partner>, "true",
httpHeaderName="X-MS-Client-Application", httpHeaderExpression=".*
Microsoft.Exchange..*", authnScheme="BasicScheme or BasicSessionlessScheme")
The values of httpHeaderName and httpHeaderExpression can be determined
from the HTTP request sent from Office365 to OAM. If you want to use other
values, use rich clients to connect the email account and capture the HTTP request
on OAM server side.
2. Use the updatePartnerProperty WLST command to update the configuration to
send certificates in XML signatures.
updatePartnerProperty(<partner>,"sp","includecertinsignature","true","boolean")
For Basic Authentication, you may need re-authentication even after the Request is
already authenticated.
40.9.3 Verifying Federation Single Sign-On
Use the procedures in this section to verify Federation SSO.
■Verifying SP-Initiated SSO
■Verifying IDP-Initiated SSO
■Verifying Non Web-based Clients
40.9.3.1 Verifying SP-Initiated SSO
Use this procedure to test SP-initiated SSO.
1. Open one of the following URLs.
■http://portal.microsoftonline.com: from login page, input "xxx@test.com" in
the user name field, then click the password field; at this time, you should be
automatically redirected to the OAM login page.
Note: It is recommended to use BasicSessionlessScheme because
Office 365 only validates user credentials to get an assertion.
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider
40-24 Administrator's Guide for Oracle Access Management
■http://www.outlook.com/test.com: you should be automatically redirected to
the OAM login page.
2. Enter a user name and password in the displayed OAM login page and click
Login.
If SSO is successful, you will be logged into the Office 365 Web portal.
40.9.3.2 Verifying IDP-Initiated SSO
Use this procedure to test IDP-initiated SSO.
1. Open
http://
host:port
/oamfed/idp/initiatesso?providerid=urn:federation:MicrosoftO
nline&returnURL=http://portal.microsoftonline.com in a browser.
2. Enter a user name and password in the displayed OAM login page and click
Login.
If SSO is successful, you will be logged into the Office 365 Web portal.
40.9.3.3 Verifying Non Web-based Clients
Use this procedure to test federation with non Web-based clients.
1. Add an Email account for an email client.
■For Desktop Email client like Outlook client, please refer to
http://help.outlook.com/en-ca/140/cc875899.aspx
■For Native Email app in Android device, please refer to
http://office.microsoft.com/client/15/help/preview?AssetId=HA102823196
&lcid=1033&NS=O365ENTADMIN&Version=15&CTT=5&origin=HA1037873
72
■For IOS device, please refer to
http://office.microsoft.com/client/15/help/preview?AssetId=HA102818554
&lcid=1033&NS=O365ENTADMIN&Version=15&CTT=5&origin=HA1028282
59
2. Check that you can send and receive email successfully.
Note: When adding an email account using the Outlook client, after
you input Your Name and Email Address in the User Information
area, it will auto-fill the User Name value in the Logon Information
area with the value of Your Name. You should change the value of
Your Name to reflect the email address.
Part X
Par t X
Managing Oracle Access Management
Security Token Service
Part VIII provides information to help Administrators manage the Security Token
Services available with Oracle Access Management.
Part VIII contains the following chapters:
■Chapter 41, "Introducing the Oracle Access Management Security Token Service"
■Chapter 42, "Security Token Service Implementation Scenarios"
■Chapter 43, "Configuring Security Token Service Settings"
■Chapter 44, "Managing Security Token Service Certificates and Keys"
■Chapter 45, "Managing Templates, Endpoints, and Policies"
■Chapter 46, "Managing Token Service Partners and Partner Profiles"
■Chapter 47, "Troubleshooting Security Token Service"
41
Introducing the Oracle Access Management Security Token Service 41-1
41
Introducing the Oracle Access Management
Security Token Service
[29]
The Oracle Access Management Security Token Service provides the foundation for
the security infrastructure, facilitating a consistent and streamlined model for token
acquisition, renewal, and cancellation that is protocol and security infrastructure
agnostic. It helps simplify the effort needed to bridge access to various systems by
using a standardized set of interfaces. Security Token Service facilitates Federated SSO
and Single Logout (SLO) for users accessing resources through a Web browser and
across different security domains or administrative boundaries.
The following sections contain introductory material regarding the Security Token
Service.
■Understanding the Security Token Service
■Using the Security Token Service
■Security Token Service Key Terms and Concepts
■Integrating the Oracle Web Services Manager
■Architecting the Security Token Service
■Security Token Service Supported Token Matrix
■Deploying Security Token Service
■Installing Security Token Service
■Administrating the Security Token Service
41.1 Understanding the Security Token Service
Security Token Service is a Web Service (WS) Trust-based token service that allows for
policy-driven trust brokering and secure identity propagation and token exchange
between Web Services. Security Token Service can be deployed as a Security and
Identity Service and used to simplify the integration of distributed or federated Web
services within an enterprise and its service providers.
Security Token Service brokers trust between a Web Service Consumer (WSC) and a
Web Service Provider (WSP) and provides security token lifecycle management
Note: Security Token Service is primarily based on the OASIS
WS-Trust protocol but it also delegates the processing of other WS-*
protocols present in the SOAP message.
Using the Security Token Service
41-2 Administrator's Guide for Oracle Access Management
services to both. It allows for the use of various federation protocols like SAML,
WS-Federation, Liberty, or OpenID.The Oracle Access Management Security Token
Service (Security Token Service) is deployed with Access Manager and must be
activated as a service.
41.2 Using the Security Token Service
Security Token Service is installed with Oracle Access Management 11g on Managed
Servers. Each Managed Server must be registered with Access Manager to open
communication channels. Security Token Service leverages the common infrastructure
for shared services and the Access Manager 11g administration model. All Security
Token Service system configuration is done using the Oracle Access Management
Console, providing a unified and consistent administration experience. Security Token
Service also inter-operates with third party security token servers.
Security Token Service is compliant and co-exists with Access Manager (using Access
Manager as the primary authenticator for Web clients requesting tokens). Security
Token Service also uses Oracle Web Services Manager Agents. WebGate is used as an
Agent for identity propagation. The WebGate must be registered with Access Manager
11g to open a communication channel. Security Token Service processing:
■Integrates with STS Audit events
■Publishes, in the Oracle Access Management Console and WLST scripts, available
Security Token Service methods to manage partner data
■Performs validation operations specific to the Security Token Service use cases and
configuration model
The Security Token Service 11g infrastructure is described in Table 41–1.
Note: Security Token Service adopts the same frameworks,
guidelines, and practices for diagnostics, monitoring, auditing, and
high availability used by Oracle Access Management 11g. For more
information, see Part III, "Logging, Auditing, Reporting and
Monitoring Performance".
Security Token Service Key Terms and Concepts
Introducing the Oracle Access Management Security Token Service 41-3
41.3 Security Token Service Key Terms and Concepts
Security tokens contain claims or statements that are used to assert trust. To secure
communication between a Web service client and a Web service, the two parties must
exchange security credentials. These credentials can be obtained from a trusted
Security Token Service.
Modern IT environments have numerous types of security tokens (most of them based
on browser cookies) for facilitating SSO and session management for Web
applications. These token types include Kerberos (primarily for Windows Native
Authentication), Security Assertion Markup Language (SAML) assertions, and even
digital certificates.
Table 41–2 identifies common Security Token Service terminology.
Table 41–1 Security Token Service 11g Infrastructure
Component Description
Default Trust Keystore Security Token Service private keys used for Signing/Encryption are stored in the common
keystore used with Access Manager. Security Token Service and Access Manager use the common
infrastructure certification validation module. Trusted Certificates and Certificate Revocation Lists
(CRLs) used during certificate validation are stored in Trust Keystore and CRL ZIP file. The
Security Token Service configuration stores the OCSP/CDP settings.
The token security key pair is populated to Access Manager/Security Token Service keystore.
Note: When the Oracle WSM Agent is used as the WS_Trust client in the Security Token Service
deployment, Oracle strongly recommends that the Oracle WSM Agent keystore and the Security
Token Service/Access Manager keystore always be different. Do not merge the two. Otherwise,
Access Manager/Security Token Service keys could be available to any modules authorized by
OPSS to access the keystore and Access Manager keys might be accessed.
See Also: "About Access Manager Keystores" on page 5-32.
Default User Identity Store Security Token Service authenticates and maps users against the User Identity stores configured
through the Common Configuration section of System Configuration in the Oracle Access
Management Console. Security Token Service maps the incoming token to user records and
attributes in the default User Identity Store, which operates with both Access Manager and
Security Token Service.
See Also: "Using the System Store for User Identities"
Certificates The certificates used by Security Token Service are self signed. The subject and the issuer field are
identical. Out of the box, the OAM Server hosting Security Token Service is uniquely identified:
■The keys and certificates used in Security Token Service are generated during installation.
The subject and issuer fields are linked to the host name. This applies to the signing and
encryption keys and certificates used by Security Token Service, as well as the
keys/certificates used by the OWSM Agent protecting Access Manager. The OWSM Agent is
the certified WS-Trust client that can be used to communicate with Security Token Service.
■The SAML Issuer settings are configured to refer to the host name of the local computer.
This ensures that two servers are not identical in terms of cryptographic materials and identifiers.
The trust granted to one server by third-party modules is not granted to the other server because
the identifiers and cryptographic keys differ. There are no identical keys, no identical identifiers,
and authorization policies are in denial mode.
Oracle Coherence Security Token Service integrates with the Oracle Coherence module to store and share run time
WS-Trust data across all the physical instances of Security Token Service. The UserNameToken
Nonce are stored in the Coherence store. This implementation supports the following
requirements, which might be specific to Security Token Service:
■Cleanup of timed out records
■Existence of the records limited to several minutes (< 30)
Note: To provide interoperable security tokens, the Security Token
Service must be trusted by both the Web service client and the Web
service.
Security Token Service Key Terms and Concepts
41-4 Administrator's Guide for Oracle Access Management
Table 41–2 Security Token Service Terms
Term Description
Security Token A security mechanism that protects messages using a token issued by a
trusted Secure Token Service for message integrity and confidentiality
protection. The issued tokens contain a key, which is encrypted for the server
and which is used for deriving new keys for signing and encrypting.
Service providers and consumers in potentially different managed
environments can use a single Security Token Service to establish a chain of
trust. The service does not trust the client directly, but instead trusts tokens
issued by a designated Security Token Service. The Security Token Service is
taking on the role of a second service with which the client must securely
authenticate.
Security Token Service A trusted third party in an explicit trust relationship with the server (and a
trust relationship with the client). Security Token Service is one example.
Secure Token Service A shared Web service that provides a standards-based consolidated
mechanism of trust brokerage between different identity domains and
infrastructure tiers.
The service implements the protocol defined in the WS-Trust specification by
making assertions based on evidence that it trusts, to whoever trusts it (or to
specific recipients). This protocol defines message formats and message
exchange patterns for issuing, renewing, canceling, and validating security
tokens.
To communicate trust, a service requires something to prove knowledge of a
security token or set of security tokens. An XML Signature binds the sender's
identity (or "signing entity") to an XML document, for example. The document
is signed using the sender's private key, the signature is verified using the
sender's public key.
Request Security Token
(RST)
Request for a security token.
Request Security Token
Response (RSTR)
Response generated by Security Token Service in response to the Request for
Security Tokens with claims for the requested user.
On Behalf Of (OBO) An OBO Request Security Token (RST) is used when only the identity of the
original client is important. An OBO RST indicates that the requestor wants a
token containing claims about only one entity:
■the external entity represented by the token in the
OnBehalfOf
element.
ActAs An
ActAs
RST requires composite delegation. The final recipient of the issued
token can inspect the entire delegation chain (not just the client). An
ActAs
RST indicates that the requestor wants a token that contains claims about
distinct entities:
■The requestor
■An external entity represented by the token in the
ActAs
element
Token Exchange The exchange of one security token for another. The requestor (in order to
invoke a web service) requires a particular token. It uses Security Token
Service to exchange the incoming token with a token required by the service.
Security Token Service Key Terms and Concepts
Introducing the Oracle Access Management Security Token Service 41-5
WS-Security Web Services Security (WS-Security) specifies SOAP security extensions that
provide confidentiality using XML Encryption and data integrity using XML
Signature.
The most prevalent security tokens used with WS-Security are Username,
X.509 Certificates, SAML assertions, and Kerberos tickets (all supported by
Oracle Web Service Manager).
WS-Security also includes profiles that specify how to insert different types of
binary and XML security tokens in WS-Security headers for authentication
and authorization purposes:
WS-* specifications often depend on each other. For example, WS-Policy is
used in conjunction with WS-Security. WS-* specifications also leverage
non-WS-* specifications; for example, WS-Security uses XML Encryption and
XML Signature.
For WS-Security, only SAML assertions are used. The protocols and bindings
are provided by the WS-Security framework.
Note: WS-Security, WS-Trust, WS-Policy have been transferred over to
standards bodies such as the Organization for the Advancement of Structured
Information Standards (OASIS) or the World Wide Web Consortium (W3C).
WS-Trust Web Services Trust Language (WS-Trust) is a specification that uses the secure
messaging mechanisms of WS-Security to facilitate trust relationships.
WS-Trust defines a request and response protocol that enables applications to
construct trusted SOAP message exchanges. Trust is represented through the
exchange and brokering of security tokens.
In a message exchange using WS-Security only, it is assumed that both parties
involved in the exchange have a prior agreement on which type of security
tokens they must use for sharing security information. However, there are
cases where these parties do not have such an agreement, as a result trust
must be established before exchanging messages. Trust between two parties
exchanging SOAP / WS-Security-based messages is established by
implementing the WS-Trust specification.
WS-Policy Web Services Policy (WS-Policy). Together with WS-Security, WS-Policy is
another key industry standard for Oracle Fusion Middleware security.
WS-Policy is used in conjunction with WS-Security. A web service provider
may define conditions (or policies) under which a service is to be provided.
The WS-Policy framework enables one to specify policy information that can
be processed by web services applications, such as Oracle Web Services
Manager.
A policy is expressed as one or more policy assertions representing a web
service's capabilities or requirements. For example, a policy assertion may
stipulate that a request to a web service be encrypted. Likewise, a policy
assertion can define the maximum message size that a web service can accept.
Certificates The certificates used by Security Token Service are self signed. The subject and
the issuer field are identical. Out of the box, the OAM Server hosting Security
Token Service is uniquely identified:
Keystore Security Token Service key stores include:
■System Keystore
■Trust Keystore
■Partner Keystore
See Also: Chapter 44, "Managing Security Token Service Certificates and Keys"
User Name Token (UNT) Identifies the requestor by their username, and optionally using a password
(or shared secret, or password equivalent) to authenticate that identity. When
using a username token, the user must be configured in the Default User
Identity Store.,
Table 41–2 (Cont.) Security Token Service Terms
Term Description
Integrating the Oracle Web Services Manager
41-6 Administrator's Guide for Oracle Access Management
41.4 Integrating the Oracle Web Services Manager
In the 11g release, Oracle Web Services Manager (WSM) security and management has
been integrated into the Oracle WebLogic Server along with Oracle WSM Agent
functionality. Table 41–3 describes the WSM components.
X.509 Certificates A signed data structure designed to send a public key to a receiving party. A
certificate includes standard fields such as certificate ID, issuer's Distinguished
Name (DN), validity period, owner's DN, owner's public key, and so on.
Certificates are issued by certificate authorities (CA), for example Verisign. A
CA verifies an entity's identity and grants a certificate, signing it with the CA's
private key. The CA publishes its own certificate which includes its public key.
Each network entity has a list of the certificates of the CAs it trusts. Before
communicating with another entity, a given entity uses this list to verify that
the signature of the other entity's certificate is from a trusted CA.
Security Assertion
Markup Language
(SAML)
SAML Assertion
An open framework for sharing security information on the Internet through
XML documents. SAML provides:
■Assertions that define authentication and authorization information.
■Protocols to ask (SAML Request) and get (SAML Response) the
assertions you need.
■Bindings that define how SAML Protocols ride on industry-standard
transport (HTTP for instance) and messaging frameworks (SOAP for
instance).
■Profiles that define how SAML Protocols and Bindings combine to
support specific use cases.
For WS-Security, only SAML assertions are used. However, the protocols and
bindings are provided by the WS-Security framework.
SAML assertions can include three types of statements:
■Authentication statement: issued by an authentication authority upon
successful authentication of a subject. It asserts that Subject S was
authenticated by Means M at Time T.
■Attribute statement: issued by an attribute authority, based on policies. It
asserts that Subject S is associated with Attributes A, B, etc. with values a,
b, and so on.
■Authorization decision statement (deprecated in SAML 2.0, now
supported by XACML): issued by an authorization authority which
decides whether to grant the request by Subject S, for Action A (read,
write, and so on.), to Resource R (e.g., a file, an application, a web
service), given Evidence E.
Kerberos A cross-platform authentication and single sign-on system. The Kerberos
protocol provides mutual authentication between two entities relying on a
shared secret (symmetric keys). Kerberos authentication requires a client, a
server, and a trusted party to mediate between them called the Key
Distribution Center (KDC). Also required:
■A Principal: An identity for a user (a user is assigned a principal), or an
identity for an application offering Kerberos services.
■A Realm is a Kerberos server environment, which can be a domain name
such as EXAMPLE.COM (by convention expressed in uppercase). Each
Kerberos realm has at least one Web Services Security KDC.
The Kerberos Token profile of WS-Security allows business partners to use
Kerberos tokens in service-oriented architectures (SOAs).
See Also: "About Access Manager Security Keys and the Embedded
Java Keystore"
Table 41–2 (Cont.) Security Token Service Terms
Term Description
Integrating the Oracle Web Services Manager
Introducing the Oracle Access Management Security Token Service 41-7
Table 41–3 Integrated Oracle Web Services Manager
Component Description
Java Keystore (JKS) Required to store the signature and encryption keys required by the X.509 token on the client. JKS
the proprietary keystore format defined by Sun Microsystems. Trusted certificates and public and
private keys are stored in the keystore. To create and manage the keys and certificates in the JKS,
use the keytool utility. Keys are used for a variety of purposes, including authentication and data
integrity.
If the client and Web service are in the same domain with access to the same keystore, they can
share the same private/public key pair:
■The client can use the private key
orakey
to endorse the signature of the request message and
the public key
orakey
to encrypt the symmetric key.
■The Web service in turn uses the public key
orakey
to verify the endorsement, and the
private key
orakey
to decrypt the symmetric key.
Policy Interceptors In Oracle Fusion Middleware 11g, Oracle WSM Agents are managed by the security and
management policy interceptors. Policy Interceptors enforce policies, including reliable messaging,
management, addressing, security, and Message Transmission Optimization Mechanism (MTOM).
The Oracle WSM Agent manages the enforcement of policies using the Policy Interceptor Pipeline.
For complete Oracle Web Services Manager details, including the differences between release 10g
and 11g, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
Oracle WSM Agent The OWSM agent is the certified WS-Trust client that can be used to communicate with Security
Token Service. The OWSM agent is embedded and used by Security Token Service for message
protection only (to publish WS Policy and to enforce message protection on inbound and
outbound WS messages). Security Token Service performs token validation/request
authentication.
■Security Token Service embedded Oracle WSM Agent is used in the mode of "Message
Protection Only" with authentication functionality disabled. This way all aspects related to
authentication of incoming token are performed by Security Token Service only.
■Oracle WSM supports disabling of authentication using configuration overrides that Security
Token Service must declare with each policy.
Exception: The Kerberos token is handled by Oracle WSM and Security Token Service is
involved in mapping only the identity.
■The OWSM Agent is one of the certified WS-Trust clients that can be used to communicate
with Security Token Service. Other 3rd party WS-Trust clients can be used to interact with
Security Token Service.
Note: Embedded means that the OWSM Agent is available as part of the JRF layer on the
WebLogic Server that Security Token Service uses:
Message/Token Protection Security Token Service/Access Manager manages its own keystore and trust store.
For Oracle WSM to enforce message protection for Security Token Service, the OWSM key store is
seeded with its own self-signed certificate; passwords for its corresponding keys are stored in CSF.
It does not work with Security Token Service keystore.
Note: Conversely, Oracle WSM requires Access Manager/Security Token Service to store keys
related to message protection in the OPSS Keystore. For cases where the client uses schemes such
as SKI, Thumbprint, and so on to refer to its certificate, Oracle WSM requires that client
certificate(s) are present in the OPSS Keystore.
Token Signing Key Security Token Service has strong security requirements around its token signing key and uses the
token signing key to broker trust between a client and a relying party. Therefore, this key must be
stored in an exclusive partition that only Security Token Service can access.
Security Key Pairs Security Token Service creates separate key pairs for issued token security and message security to
provide security of token signing keys and eliminate the need for Oracle WSM agents to work
with Access Manager/Security Token Service keystore:
■The message security key pair is populated to OPSS Keystore
■The token security key pair is populated to Access Manager/Security Token Service keystore
OPSS Keystore The message security key pair is populated to OPSS Keystore. For special cases where clients use
referencing schemes such as SKI (not a certificate token being received as part of the Web service
request), Security Token Service populates OPSS Keystore with the requesting party's certificates.
This is an uncommon scenario. Security Token Service can provide instructions on manually
provisioning the keys to OPSS keystore to make it work.
Architecting the Security Token Service
41-8 Administrator's Guide for Oracle Access Management
41.5 Architecting the Security Token Service
Security Token Service is a centralized token service that supports WS-Trust protocol.
It also defines extensions to the WS-Security specification for issuing and exchanging
security tokens and establishing trust relationships. The Security Token Service is
hosted as a web service endpoint and coordinates security based interactions between
a WSC and a WSP. All communication with the Security Token Service occurs through
a WS_Trust client, as shown in Figure 41–1.
Figure 41–1 Security Token Service Architecture
When a WSC makes a call to the WSP, it gets the WS-Security policy that will indicate
that a security token issued by Security Token Service should be presented. The policy
will contain the location of the Security Token Service, and the WSC will use that
location to contact the Security Token Service to retrieve the token expected by the
WSP. (Alternately, the WSP could register its acceptable security mechanisms with the
Security Token Service and, before validating the incoming SOAP request, check with
the Security Token Service to determine its security mechanisms). When an
authenticated WSC (carrying credentials that confirm either the identity of the end
user or the application) requests a token for access to a WSP, the Security Token
Service verifies the credentials and, in response, issues a security token that provides
proof that the WSC has been authenticated. The WSC presents the security token to the
WSP which verifies that the token was issued by a trusted Security Token Service.
41.6 Security Token Service Supported Token Matrix
Figure 41–2 documents the token support matrix for Security Token Service.
Figure 41–2 Security Token Service Token Support
Deploying Security Token Service
Introducing the Oracle Access Management Security Token Service 41-9
41.7 Deploying Security Token Service
This section provides overviews of different deployment options:
■Centralized Token Authority Deployment
■Tokens Behind a Firewall Deployment
■Web Services SSO Deployment
41.7.1 Centralized Token Authority Deployment
The need for a token exchange for security integration between Web SSO and Web
service security tiers is in demand in a deployment where a Web application makes
internal or external Web service calls. An example of this is an intranet portal
integration with an external Web service provided by a partner or another
organization within the same company. The portal needs a way to securely access the
service but the difficulty of security integration in this case stems from the fact that the
Web SSO tier and WS tier use different methods of user authentication.
In the Web SSO environment, the Web application can accept WAC-issued session
tokens (SMSESSION, OBSSO), SAML assertions or proprietary tokens to authenticate
the users. The WS* security tier also uses a variety of standard and proprietary tokens
and, in most cases, local translation of token is required to achieve integration between
the two tiers. Additionally, the WS performing the translation must contact the
authority by which the token was issued (Oracle Adaptive Access Manager) to
decompose the token before it can be translated. Decomposition requires every WS
service to maintain trust with WAC systems; this is complex and not very secure
because of multiple trust links that need to be maintained. With the introduction of
Security Token Service, the translation of tokens can be done at the centralized
authority as illustrated in Figure 41–3.
Figure 41–3 Token Translation at a Centralized Authority
41.7.2 Tokens Behind a Firewall Deployment
The situation when applications rely on special form of credentials for their business
logic is very common in deployments of Oracle access products. Integrations of WAC
See Also: "Scenario: Identity Propagation with the Access Manager
Token" on page 42-2
Deploying Security Token Service
41-10 Administrator's Guide for Oracle Access Management
systems with both Oracle and custom applications almost always require extensive
coding for:
1. Decomposing tokens issued by one token authority (such as OAM or SiteMinder)
by calling a proprietary vendor API (SM agent API or ASDK).
2. Composing a new token format (PSFT, Siebel), that the application requires for its
internal business logic.
Although such translations are often handled through application coding, it introduces
the risk of exposing user names and passwords when the code is deployed on multiple
application instances in the DMZ. Thus, Security Administrators need an ability to
control the translation process by externalizing it from the application. Introducing the
Security Token Service provides significant relief in this situation. Security Token
Service plays the role of a centralized token authority, performing token translation
behind the firewall, as shown in Figure 41–4.
Figure 41–4 Translating Tokens Behind a Firewall
Application 1 and Application 2 are protected by Access Manager. Application 2 relies
on a different type of token for its internal business logic. It has a client-side connector
that contacts Security Token Service for exchanging the OBSSO token for a username
token. The Security Token Service relies on Access Manager for decomposing the
OBSSO token and generates the new token required by Application 2. This is more
secure, because the same authority (Access Manager) performs both operations
(composing and decomposing the OBSSO token) thus, there is no need to decompose
the token on the application side.
41.7.3 Web Services SSO Deployment
As in the Web SSO case, Web services SSO is a convenience feature. The difference is
that in the case of Web SSO the party who benefits from the feature is a user; in the WS
SSO environment, the Security Administrator benefits.
With Web services SSO different Web services have different token requirements (that
change often). Externalizing the exchange to Security Token Service enables the
application to simply supply the target and the current token in its possession.
Security Token Service takes charge of determining the token type for each requested
service. When one or more Web services change their authentication requirements,
Security Token Service can seamlessly verify the token type submitted by the
application. If the token is not of the requested type, the old token is revoked and the
new one of the correct type is issued. Figure 41–5 illustrates Web services SSO.
Installing Security Token Service
Introducing the Oracle Access Management Security Token Service 41-11
Figure 41–5 Web Services SSO
41.8 Installing Security Token Service
This section provides an overview of the installation options:
■Security Token Service Cluster in Single WLS Domain
■Endpoint Exposure through a Web Server Proxy
■Security Token Service Installation Overview
■Post-Installation Tasks: Security Token Service
41.8.1 Security Token Service Cluster in Single WLS Domain
This installation option leverages clustering across Security Token Service instances
deployed in different managed servers within a single WebLogic domain. This
deployment topology facilitates High Availability capabilities through a load balancer.
By default, Access Manager co-exists on the same managed server as Security Token
Service. However, Security Token Service is disabled by default and must be manually
enabled before it can be used. This deployment topology supports:
■Deploying multiple instances of Security Token Service through the suite installer.
■Deploying a load balancer to support the High Availability and failover scenarios
on the front of the Security Token Service cluster.
For more information, see the Oracle Fusion Middleware High Availability Guide.
41.8.2 Endpoint Exposure through a Web Server Proxy
This installation option provides inter-operability of Requester and Relying Party with
Third-party STS Servers. At runtime, Security Token Service supports interoperability
with Requesters and Relying Parties of third-party security token servers using the
OPSS WS-Trust-Provider. For instance, a third-party Security Token Service can create
a valid SAML Assertion that can be consumed by Security Token Service.
Administrating the Security Token Service
41-12 Administrator's Guide for Oracle Access Management
41.8.3 Interoperability of Requester and Relying Party with Other Oracle WS-Trust
based Clients
All run-time scenarios for Requesters and Relying Parties are supported by other
Oracle WS-Trust Clients, including WLSClient, MetroClient, and Oracle Web Services
Manager (Oracle WSM). All Web services clients are supported with Security Token
Service only through the WS-Trust binding.
41.8.4 Security Token Service Installation Overview
Access Manager and Security Token Service are installed together from a single EAR
file and deployed on the same managed server in a WebLogic domain. The Oracle
WSM Agent uses a keystore for various cryptographic operations. For those tasks, the
Oracle WSM Agent uses the keystore configured for Oracle WSM tasks. During
installation, if the Oracle WSM keystore service has not been configured, the installer:
■Creates a new keystore in the $DOMAIN_HOME/config/fmwconfig folder
(default name is default-keystore.jks
■Creates a key entry with the corresponding certificate to be used by OWSM for
signature and encryption operations. This key entry is stored in the OWSM
Keystore under the
orakey
alias
■Stores the passwords of the key entry and of the keystore in CSF
Having access to the keystore is sometimes required to:
■Extract the signing or encryption certificate to distribute to clients, if needed
■Update or replace the signing or encryption key entry
■Add trusted certificates
For more information, see the Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management.
41.8.5 Post-Installation Tasks: Security Token Service
Any server hosting Security Token Service must be registered with Access Manager.
This can occur automatically during installation, or manually after installation.
All Security Token Service system configuration is done using the Oracle Access
Management Console. Elements in the Oracle Access Management Console enable
Administrators to easily configure the Security Token Service to exchange WS Trust
tokens with partners. Other Security Token Service elements provide for creation,
viewing, modification, and removal of partners, endpoints, validation templates,
issuance templates, and data store connections.
For more details on the Security Token Service, see Part X, "Managing Oracle Access
Management Security Token Service".
41.9 Administrating the Security Token Service
During initial deployment, using the Oracle Fusion Middleware Configuration
Wizard, the Administrator userID and password are set. Administrators can log in and
use the Oracle Access Management Console (and WebLogic Server Administration
Console). A single LDAP group, the WebLogic Server "Administrators" group, is set by
default. For more information, see Chapter 2, "Getting Started with Oracle Access
Management".
42
Security Token Service Implementation Scenarios 42-1
42
Security Token Service Implementation
Scenarios
This chapter introduces several Security Token Service implementation and processing
scenarios. Regardless of scenario specifics, there are many similarities in both
configuration tasks and token handling. This chapter provides the following sections:
■Prerequisites
■Typical Token Ecosystem
■Scenario: Identity Propagation with the Access Manager Token
■Scenario: Web Service Security With On Behalf Of Username Token
42.1 Prerequisites
"Introducing the Oracle Access Management Security Token Service" on page 41-1.
42.2 Typical Token Ecosystem
The abstract model chosen here is of interest because of the requirements placed on
Security Token Service to support such models.
The phrase security token ecosystem is used here to represent a typical environment
where security tokens are in use. In such environments the security token, based on
the security model required for the environment, could be used to serve an end goal
such as to enable brokered trust or single-sign-on and so on. Regardless of the
environment and the type of security token, several aspects are common across all
models, as shown and described here.
Figure 42–1 illustrates a typical token ecosystem, which includes: Token Issuing
Authority, Token Requestor, Token Consumer, and the Security Token.
Scenario: Identity Propagation with the Access Manager Token
42-2 Administrator's Guide for Oracle Access Management
Figure 42–1 Typical Token Ecosystem
Actors and Process overview: In a typical token ecosystem
1. The Token Requestor places a request for a security token at the Token Issuing
Authority.
This security token is required to communicate and request access to a service
provided by a Service Provider (a Token Consumer who accepts the security
token).
■A Token Requestor could be a Partner of the Token Issuing Authority
(generally registered with the Token Issuing Authority).
■A Token Requestor could be an End User (generally not registered with the
Token Issuing Authority).
2. The Token Issuing Authority (Access Manager and Security Token Service, for
example) receives and processes the security token request and returns a security
token, as follows:
■Authenticate the input credentials.
■Authorize the security token request based on a Token Issuance Policy that
specifies which Token Requestors are authorized to request a security token
for a given Token Consumer.
3. The Token Consumer (typically a service provider).
■Accepts the security token as part of the service request and provides service
based on the validity of the input security token.
■Validates the input security token with Token Issuing Authority.
42.3 Scenario: Identity Propagation with the Access Manager Token
This is a deployment where the user's Identity information needs to be propagated
from a Web application to a Web service provider. The Web service provider can reside
in the same security domain as the web application or in a different security domain.
Note: A Token Consumer is typically a registered Partner of the
Token Issuing Authority. A Token Consumer is also known as a
Relying Party, because it trusts and relies on the Token Issuing
Authority for Token Requestor authentication. Token Consumers
(Relying Party Partner) are Web Applications (for Access Manager,
Security Token Service is the Token Issuing Authority) or STS Relying
Party Web Services.
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-3
Figure 42–2 Identity Propagation with the OAM Token
Identity propagation means that the original user context becomes visible outside its
original security tier or domain boundaries. The user security context is propagated
across different security tiers or domains to support tier-specific or domain-specific
security needs such as step-up authentication, authorization, audit and/or internal
application-specific business logic.
ID Propagation is said to occur in a distributed processing of a request when the
identity context established in the first node is propagated to subsequent nodes to
enable further processing of the request in the context of that identity.
ID Propagation can be achieved in several ways. One of them is based on a
brokered-trust model where an ID provider acts as a trust-broker for ID Assertions.
The discussion here is pertains to this model.
Figure 42–3 illustrates an ID Propagation scenario in a brokered-trust model, where a
user-facing application needs to request processing by a backend service application in
the context of the end user. To bring out the main aspects of ID propagation all other
interaction and relationship details between end user, application, and backend service
application are ignored.
Figure 42–3 Process Flow During Identity Propagation
Actors and Process overview: Identity Propagation
1. The ID Assertion Token Requestor (an End User-Facing Application), upon end
user access, requests authentication and ID Assertion Token at the identity
Provider.
2. The ID Provider (Security Token Service) processes the request and returns an
Authentication Token and an ID Assertion Token. An ID Assertion Token, in itself,
Note: Examples of ID Assertion Token Requestors include Web
applications that are protected by OAM. The ID Assertion Token
request could be either implicit or could be driven by a policy at the
ID Provider.
Scenario: Identity Propagation with the Access Manager Token
42-4 Administrator's Guide for Oracle Access Management
does not represent a user session and cannot be used independently to request
direct access to a resource or service.
3. The ID Assertion Token Requestor uses this Token later, during the end user
session, as part of a backend service processing request (on behalf of the end user).
4. The ID Assertion Token Consumer (Security Token Service), as part of the request
processing, first validates the ID Assertion Token and then (on validation success)
processes the request in the context of the end user Identity
For more information, see the following topics:
■Component Processing: Identity Propagation with the OAM Token
■Request Security Token Attributes and Run Time Processing
■Configuration Requirements: Identity Propagation with the OAM Token
42.3.1 Component Processing: Identity Propagation with the OAM Token
Figure 42–4 illustrates a typical deployment topology for Identity propagation using
Security Token Service with Access Manager.
Figure 42–4 Identity Propagation Deployment
Figure 42–5 illustrates a processing of Identity propagation using Security Token
Service with Access Manager. Details follow the figure.
Figure 42–5 Identity Propagation Processing
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-5
Process overview: Component interactions for Identity Propagation
1. User attempts to access a protected resource.
2. WebGate is protecting the resource; it sends request to Access Manager for
authentication and authorization.
3. Access Manager authenticates the user using the policy configured for this
WebGate Application Domain. It sees the response type "IDENTITY_ASSERTION"
is configured for this Webgate, so it generates ID Assertion token as well.
4. Access Manager sends authentication and ID assertion token to WebGate
5. WebGate processes the response; sets ID assertion token to the header; (OHS
where WebGate is installed on) then redirect the request to the WLS that hosts the
resource.
6. IAP (Access Manager Identity Asserter on WebLogic Server) sees OAM_
IDENTITY_ASSERTION header is set, processes the headers, then sets ID
assertion token to Subject's private credential as
OamIdentity
.
7. When the resource is finally accessed, a Web Service Client can then obtain the ID
assertion token from current user's Subject, generates a OnBehalfOf (OBO) token
with it, then creates and sends Request Security Token (RST) to Security Token
Service.
8. Security Token Service sees the ID assertion Token inside OBO token, it sends
validation/authentication request to Access Manager using Access Manager
library.
9. Access Manager validates and authenticates the ID Assertion Token, then sends
response (user identity) to Security Token Service.
10. Security Token Service uses this user identity to do further processing: policy
evaluation, token issuance, and so on. It then generates Request Security Token
Response.
11. Security Token Service sends Request Security Token Response to the client, which
can then use the token inside the Request Security Token Response (RSTR) to
create a web service request to access a service hosted on a relying party.
42.3.2 Request Security Token Attributes and Run Time Processing
For an incoming Request Security Token (RST) with the following attributes, Security
Token Service must be configured to process a request and issue a token):
RST Attributes for Identity Propagation with the OAM Token
■The SOAP header contains a Username token referencing a WS Requester. The
Username token contains at least a username and a password.
■The SOAP body contains a WS-Trust RST message
■The RST contains a OAM ID Propagation token in the OnBehalfOf field
referencing a user in LDAP. The token included in the OnBehalfOf element is a
BinarySecrityToken, whose text value is the Base 64 encoded format of the OAM
Session Propagation Token, and whose ValueType attribute is
http://something.example.com/am/2012/11/token/session-propagation
and
whose EncodingType attribute is
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soapmessage-sec
urity-1.0#Base64Binary
Scenario: Identity Propagation with the Access Manager Token
42-6 Administrator's Guide for Oracle Access Management
■The RST can possibly contain an AppliesTo field holding a URL pointing to the
endpoint of the Relying Party Web Service
■The RST can possibly contain a TokenType field holding the type of token that
needs to be returned
■The RST can possibly contain an Entropy field holding random data that will be
used when creating the SecretKey when a symmetric proof key is required in the
SAML Assertion
■The RST can possibly contain a UseKey field holding the certificate or public key
to be used as an asymmetric proof key in the SAML Assertion, but this field will
be ignored by Security Token Service
Process overview: Identity Propagation with the OAM Token
1. Client prepares the request by:
a. Creating the SOAP message
b. Creating the Username token referencing the client and including it in the
SOAP header
c. Creating the WS-Trust RST message
d. Creating the OAM ID Propagation token referencing the user and including it
in the OnBehalfOf field of the RST
e. Including the RST message in the SOAP body
2. Client sends the message to the Security Token Service, to an endpoint protected
by a WS-Security User Name Token (UNT) Policy, with that endpoint being
mapped to an Security Token Service WSS Validation Template.
3. Security Token Service will process the incoming request
4. Security Token Service validates the token included in the SOAP header by using
the settings contained in the WS-Security Validation Template:
a. Validates the format of the Username token
b. Validates the credentials contained in the Username token against the Security
Token Service Partner store, thus mapping this token to a Requester Partner
c. Knowing the Requester Partner, Security Token Service will retrieve the
Requester Partner Profile associated with this Requester
5. Security Token Service then validates the token present in the OnBehalfOf field:
a. Determines the type of token present in the OnBehalfOf field
b. Retrieves the WS-Trust Validation Template to be used for OAM Token Type,
from the Requester Partner Profile
c. Validates the format of the OAM token
d. Validates the OAM token, and maps the token to a user
e. Creating the OAM ID Propagation token referencing the user and including it
in the OnBehalfOf field of the RST
6. Security Token Service then examines the AppliesTo field:
■If present, Security Token Service will attempt to map the AppliesTo URL to a
Relying Party Partner, using the WS Endpoint Mapping of the Relying Party
Partner. If the mapping is successful, then the AppliesTo field has been
mapped to a Relying Party Partner, and Security Token Service will retrieve
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-7
the Relying Party Partner Profile from this Partner. If mapping was not
successful, then the AppliesTo field could not be mapped to a Relying Party
Partner, and Security Token Service will retrieve the Default Relying Party
Partner Profile from the Requester Partner Profile.
■If absent, Security Token Service will retrieve the Default Relying Party
Partner Profile from the Requester Partner Profile.
7. Security Token Service then examines the TokenType field:
■If present, Security Token Service will map the TokenType string to a local
token type value using the Requester Partner Profile, and it will then use the
Relying Party Partner Profile to retrieve the Issuance Template to be used to
create the outgoing token.
■If absent, Security Token Service will retrieve the default token type from the
Relying Party Partner Profile, and it will then use the Relying Party Partner
Profile to retrieve the Issuance Template to be used to create the outgoing
token.
8. Security Token Service will perform an Authorization evaluation to check that the
Requester Partner is authorized to request a token for the Relying Party referenced
in the flow (see Authorization Trust Policy for more information)
9. Security Token Service will then create the token:
■If the token to be issued is of SAML type, then the Issuance Template will list
how to populate the NameID, the Relying Party Partner Profile will list which
attributes need to be sent in the token, the Issuance Template will indicate
whether or not to translate the names and values of the attributes, the Issuance
Template will indicate whether or not to sign/encrypt the token.
■If the token to be issued if of SAML type, the Security Token Service server
will examine the KeyType to determine the Subject Confirmation Method of
the Assertion. If it is missing, it will use the Default Confirmation Method
from the Issuance Template.
10. Security Token Service will create the Response that the client will process:
a. Creates the WS-Trust RSTRC
b. Includes the returned token
c. Includes proof key if necessary
42.3.3 Configuration Requirements: Identity Propagation with the OAM Token
This topic walks through the configuration requirements for the identity propagation
scenario. It includes:
■Configuration overview: Identity Propagation with the OAM Token
■WebLogic Server Identity Assertion Providers
■Access Manager Identity Asserter Details
■LDAP Authentication Provider Details
■Default Identity Store Configuration
■Token Issuance Policy
■Authentication Policy Response for Identity Assertion by Webgate
■Endpoint Configuration
Scenario: Identity Propagation with the Access Manager Token
42-8 Administrator's Guide for Oracle Access Management
■Issuance Template Configuration
■Partner Configuration: Requester
■Partner Profile: Relying Party
■Partner Profile: Requester
■Validation Template for WS-TRUST
■Cookies and Headers (Truncated)
■Request Security Token Sent By the Client (Truncated)
■Request Security Token Response sent by the Security Token Service (Truncated)
Configuration overview: Identity Propagation with the OAM Token
Following is an overview of the Identity Propagation environment and
implementation tasks:
■A custom application module that will act as a client to:
–Retrieve the OAM Session Propagation token from the HTTP request
–Send a WS-Trust request to the Security Token Service server with Access
Manager Session Propagation token as the OnBehalfOf element
■A web application that will be protected by Webgate and will invoke the client
web application that will send a WS-Trust request to Security Token Service
■Security Token Service URL: http://myhost.domain.com:14100/sts/<endpoint>
■An OHS 11g with Webgate protecting the web application
Provision (register) a Webgate (11g or 10g) to protect the application deployed in
WebLogic Server. The
OAMSuite
Application Domain is pre-seeded and delivered
with Access Manager 11g. When you provision an OAM Agent to use this (or
another existing) Application Domain, decline the option of having policies
automatically created.
Reverse Proxy mapping for Webgate in the OHS Server mod_wl_ohs.conf, is
shown here.
The following Security Token Service configuration is required to implement token
processing for identity propagation:
■One Requester Partner Profile
■One Relying Party Partner Profile
■One Issuance Template
■One WS-Trust Validation Template
Note: Replace <endpoint> with the path configured in the STS
Endpoints section.
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-9
■Security Token Service Endpoint
■An LDAP server is required for Security Token Service to map the Username token
referencing the user to an LDAP User record, and thus use that record to populate
the outgoing token.
Ensure that the desired LDAP server is configured as the Default Identity Store.
WebLogic Server Identity Assertion Providers
Deploy the Identity Assertion Providers war. The Access Manager Identity Asserter is
available in the following path with Oracle Fusion Middleware installed:
$ORACLE_HOME/modules/oracle.oamprovider_11.1.1/oamauthenticationprovider.war
Copy oamauthenticationprovider.war to the following location:
$BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
provider.war
Figure 42–6 illustrates the required WebLogic Server Identity Assertion Providers
configuration for this scenario.
Figure 42–6 Required v1.0 WebLogic Server Identity Assertion Providers
Access Manager Identity Asserter Details
The IAP-Security Token Service identity asserter must be the first, and set using the
REQUIRED Control flag. The Active Types should be set as ObSSOCookie and OAM_
REMOTE_USER, with an SSO Header name of OAM_REMOTE_USER1.
Figure 42–7 illustrates the configuration.
Scenario: Identity Propagation with the Access Manager Token
42-10 Administrator's Guide for Oracle Access Management
Figure 42–7 IAP-Security Token Service Details
LDAP Authentication Provider Details
Create the Authenticator for the LDAP with the OPTIONAL JAAS flag. This will point
to the Default System Store of Oracle Access Management, which provides the Access
Manager token.
Figure 42–8 illustrates this.
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-11
Figure 42–8 LDAP Provider: IAP-DSEE
Default Identity Store Configuration
Figure 42–9 illustrates the Default Identity Store configuration within Oracle Access
Management Console.
Scenario: Identity Propagation with the Access Manager Token
42-12 Administrator's Guide for Oracle Access Management
Figure 42–9 Default Identity Store Defined in Access Manager
Token Issuance Policy
Create the Token Issuance Policy for the resource URL within the IAM Suite
Application Domain. Figure 42–10 is a screenshot of the Token Issuance Policy page.
Figure 42–10 Token Issuance Policy for Identity Propagation
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-13
Authentication Policy Response for Identity Assertion by Webgate
Identity Assertion is required for ID propagation for any issued token from Access
Manager that represents an end user (and possibly its OAM session).
The Identity Assertion Token is generated and returned as a policy response (HTTP
HEADER named "OAM_IDENTITY_ASSERTION" with a value as a SAML token)
after a successful authentication.
Security Token Service clients that are Web applications protected by Access Manager
requesting tokens to gain proxy access to a Relying Party (ID Propagation use case) are
required to pass an OAM Identity Assertion token that represents the end user.
The ID Provider (Access Manager) processes the request and returns an
Authentication Token and an ID Assertion Token. An ID Assertion Token, in itself,
does not represent a user session and cannot be used independently to request direct
access to a resource or service.
The ID Assertion Token Requestor uses this Token later, during the end user session,
as part of a backend service processing request (on behalf of the end user).
The ID Assertion Token Consumer (Security Token Service), as part of request
processing, first validates the ID Assertion Token and then (on validation success)
processes the request in the context of the end user Identity.
Confirm that the Identity Assertion box is checked as part of the Authentication Policy
Response within the IAM Suite Application Domain. This enables Webgate to perform
Identity Assertion for protected resources.
As you add each Response, you might be informed that
Identity Assertion has not
been enabled for this policy. Enable Identity Assertion in order to
collect Assertion Attribute type responses (when this policy is executed)
.
Endpoint Configuration
The /wss10user Endpoint is needed, as shown in Figure 42–11. This endpoint is
protected by the default WS-Security Validation Template. This is the one that will be
used in the Web application to post the RST.
Figure 42–11 /wssuser Endpoint for Identity Assertion
Issuance Template Configuration
The Issuance Template requires the following configuration for Identity Propagation:
■Name: iap-issuance-template
■Description: Custom issuance template
See Also: "Introduction to Policy Responses for SSO" on page 25-68.
See Also: "Adding and Managing Policy Responses for SSO" on
page 25-75.
Scenario: Identity Propagation with the Access Manager Token
42-14 Administrator's Guide for Oracle Access Management
■Token Type: SAML 2.0
■Signing Key Id: osts_signing
■Description: Custom issuance template
Partner Configuration: Requester
Create a new Requester Partner configuration for Identity Propagation with the OAM
token as follows:
■Partner Name: iap-request-partner
■Requester Type: STS_REQUESTER
■Partner Profile: iap-requestor-profile
■Description: Custom requester
■Trusted
■Username Token Authentication
–Username <enter username used by the Web Service Client>
–Password <enter password used by the Web Service Client>
–Confirm Password <enter password used by the Web Service Client>
■Identity Attribute values for:
–httpbasicusername
–sslclientcertdn
Partner Profile: Relying Party
Create a new Relying Party Profile for Identity Propagation as follows:
■Profile ID: iap-relyingparty-profile
■Description: iap-issuance-template
■Default Token Type: SAML 2.0
■Default Template: iap-issuance-template
Partner Profile: Requester
Create a new Requester Profile for Identity Propagation as follows:
■Profile ID: iap-requestor-profile
■Description: iap-requestor-profile partner profile
■Default Relying Party Profile: iap-relyingparty-profile
Validation Template for WS-TRUST
The Validation Template requires the following configuration for Identity Propagation:
■Validation Template Name: iap_wstrust_validation_template
■Description: iap_wstrust_validation_template
■Token Protocol: WS-Trust
■Token Type: OAM
■Timestamp Lifespan:
Scenario: Identity Propagation with the Access Manager Token
Security Token Service Implementation Scenarios 42-15
This completes the configuration requirements for the Identity Propagation with OAM
Token scenario.
42.3.4 Testing Your Implementation
Following configuration, you can try to access the resource to confirm your
implementation is working properly.
Webgate should redirect to the OAM Server if there is no existing session for the user
Upon successful authentication, you should be able to see the RST and RSTR sent by
the STS server.
Cookies and Headers (Truncated)
Request Security Token Sent By the Client (Truncated)
Here is a (truncated) request for security token sent by the client.
Request Security Token Response sent by the Security Token Service
(Truncated)
Here is a (truncated) response to the RST sent by the Security Token Service.
Scenario: Web Service Security With On Behalf Of Username Token
42-16 Administrator's Guide for Oracle Access Management
42.4 Scenario: Web Service Security With On Behalf Of Username Token
This section provides the following topics:
■Component interactions for Identity Propagation with Username Token
■RST Attributes and Processing for Identity Propagation with a Username Token
■Configuration Requirements: Identity Propagation with the Username Token
42.4.1 Component interactions for Identity Propagation with Username Token
Process overview: Component interactions for Identity Propagation
1. User attempts to access a protected resource.
2. User is authenticated.
3. The WebLogic container sets the user's identity into a Subject for this session.
4. When the resource is finally accessed, a Web Service Client can then obtain the
user's identity from current user's Subject, generates a OnBehalfOf (OBO) token
with it, then creates and sends Request Security Token (RST) to Security Token
Service.
5. Security Token Service authenticates the Web Service Client as a Requester Partner.
6. Security Token Service sees the Username Token inside OBO token, it maps the
maps the user's identity to a user record in LDAP.
7. Security Token Service then generates Request Security Token Response.
8. Security Token Service sends Request Security Token Response to the client, which
can then use the token inside the Request Security Token Response (RSTR) to
create a web service request to access a service hosted on a relying party.
42.4.2 RST Attributes and Processing for Identity Propagation with a Username Token
For an incoming Request Security Token (RST) with the following attributes, Oracle
Security Token Service must be configured to process a request and issue a token.
RST Attributes for Identity Propagation with a Username Token
■The SOAP header contains a Username token referencing a WS Requester. The
Username token contains at least a username and a password.
■The SOAP body contains a WS-Trust RST message.
■The RST contains a Username Token in the OnBehalfOf field referencing a user in
LDAP.
■The RST can possibly contain an AppliesTo field holding a URL pointing to the
endpoint of the Relying Party Web Service.
■The RST can possibly contain a TokenType field holding the type of token that
needs to be returned.
■The RST can possibly contain an Entropy field holding random data that will be
used when creating the SecretKey when a symmetric proof key is required in the
SAML Assertion.
■The RST can possibly contain a UseKey field holding the certificate or public key
to be used as an asymmetric proof key in the SAML Assertion, but this field will
be ignored by Security Token Service.
Scenario: Web Service Security With On Behalf Of Username Token
Security Token Service Implementation Scenarios 42-17
Process overview: Identity Propagation with the OAM Token
1. Client prepares the request by:
■Creating the SOAP message
■Creating the Username token referencing the client and including it in the
SOAP header.
■Creating the WS-Trust RST message.
■Creating the Username Token referencing the user and including it in the
OnBehalfOf field of the RST.
■Including the RST message in the SOAP body.
2. Client sends the message to the Security Token Service, to an endpoint protected
by a WS-Security User Name Token (UNT) Policy, with that endpoint being
mapped to an Security Token Service WSS Validation Template.
3. Security Token Service will process the incoming request.
4. Security Token Service validates the token included in the SOAP header by using
the settings contained in the WS-Security Validation Template:
■Validates the format of the Username token.
■Validates the credentials contained in the Username token against the Security
Token Service Partner store, thus mapping this token to a Requester Partner.
■Knowing the Requester Partner, Security Token Service will retrieve the
Requester Partner Profile associated with this Requester.
5. Security Token Service then validates the token present in the OnBehalfOf field:
■Determines the type of token present in the OnBehalfOf field.
■Retrieves the WS-Trust Validation Template to be used for Username Token
Type, from the Requester Partner Profile.
■Validates the Username Token, and maps the token to a user.
6. Security Token Service then examines the AppliesTo field:
■If present, Security Token Service will attempt to map the AppliesTo URL to a
Relying Party Partner, using the WS Endpoint Mapping of the Relying Party
Partner. If the mapping is successful, then the AppliesTo field has been
mapped to a Relying Party Partner, and Security Token Service will retrieve
the Relying Party Partner Profile from this Partner. If mapping was not
successful, then the AppliesTo field could not be mapped to a Relying Party
Partner, and Security Token Service will retrieve the Default Relying Party
Partner Profile from the Requester Partner Profile.
■If absent, Security Token Service will retrieve the Default Relying Party
Partner Profile from the Requester Partner Profile.
7. Security Token Service then examines the TokenType field:
■If present, Security Token Service will map the TokenType string to a local
token type value using the Requester Partner Profile, and it will then use the
Relying Party Partner Profile to retrieve the Issuance Template to be used to
create the outgoing token.
■If absent, Security Token Service will retrieve the default token type from the
Relying Party Partner Profile, and it will then use the Relying Party Partner
Profile to retrieve the Issuance Template to be used to create the outgoing
token.
Scenario: Web Service Security With On Behalf Of Username Token
42-18 Administrator's Guide for Oracle Access Management
8. Security Token Service will perform an Authorization evaluation to check that the
Requester Partner is authorized to request a token for the Relying Party referenced
in the flow (see Authorization Trust Policy for more information).
9. Security Token Service will then create the token:
■If the token to be issued is of SAML type, then the Issuance Template will list
how to populate the NameID, the Relying Party Partner Profile will list which
attributes need to be sent in the token, the Issuance Template will indicate
whether or not to translate the names and values of the attributes, the Issuance
Template will indicate whether or not to sign/encrypt the token.
■If the token to be issued if of SAML type, the Security Token Service server
will examine the KeyType to determine the Subject Confirmation Method of
the Assertion. If it is missing, it will use the Default Confirmation Method
from the Issuance Template.
10. Security Token Service will create the Response that the client will process:
■Creates the WS-Trust RSTRC
■Includes the returned token
■Includes proof key if necessary
42.4.3 Configuration Requirements: Identity Propagation with the Username Token
This topic walks through the configuration requirements for the identity propagation
scenario. It includes:
■Configuration overview: Identity Propagation with the Username Token
■Default Identity Store Configuration
■Token Issuance Policy
■Endpoint Configuration
■Issuance Template Configuration
■Partner Configuration: Requester
■Partner Profile: Relying Party
■Partner Profile: Requester
■Validation Template for WS-TRUST
■Example 42–1, "Sample exchange: Request Security Token Sent By the Client"
■Example 42–2, "Request Security Token Response sent by the Security Token
Service"
Configuration overview: Identity Propagation with the Username Token
Following is an overview of the Identity Propagation environment and
implementation tasks:
■A web application where the user will request. This web application will
authenticate the user, then attempt to send a SOAP message to a remote Web
Service Provider. As part of that SOAP exchange, the WS-Security client will
download the WS-Security policy of the Web Service Provider, connect to the
Security Token Service to retrieve the token requested by the Web Service Provider,
send the Security Token with the SOAP message to the Web Service Provider.
■Security Token Service URL: http://myhost.domain.com:14100/sts/<endpoint>
Scenario: Web Service Security With On Behalf Of Username Token
Security Token Service Implementation Scenarios 42-19
The following Security Token Service configuration is required to implement token
processing for identity propagation:
■One Requester Partner Profile
■One Relying Party Partner Profile
■One Issuance Template
■One WS-Trust Validation Template
■Security Token Service Endpoint
■An LDAP server is required for Security Token Service to map the Username token
referencing the user to an LDAP User record, and thus use that record to populate
the outgoing token.
■Ensure that the desired LDAP server is configured as the Default Identity Store for
Access Manager.
Default Identity Store Configuration
Figure 42–12 illustrates the Default Identity Store configuration within Oracle Access
Management Console.
Figure 42–12 Default Identity Store Defined for Access Manager
Token Issuance Policy
Create the Token Issuance Policy for the resource URL within the IAMSuite
Application Domain. Figure 42–13 is a screen shot of the Token Issuance Policy page.
Note: Replace <endpoint> with the path configured in the STS
Endpoints section.
Scenario: Web Service Security With On Behalf Of Username Token
42-20 Administrator's Guide for Oracle Access Management
Figure 42–13 Token Issuance Policy for Identity Propagation
Endpoint Configuration
The /wss11user Endpoint is needed, as shown in Figure 42–14. This endpoint is
protected by the default WS-Security Validation Template. This is the one that will be
used in the Web application to post the RST.
Figure 42–14 /wss11user Endpoint for Identity Assertion
Issuance Template Configuration
The Issuance Template requires the following configuration for Identity Propagation:
■Name: saml-issuance-template
■Description: SAML issuance template
■Token Type: SAML 2.0
■Signing Key Id: osts_signing
Partner Configuration: Requester
Create a new Requester Partner configuration for Identity Propagation with the OAM
token as follows:
■Partner Name: requester-partner
■Partner Type: Requester
■Partner Profile: requester-profile
■Description: Requester
Scenario: Web Service Security With On Behalf Of Username Token
Security Token Service Implementation Scenarios 42-21
■Trusted
■Username Token Authentication
–Username <enter username used by the Web Service Client>
–Password <enter password used by the Web Service Client>
–Confirm Password <enter password used by the Web Service Client>
■Identity Attribute values for:
–httpbasicusername
–sslclientcertdn
Partner Profile: Relying Party
Create a new Relying Party Profile for Identity Propagation as follows:
■Profile ID: relying-party-profile
■Description: Relying Party Profile
■Default Token Type: SAML 2.0
■Issuance Template: iap-issuance-template for SAML 2.0
Partner Profile: Requester
Create a new Requester Profile for Identity Propagation as follows:
■Profile ID: requester-profile
■Description: Requester Partner Profile
■Default Relying Party Profile: relying-party-profile
Validation Template for WS-TRUST
The Validation Template requires the following configuration for Identity Propagation:
■Validation Template Name: username_wstrust_validation_template
■Description: Username WS-Trust Template
■Token Protocol: WS-Trust
■Token Type: Username
■Timestamp Lifespan: 600
■Enable Credential Validation: unchecked
■Token Mapping:
–Map Token To User: checked
–Enable Simple User Mapping: checked
–Datastore Attribute: uid
This completes the configuration requirements for the Identity Propagation with
Username Token scenario.
Example 42–1 Sample exchange: Request Security Token Sent By the Client
Here is a request for security token sent by the client.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
Scenario: Web Service Security With On Behalf Of Username Token
42-22 Administrator's Guide for Oracle Access Management
<SOAP-ENV:Header><wsse:Security
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd">
<wsse:UsernameToken><wsse:Username>requester-test</wsse:Username><wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profi
le-1.0#PasswordText">welcome1</wsse:Password></wsse:UsernameToken></wsse:Security>
<wsa:Action
xmlns:wsa="http://www.w3.org/2005/08/addressing">http://docs.oasis-open.org/ws-sx/
ws-trust/200512/RST/Issue</wsa:Action></SOAP-ENV:Header>
<SOAP-ENV:Body><wst:RequestSecurityToken
xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"><wst:RequestType>http
://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
<wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAM
LV1.1</wst:TokenType><wst:OnBehalfOf>
<wsse:UsernameToken
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd"><wsse:Username>user-alice</wsse:Username>
</wsse:UsernameToken></wst:OnBehalfOf></wst:RequestSecurityToken></SOAP-ENV:Body><
/SOAP-ENV:Envelope>
Example 42–2 Request Security Token Response sent by the Security Token Service
Here is a response to the RST sent by the Security Token Service.
<env:Envelope
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Header><Action
xmlns="http://www.w3.org/2005/08/addressing">http://docs.oasis-open.org/ws-sx/ws-t
rust/200512/RSTRC/IssueFinal</Action>
</env:Header><env:Body><wst:RequestSecurityTokenResponseCollection
xmlns:ns6="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd" xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-util
ity-1.0.xsd">
<wst:RequestSecurityTokenResponse><wst:TokenType>http://docs.oasis-open.org/wss/oa
sis-wss-saml-token-profile-1.1#SAMLV1.1</wst:TokenType><wst:RequestedSecurityToken
><saml:Assertion AssertionID="id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-"
IssueInstant="2011-04-22T18:48:05Z" Issuer="myhost.uk.example.com"
MajorVersion="1" MinorVersion="1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:enc="http://www.w3.org/2001/04/xmlenc#"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Conditions NotBefore="2011-04-22T18:48:05Z"
NotOnOrAfter="2011-04-22T19:48:05Z"/><saml:AttributeStatement><saml:Subject><saml:
NameIdentifier
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">user-alice@example
.com</saml:NameIdentifier><saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</saml:Confi
rmationMethod></saml:SubjectConfirmation>
</saml:Subject><saml:Attribute AttributeName="sn"
AttributeNamespace="urn:oracle:security:fed:attrnamespace"><saml:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xsi:type="xs:string">user-alice-last</saml:AttributeValue></saml:Attribute>
</saml:AttributeStatement><dsig:Signature><dsig:SignedInfo><dsig:CanonicalizationM
ethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<dsig:SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><dsig:Reference
URI="#id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-"><dsig:Transforms><dsig:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
Scenario: Web Service Security With On Behalf Of Username Token
Security Token Service Implementation Scenarios 42-23
<dsig:Transform
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></dsig:Transforms><dsig:Diges
tMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<dsig:DigestValue>1GF2ZT9h+gs8sxyO+/yG/N6jxk8=</dsig:DigestValue></dsig:Reference>
</dsig:SignedInfo>
<dsig:SignatureValue>InZVb5aRM5+KKI1VqXg9HiIgLjKyGm0VkD6sMJ/8SIbFbbxuNm7Mnky5W35p2
P0c5bCPRx02uzLEE4KhLkyM2GsLsVaDNkRztGMphQW/Mcg7DprJIEyR2OYMYDOQSipa/k2K98C4zO/RNiv
o1KvyJsd6a3h6CBHwoO1RKip039w=</dsig:SignatureValue>
<dsig:KeyInfo><dsig:X509Data><dsig:X509Certificate>MIIB/DCCAWWgAwIBAgIBCjANBgkqhki
G9w0BAQQFADAjMSEwHwYDVQQDExhhZGMyMTEwNjE4LnVzLm9yYWNsZS5jb20wHhcNMTEwNDE5MTUxNTI2W
hcNMjEwNDE2MTUxNTI2WjAjMSEwHwYDVQQDExhhZGMyMTEwNjE4LnVzLm9yYWNsZS5jb20wgZ8wDQYJKoZ
IhvcNAQEBBQADgY0AMIGJAoGBAJnSxVc86TGcwewieaueIVG33C3Qouve6HuJxHsoM8cRRkJcmv+0auyvD
LJfYAEOfHo5OsF4+za11iNPln9ZFaOjUy/Y8JC0kSVxatgU36RveIrpOJvp978Oa6IlMNUtdFf8q3Trsiz
spE2hnbLY+0SMofgnAPcJEKPxkd6b0b0ZAgMBAAGjQDA+MAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/BAUDA
wfYADAdBgNVHQ4EFgQU47ZqWHgTOmZO67uw4YzsbrRMNOswDQYJKoZIhvcNAQEEBQADgYEAH0QIHaLMN/7
hD2VP0SLOCtNdEmY5IqLY1CDW+GpUZZ9e+MCgE/rvr34566D9Q8lvET6T9u+sg3h+hSkb3gE4a4wgShH/V
7nfHzx8ZntlxccvCZK6ePVDMt0Lfj2iVnE7IJxou4bO0w0m9DrvyKop7ncnSEzaVpxIZgCDo7+8Zdw=</d
sig:X509Certificate>
</dsig:X509Data></dsig:KeyInfo></dsig:Signature></saml:Assertion></wst:RequestedSe
curityToken><wst:RequestedAttachedReference><wsse:SecurityTokenReference><wsse:Key
Identifier
ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAss
ertionID">id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-</wsse:KeyIdentifier></wsse:SecurityToken
Reference></wst:RequestedAttachedReference>
<wst:RequestedUnattachedReference><wsse:SecurityTokenReference><wsse:KeyIdentifier
ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAss
ertionID">id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-</wsse:KeyIdentifier></wsse:SecurityToken
Reference></wst:RequestedUnattachedReference>
<wst:Lifetime><wsu:Created>2011-04-22T18:48:05Z</wsu:Created><wsu:Expires>2011-04-
22T19:48:05Z</wsu:Expires></wst:Lifetime></wst:RequestSecurityTokenResponse></wst:
RequestSecurityTokenResponseCollection></env:Body></env:Envelope>
Scenario: Web Service Security With On Behalf Of Username Token
42-24 Administrator's Guide for Oracle Access Management
43
Configuring Security Token Service Settings 43-1
43
Configuring Security Token Service Settings
This chapter introduces how to manage components involved in the protection of
Security Token Service endpoints. This chapter provides the following topics:
■Prerequisites
■Introduction to Security Token Service Configuration
■Enabling and Disabling Security Token Service
■Defining Security Token Service Settings
■Using and Managing WSS Policies for Oracle WSM Agents
■Configuring OWSM for WSS Protocol Communication
■Managing and Migrating Security Token Service Policies
■Logging Security Token Service Messages
■Auditing the Security Token Service
43.1 Prerequisites
Before beginning tasks in this chapter, be sure to review the following chapters.
■Chapter 41, "Introducing the Oracle Access Management Security Token Service"
■Chapter 2, "Getting Started with Oracle Access Management"
■Chapter 6, "Managing Server Registration"
43.2 Introduction to Security Token Service Configuration
Security Token Service a Web Service co-existing with Access Manager. Security Token
Service invokes some Access Manager components to validate and issue security
tokens. Typically, the Web client can use the Security Token Service to request an
outbound token, such as SAML, by providing a security token, like a Username Token
or an X.509 Token.
Security Token Service is integrated with the Oracle Access Management Console to
provide a unified and consistent administration experience. All Security Token Service
system configuration is done using the Oracle Access Management Console.
Security Token Service provides:
■Tokens:
–Validation Tokens: Standard (Username, X.509, Kerberos, SAML 1.1/2.0) and
custom tokens. OnBehalfOf use cases (OAM Session ID Propagation Token
Introduction to Security Token Service Configuration
43-2 Administrator's Guide for Oracle Access Management
and custom tokens through the integration engine) also supports the following
standard tokens along with OAM sessionID propagation token and custom
token (Username, X.509, SAML 1.1/2.0).
–Issuance Tokens: Standard (Username, SAML 1.1/2.0) and custom tokens
through the integration engine
■Configuration-driven token issuance and validation
■Enhanced auditing through identity propagation across multiple tiers and
domains
■Consolidated shared-platform service interacts with internal (Access Manager
SSO, Federation, Oracle Web Services Manager) and external services
This section provides the following topics:
■Post-Installation Configuration
■About OAM Servers and Security Token Service
■About Security Token Service Clients
■About Agents and Security Token Service
43.2.1 Post-Installation Configuration
After installation and server startup, you can access the Oracle Access Management
Console on the OAM Server. For example, if the URL to the OAM Server is
http://machine:14100/oam, you might access:
■Oracle Access Management Console at http://machine:7001/oamconsole
■Security Token Service: http://machine:14100/sts/wss11user?wsdl to view the
WSDL of the /sts/wss11user endpoint that is available by default, to ensure that
Security Token Service is available.
By default, Security Token Service is disabled and as such all runtime functionality
as well as Web Service endpoints are disabled. To access those endpoints, Security
Token Service must first be enabled using the Oracle Access Management Console.
Afterwards, the endpoints might be accessed
Post-installation configuration includes the tasks in the following outline, which point
to other areas in this book for details.
Task overview: Security Token Service configuration requires
1. Server Side Configuration: Use the Oracle Access Management Console for the
following tasks.
a. Service enablement "Enabling and Disabling Services for Security Token
Service" on page 43-9
b. Settings configuration "Managing Security Token Service Settings" on
page 43-12
c. Endpoint registration "Managing EndPoints" on page 45-26
d. Token Issuance Template configuration "Managing Token Issuance Templates"
on page 45-5
See Also: Oracle Fusion Middleware Security and Administrator's Guide
for Web Services
Introduction to Security Token Service Configuration
Configuring Security Token Service Settings 43-3
e. Token Validation Template configuration "Managing Token Validation
Templates" on page 45-13
f. Partner Profile creation "Managing Token Service Partner Profiles" on
page 46-7
g. Partner configuration "Managing Token Service Partners" on page 46-3
h. Token Issuance Policies to define an authorization rule for issuing tokens with
Security Token Service, for a specific Relying Party "Managing Token Issuance
Policies, Conditions, and Rules" on page 45-27
2. Set up interactions with the Oracle WSM Agent as described in following topics:
a. Using and Managing WSS Policies for Oracle WSM Agents
b. Configuring OWSM for WSS Protocol Communication
3. Set up message logging, as described in "Logging Security Token Service
Messages" on page 43-20.
4. Configure event auditing, as described in "Setting Up Auditing for Oracle Access
Management" on page 8-20.
5. Configure lifecycle management
a. Register the Security Token Service trust endpoint, as described in item 1c.
b. Register the Requester or Relying Party Partner with Security Token Service,
as described in "Managing Token Service Partners" on page 46-3.
c. Monitor performance, as described in Chapter 12, "Monitoring Performance
and Logs with Fusion Middleware Control".
43.2.2 About OAM Servers and Security Token Service
With Oracle Access Management, all Security Token Service instances are installed on
OAM Servers (also known as Managed Servers). Each server must be registered with
Access Manager.
Security Token Service leverages the common infrastructure for shared services and
the Oracle Access Management administration model.
Security Token Service support Web Services Security protocol 1.0 and 1.1 and process
the following tokens, if present in the Security SOAP headers:
■Username token (UNT)
■SAML 1.1 or SAML 2.0 Assertion
■Kerberos
■X.509
Third-Party Servers: Security Token Service interoperates with third party security
token servers. For instance, a third party Security Token Service can create a valid
Security Assertion Markup Language (SAML) Assertion that can be consumed by
Security Token Service.
Note: Managed servers hosting Security Token Service must be
registered with Access Manager as described in Chapter 6, "Managing
Server Registration".
Introduction to Security Token Service Configuration
43-4 Administrator's Guide for Oracle Access Management
43.2.3 About Security Token Service Clients
Security Token Service provides services to various Oracle clients (Oracle Web Services
Manager client) or third party clients (Microsoft and IBM are two).
Oracle WSM Client: Oracle Web Services Manager client bindings are the
responsibility of Oracle Web Services Manager (and out of scope for this book). For
more information, see "Configuring Oracle WSM Agent for WSS Kerberos Policies" on
page 43-18.
Third Party Clients: Require a secure key exchange between the Oracle WSM client
and server. You simply import the Security Token Service certificate to the client.
During SOAP interactions, the WS-Security protocol might require the client to trust
the signing/encryption certificate used for WSS operations by the OWSM Agent
protecting the Security Token Service endpoint. In those cases, the Oracle Access
Management Administrator should extract the Security Token Service OWSM
signing/encryption certificate used for WSS operations and provide it to the WS
Client. For more information, see "Extracting the Oracle STS/Oracle WSM Signing and
Encryption Certificate" on page 43-16.
43.2.4 About Agents and Security Token Service
Oracle Web Services Manager communicates through agents. This topic introduces the
agents that operate with Security Token Service.
Oracle WSM Agent: The Oracle Web Services Manager (Oracle WSM) Agent is
integrated with Security Token Service. This agent provides the Web Services Security
support for Security Token Service Web Services endpoints.
■Protects Web Services endpoints of Security Token Service
■Provides WS-Security support for sending SOAP messages to Relying Parties. As
part of that process, the OWSM Client might interact with Security Token Service
to get a security token that will be presented to the Relying Party
■Interacts with Security Token Service for token acquisition and token validation
Security Token Service supports token acquisition and token validation by Oracle Web
Services Manager (Oracle WSM) agents. Oracle Web Services Manager Agents are not
required to use Security Token Service as part of their inbound or outbound security
policy enforcement. Oracle Web Services Manager client bindings are the
responsibility of Oracle Web Services Manager Administrators.
The Oracle WSM Agent is used by Security Token Service to enforce message
protection of the SOAP communication channel between Security Token Service and
the client. The Oracle WSM Agent caches the OPSS Keystore (by default the
default-keystore.jks keystore located in $DOMAIN_HOME/config/fmwconfig
directory) which contains the trusted certificates involved when validating the WSS
clients' certificates. Subsequent changes to the contents of the keystore or to its name,
require a restart of the Managed Server using Oracle Enterprise Manager Fusion
Middleware Control or WebLogic Server console, or NodeManager.
The Oracle WSM Agent available to Security Token Service must be configured to
protect the Security Token Service endpoints, to perform the following tasks:
■Decrypt the request, if necessary
See Also: "WS-Trust Policies and Configuration Steps" in Oracle
Fusion Middleware Security and Administrator's Guide for Web
Services
Introduction to Security Token Service Configuration
Configuring Security Token Service Settings 43-5
■Verify any digital signatures present in the request
■Validate any certificate used to create the request's digital signatures, if the
signatures were created with a private key
■Validate any X.509 token, if present, in the SOAP headers
■Validate the Kerberos token, if present, in the SOAP headers
■Sign the outgoing response, if needed
■Encrypt the outgoing response, if required
Oracle WSM Agent Keystore: The Oracle WSM Agent uses a keystore for various
cryptographic operations. For these operations, the Oracle WSM Agent uses the
keystore configured for Oracle WSM tasks.
Webgate: Security Token Service uses Webgate for the Access Manager session
propagation token. This, identity propagation, use case is more advanced. It requires
the Identity Assertion Provider in WebLogic Server and some custom integration.
43.2.5 About Security Token Service End Points and Policies
When you add an endpoint, you can choose from a list of Policy URI's and validation
templates with which to associate the Security Token Service endpoint. By default,
Security Token Service is configured with the endpoints shown in Figure 43–1.
Figure 43–1 Default Endpoints, Policies, and Validation Templates
The ORAPROVIDER is integrated with the Oracle WSM Agent, which provides Web
Services Security support on the SOAP messages being exchanged between the client
and Security Token Service. Security Token Service leverages ORAPROVIDER for Web
Services to:
See Also:
■"Introduction to Oracle Access Management Keystores" on
page 5-31
■Chapter 44, "Managing Security Token Service Certificates and
Keys"
See Also:
■Chapter 42, "Security Token Service Implementation Scenarios"
■"About the Oracle Web Services Manager Keystore
(default-keystore.jks)" on page 44-3
Introduction to Security Token Service Configuration
43-6 Administrator's Guide for Oracle Access Management
■publish Web Services endpoints dynamically
■invoke Security Token Service to process SOAP messages
■publish a WSDL file for each WS endpoint
Oracle WSM Agent WSS Policy Stores: The Oracle WSM Agent requires a repository
to retrieve the Web Services Security (WSS) policies it needs. Security Token Service
supports two types of repositories:
■JAR file with WSS Policies: Used when the WLS Domain is configured for
classpath.
■Oracle WSM Policy Manager available from the SOA deployment
Policy Assertions: Out of the box, Security Token Service provides a set of security
policy assertions for use with the WS-Policy framework to describe how messages are
to be secured in the context of Oracle Workspace Studio: SOAP Message Security and
WS-Trust.
■Security Token Service makes its associated security policy files publicly available
by attaching them to its deployed WSDL.
■Security Token Service runtime uses the private key and X.509 certificate pairs,
stored in the keystores defined by the jps-config.xml file, for its WS-Security
encryption and digital signature operations.
The following paragraphs and tables identify the policies that are available out of the
box for Security Token Service and the Oracle WSM Agent.
Message-level Security Not Required: When message level-security is not required,
use an Security Token Service policy that does not specify message_protection in its
name. This authenticates users using credentials provided in tokens in the WS-Security
SOAP header. The credentials in the Fusion Applications token are mapped based on
the rules specified in the validation template. Both plain text and digest mechanisms
are supported.
Transport Security when Message-level Security Not Required: You can configure
two-way SSL where both the client applications and WebLogic server present
certificates to each other. To configure two-way or one-way SSL for the core WebLogic
Server security see "Configuring SSL" in Oracle Fusion Middleware Securing Oracle
WebLogic Server guide. Use the policies described in Table 43–1.
Interoperability WS-Security 1.0 and 1.1 Policies: Use policies in Figure 43–2 if you
require interoperability with WS-Security 1.0 or 1.1 (depending on your authentication
requirements and credential availability). Use WS-Security 1.1 policies if you have
strong security requirements.
See Also:
■"Configuring OWSM for WSS Protocol Communication" on
page 43-15
■Managing Oracle Workspace Studio policies for Security Token
Service
■Oracle Fusion Middleware Security and Administrator's Guide for Web
Services for details about the policies for Security Token Service
Enabling and Disabling Security Token Service
Configuring Security Token Service Settings 43-7
Figure 43–2 WS-Security 1.0 and 1.1 Policies
Task overview: Using and modifying WS-S policies
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Endpoints from the View drop-down menu in
the Security Token Service section.
3. Proceed as described in "Managing Security Token Service Endpoints" on
page 45-25 to locate or create the endpoint to be protected.
4. In the Policy URI list, choose a specific WS Security policy to protect the endpoint,
as described in:
■Managing WSS Policies for Security Token Service: Classpath
■Managing WSS Policies for Security Token Service: Oracle WSM Policy
Manager
43.3 Enabling and Disabling Security Token Service
This topic includes the following topics:
■About Security Token Service and the Oracle Access Management Console
■About Enabling Services for Security Token Service
■Enabling and Disabling Services for Security Token Service
See Also: "Using and Managing WSS Policies for Oracle WSM
Agents"
Enabling and Disabling Security Token Service
43-8 Administrator's Guide for Oracle Access Management
43.3.1 About Security Token Service and the Oracle Access Management Console
Elements in the Oracle Access Management Console enable Administrators to easily
configure the Token Service to exchange WS Trust tokens with partners. Token Service
elements provide for creation, viewing, modification, and removal of partners,
endpoints, validation templates, issuance templates, and data store connections.
All Security Token Service system configuration is done using the Oracle Access
Management Console. This includes the following common tasks covered in Part II of
this book:
■Registering and managing common OAM Servers and proxy information
■Registering and managing the common Default User Identity Store
■Configuring the OAM Keystore, which differs from the OWSM Keystore used for
WSS processing
■ Certificate Validation and Revocation
The Oracle Access Management Console enables Administrators to perform the
following Security Token Service-specific tasks:
■Manage validation token templates: The validation templates include
configuration properties to validate a Web Services Security/WSTrust token, and
map it to a Requester Partner or a User record in the Default User Identity Store.
■Manage issuance templates: The issuance templates contain rules on how a token
will be created
■Manage Partner Data: A partner represents a partner trusted by Security Token
Service. Security Token Service defines three types of partners: Requester, Relying
Party and Issuing Authority. Each partner entry is associated to a partner profile.
The partner entry contains signing and encryption certificates and identifiers used
to uniquely identify a partner
■Manage Partner Profile: A partner profile contains configuration properties that
are common to a set of partners:
–Claim Mapping
–Token Types definition
–Issuance and Validation templates defined for the token Types
–Override Validation Template rules for Issuing Authorities(Other STS)
■Manage Security Token Service Endpoints
■Manage Token Issuance Policies (authorization policies that will be evaluated to
determine if a Requester Partner can request a token based on the Relying Party
referenced in the request)
■Security Token Service Global Settings
■Custom tokens
43.3.1.1 About Security Token Service Administrators
Users with administrative access to the Oracle Access Management Console, have
access to Security Token Services.
Initially, administrative users must log in to the Oracle Access Management Console
using the WebLogic Administrator credentials set during initial configuration.
However, your enterprise might require independent sets of Administrators: one set of
users responsible for Access Manager and another for Security Token Service.
Defining Security Token Service Settings
Configuring Security Token Service Settings 43-9
43.3.1.2 About Logging In To, and Signing Out Of, Security Token Service
When using Security Token Service with Access Manager, logging in to, and signing
out of the Oracle Access Management Console is the same.
43.3.2 About Enabling Services for Security Token Service
To use Security Token Service, both it and Access Manager must be enabled. By default
Security Token Service is disabled and needs to be enabled.
A green check mark in the Status field beside the service name indicates the service is
enabled. A red circle with a line through it indicates that the corresponding service is
disabled.
43.3.3 Enabling and Disabling Services for Security Token Service
Prerequisites
Oracle Access Manager service must be enabled.
To enable or disable Security Token Service
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, click Available Services.
3. Enable Security Token Service: Beside Security Token Service, click Enable (or
confirm that the Status check mark is green) and confirm that the Access Manager
Service is also enabled.
4. Disable Security Token Service: Beside Security Token Service, click Disable (or
confirm that the Status check mark is red).
43.4 Defining Security Token Service Settings
This section provides the following information:
■About Security Token Service Settings
■Managing Security Token Service Settings
43.4.1 About Security Token Service Settings
Security Token Service can be viewed or altered from the Security Token Service
section of the System Configuration tab. These settings are show in Figure 43–3.
See Also: Chapter 2 for the following topics:
■Logging Into the Oracle Access Management Console
■Signing Out
Defining Security Token Service Settings
43-10 Administrator's Guide for Oracle Access Management
Figure 43–3 Security Token Service Page
Table 43–1 describes the elements on the Security Token Service Settings page.
Table 43–1 Security Token Service Settings
Element Description
Partner Identification
Attributes
A field where you list attributes, other than the standard ones
available by default, that should be available in "Identity
Attributes" Table in the Partner page. These attributes can be
used to identify a partner by matching their values against
those in the incoming request.
When a Requester sends a WS-Trust request to Security Token
Service, the server might map the incoming token containing
the requester's identity to a partner entry in the Security Token
Service partner store.
To do so, Security Token Service will use the mapping settings
configured in a validation template and will attempt to map
the token data to a partner entry by performing a lookup by
matching the token data to a Partner Identification Attribute.
By default, each requester partner contains three identification
attributes that can be set: username, HTTP Basic Username,
SSL Client Certificate DN.
It is possible to define additional Identification Attributes that
could be set for each requester partner entry.
This section allows new attributes to be set. After defining a
new attribute, it becomes available in the Requester Partner
entry section, and it can be used in mapping rules in the WSS
Validation Templates.
Defining Security Token Service Settings
Configuring Security Token Service Settings 43-11
Custom Trust Anchor File By default, Access Manager and Security Token Service use the
default
$DOMAIN_HOME/config/fmwconfig/amtruststore
keystore containing the trust anchors used for certificate
validation by Security Token Service, when verifying X.509
Tokens, or when verifying certificates used in SAML Assertion
signatures.
It is possible to configure Security Token Service to use a
specific trust anchor file if necessary, that will contain trust
anchors only used for Security Token Service operations and
validations. In this case, this field should contain the location
of the JKS keystore to use.
Note the following:
■When using a custom trust anchor keystore, it will not be
replicated automatically across the cluster. You must
manage replication.
■In most cases, the default Access Manager and Security
Token Service trust anchor should be enough.
See Also: Chapter 44, "Managing Security Token Service
Certificates and Keys"
Default Encryption Template A list from which you choose the default template for Security
Token Service encryption:
■osts_encryption
■osts_signing
See Also: Setting the Default Encryption Key on page 44-6.
Proxy Outbound Connection Properties, HTTP Proxy Settings Use
this section to configure Security Token Service to use a proxy
for outgoing HTTP connections when optionally retrieving the
WS-Sec Policy of Relying Parties at runtime:
■Enabled: When this box is checked the Proxy function is
enabled and will be used when retrieving the WS-Security
Policy of Relying Parties. When the box is not checked, the
Proxy function is disabled and related fields are
inaccessible for editing.
■Host: The proxy hostname
■Port: The proxy port number. Default is 8080
■Non Proxy Hosts: A list of hosts for which the proxy
should not be used. Use ';' to separate multiple hosts.
■Username: The username to use when connecting to the
proxy.
■Password: The password to use when connecting to the
proxy.
Table 43–1 (Cont.) Security Token Service Settings
Element Description
Using and Managing WSS Policies for Oracle WSM Agents
43-12 Administrator's Guide for Oracle Access Management
43.4.2 Managing Security Token Service Settings
Users with valid Administrator credentials can use this procedure to confirm or alter
Security Token Service Settings.
Prerequisites
Both the Access Manager Service and the Security Token Service must be enabled.
To view or edit Security Token Service Settings
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Security Token Service from the View
drop-down menu in the Settings section.
3. On the Security Token Service Settings page view (or modify) the following
information (see Table 43–1):
■Partner Identification Attributes
■Custom Trust Anchor File
■Proxy details
4. Keystore Table: View, add, or remove new encryption templates
5. Click Apply to submit changes (or Revert to cancel changes).
6. Close the page when finished.
43.5 Using and Managing WSS Policies for Oracle WSM Agents
You can use existing Oracle Workspace Studio policies to protect Security Token
Service Web Service endpoints. For instance:
■classpath mode: Existing Oracle Workspace Studio policies defined in
$ORACLE_
IDM_HOME/oam/server/policy/sts-policies.jar
are used in this mode
Keystore Location: Path of the active keystore that was set up during
Security Token Service installation.
The Keystore table includes the following information for each
of the templates in the table, which are available for use as the
Default Encryption Template:
■Template ID: The name of the template that can access the
keystore.
■Alias: Identifies the alias for the template. When adding a
template, you can choose from the Aliases listed.
■Password: The password for the selected Alias.
■Description: Optional.
The keystore section defines key entries that exist in the
Security Token Service keystore:
$DOMAIN_
HOME/config/fmwconfig/.oamkeystore
After an entry is defined an entry, it can be used in other
Security Token Service templates (like SAML Issuance
Templates).
Table 43–1 (Cont.) Security Token Service Settings
Element Description
Using and Managing WSS Policies for Oracle WSM Agents
Configuring Security Token Service Settings 43-13
■SOA deployment: Policies defined in the Oracle WSM Policy Manager available
from a SOA deployment are used
This section describes how to manage Web Service Security Policies for Security Token
Service in the following topics:
■Using and Modifying Oracle Workspace Studio Policies
■Managing WSS Policies for Security Token Service: Classpath
■Managing WSS Policies for Security Token Service: Oracle WSM Policy Manager
43.5.1 Using and Modifying Oracle Workspace Studio Policies
This section introduces WS-Security Policies used to protect Security Token Service WS
Endpoint and how to modify these policies. TheWS-Security Policies that are provided
by Oracle should cover most use cases.
43.5.2 Managing WSS Policies for Security Token Service: Classpath
Predefined Oracle Web Services Manager policies are constructed using assertions
based on predefined assertion templates. For WSS Policy classpath mode, the OWSM
Agent retrieves policies from sts-policies.jar located on the classpath.
If SOA is not deployed in the WebLogic Server domain, the Security Token Service
installer configures the WebLogic Server domain for WSS Policy classpath mode. The
JAR file containing the WSS Policies used when the WLS Domain is configured for
classpath is located at:
$ORACLE_IDM_HOME/oam/server/policy/sts-policies.jar
When your environment is in classpath mode, perform the following tasks to
Administrators confirm sts-policies.jar is located on the classpath.
Task overview: Managing WSS Policies for Security Token Service: Classpath
1. Define an OWSM Assertion Template.
2. Proceed as follows, depending on your need:
■Modify an OWSM Policy
■Define a Policy using the OWSM Assertion Template
3. Bundle the Assertion Template and policy in the sts-policies.jar file:
META-INF/assertiontemplates/oracle of the $ORACLE_IDM_HOME/oam/server/policy/
See Also:
■"About Security Token Service End Points and Policies" on
page 43-5
■Attaching Policies to Web Services in the Oracle Fusion Middleware
Security and Administrator's Guide for Web Services
See Also:
■"About Security Token Service End Points and Policies" on
page 43-5
■Oracle WSM Predefined Policies and Assertion Templates in the
Oracle Fusion Middleware Security and Administrator's Guide for Web
Services
Using and Managing WSS Policies for Oracle WSM Agents
43-14 Administrator's Guide for Oracle Access Management
sts-policies.jar
4. Confirm that
sts-policies.jar
is located in the following path to enable the
policy URI to be available the Policy URI drop down list.
$ORACLE_IDM_HOME/oam/server/policy/sts-policies.jar
5. Restart the Managed Servers running Security Token Service.
6. Proceed to the Oracle Access Management Console to configure the Security Token
Service Endpoints.
43.5.3 Managing WSS Policies for Security Token Service: Oracle WSM Policy Manager
The Oracle WSM Policy Manager is the security linchpin for Oracle Fusion
Middleware Web services and SOA applications. For more information about how the
Oracle WSM Policy Manager manages the policy framework, see "Understanding
Oracle WSM Policy Framework" in Oracle Fusion Middleware Security and
Administrator's Guide for Web Services.
At design time, you attach Oracle WSM and WebLogic Web service policies to
applications programmatically using your favorite IDE, such as Oracle JDeveloper.
Alternatively, at deployment time you attach policies to SOA composites, ADF, and
WebCenter applications using the Oracle Enterprise Manager Fusion Middleware
Control, and to WebLogic Web services (Java EE) using the WebLogic Server
Administration Console.
System Administrators can leverage the Oracle WSM through the Oracle Enterprise
Manager Fusion Middleware Control to:
■Centrally define policies using the Oracle WSM Policy Manager.
■Enforce Oracle WSM security and management polices locally at run time.
When your environment is integrated with the OWSM Policy Manager, perform the
following tasks to add or modify WSS policies for Security Token Service using Oracle
Web Services Manager.
Task overview: Managing WSS Policies for Security Token Service: OWSM Policy
Manager
1. From the OWSM Policy Manager, locate and open the desired policy.
2. Refer to the Oracle Fusion Middleware Security and Administrator's Guide for Web
Services and make any required changes to the policy.
3. Restart all Managed Servers running Security Token Service.
4. Proceed to "Configuring OWSM for WSS Protocol Communication".
Note: All of Oracle WSM's functionality is accessible to
Administrators from Oracle Enterprise Manager Fusion Middleware
Control.
See Also: Oracle Fusion Middleware Security and Administrator's
Guide for Web Services
■Part II, "Basic Administration"
■Part III, "Advanced Administration"
Configuring OWSM for WSS Protocol Communication
Configuring Security Token Service Settings 43-15
43.6 Configuring OWSM for WSS Protocol Communication
This section describes how to configure communication between WS-Sec Clients and
the Oracle WSM Agent embedded with Security Token Service.
The Oracle WSM Agent protects the Web Service endpoints of Security Token Service,
and provides support for WSS protocol exchanges. To ensure a client is
communicating successfully with the Oracle WSM Agent:
■The client might need to be aware of the signing and encryption certificates used
by the Oracle WSM Agent (this will require extracting and distributing the signing
and encryption certificates used by the OWSM Agent embedded with Security
Token Service).
■The Oracle WSM Agent might need to be aware, depending on the policies, of the
signing certificate used by the client (this will require adding the client's certificate
as a trusted certificate for the Oracle WSM Agent)
Task overview: Configuring communication with Oracle WSM agents
1. See "About Oracle WSM Agent WS-Security Policies for Security Token Service"
2. Retrieving the Oracle WSM Keystore Password
3. Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate
4. Adding Trusted Certificates to the Oracle WSM Keystore
5. Validating Trusted Certificates in the Oracle WSM Keystore
6. Configuring Oracle WSM Agent for WSS Kerberos Policies
43.6.1 About Oracle WSM Agent WS-Security Policies for Security Token Service
The Oracle WSM Agent requires a repository to retrieve the Web Services Security
(WSS) policies it needs. Access Manager supports two types of repositories for
Security Token Service:
■JAR file with WSS Policies: Used when the WLS Domain is configured for
classpath. The required JAR file is located in $ORACLE_IDM_
HOME/oam/server/policy/ sts-policies.jar.
■Oracle WSM Policy Manager available from the SOA deployment
During Security Token Service installation, the installer detects if the Oracle Web
Services Manager Policy Manager is present and deployed in the WebLogic Security
domain.
■If not deployed in the WebLogic Security domain, the installer configures the
WebLogic Security domain for the Web Services Security Policy classpath mode,
where the WSM Agent will retrieve the policies from a JAR file.
■If present, the installer connects to the Oracle Web Services Manager Policy
Manager and uploads the policies that are used to protect Security Token Service
endpoints.
See Also: Chapter 44, "Managing Security Token Service Certificates
and Keys"
See Also: "About the Database Store for Policy, Password
Management, and Sessions" on page 5-29 for details about the
required database for Access Manager policy data and (optionally)
Access Manager session data.
Configuring OWSM for WSS Protocol Communication
43-16 Administrator's Guide for Oracle Access Management
43.6.2 Retrieving the Oracle WSM Keystore Password
Administrators need to retrieve the keystore password and key entry password from
CSF for certain activities. Otherwise, keystore or key entry cannot be changed. Having
access to the keystore is sometimes required to:
■Extract the signing/encryption certificate to distribute to clients if necessary
■Update or replace the signing/encryption key entry
■Add trusted certificates
The following procedure displays the password used to protect the Oracle WSM
keystore as well as the key entry.
To retrieve the Oracle WSM keystore password
1. Enter the WSLT scripting environment.
2. Connect to the WebLogic Server AdminServer, using the
connect()
command.
3. Execute the following command by providing the connection information to the
AdminServer:
listCred(map="OAM_STORE", key="jks")
.
4. Note the password.
5. Proceed to "Extracting the Oracle STS/Oracle WSM Signing and Encryption
Certificate".
43.6.3 Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate
During SOAP interactions, the WS-Security protocol might require the client to trust
the signing/encryption certificate used for WSS operations by the OWSM Agent
protecting the Security Token Service endpoint. In those cases, the Oracle Access
Management Administrator should extract the Security Token Service OWSM
signing/encryption certificate used for WSS operations and provide it to the WS
Client.
The Administrator must export the signing and encryption certificate used by Security
Token Service for WSS cryptographic operations. The following procedure guides as
you do this by:
■Replacing $DOMAIN_HOME with the path to the Domain directory
■CERT_FILE with the location of the file where the certificate will be saved
If you are prompted to enter a password, simply press the Enter key.
Prerequisites
Retrieving the Oracle WSM Keystore Password
To export the signing and encryption certificate
1. Locate keytool.
2. Execute the following command.
keytool -exportcert -keystore $DOMAIN_HOME/config/fmwconfig/default-keystore.j
ks -storetype JKS -alias orakey -file $CERT_FILE
3. Enter the keystore password retrieved in the previous section if prompted.
4. Proceed to "Adding Trusted Certificates to the Oracle WSM Keystore".
Configuring OWSM for WSS Protocol Communication
Configuring Security Token Service Settings 43-17
43.6.4 Adding Trusted Certificates to the Oracle WSM Keystore
To add a trusted certificate to the OWSM keystore for WSS cryptographic operations:
■perform the command in the following procedure
■replace the $DOMAIN_HOME with the path to the Domain directory
■replace the TRUSTED_CERT_FILE with the location of the file containing the
trusted certificate
■replace the TRUSTED_CERT_ALIAS with the alias under which the trusted
certificate will be stored
When prompted to enter a password, enter the password of the OWSM keystore that
you retrieved earlier.
Prerequisites
Retrieving the Oracle WSM Keystore Password
The Administrator must have the certificate to import.
To add trusted certificates to the Oracle WSM keystore
1. Locate keytool.
2. Execute the following command.
keytool -importcert -trustcacerts -keystore $DOMAIN_HOME/config/fmwconfig/de
fault-keystore.jks -storetype JKS -alias $TRUSTED_CERT_ALIAS -file $TRUSTED_
CERT_ALIAS
3. Observe messages on the screen, enter a password if requested.
4. Proceed to "Validating Trusted Certificates in the Oracle WSM Keystore".
43.6.5 Validating Trusted Certificates in the Oracle WSM Keystore
When the Oracle WSM Agent performs a certificate validation, it uses the keystore
configured for Oracle WSM tasks, and will validate the certificate against the trusted
certificate entries contained in the keystore. For those operations, it might be required
to add trusted certificate entries (the certificate itself or the issuer's certificate) in the
OWSM keystore.
When receiving a SOAP requester, the Oracle WSM Agent processes the request for
message protection. Part of the steps might include a certificate validation operation if
the incoming message:
■is of type WSS 1.0, and includes a digital signature created with a private key,
without the certificate being present. In this case:
Remedy: The Oracle WSM keystore must contain the signing certificate.
■is of type WSS 1.0, and includes a digital signature created with a private key, with
the certificate being present.
Remedy: The Oracle WSM keystore must contain either the signing certificate or
the issuer's certificate of the signing certificate.
■is of type WSS 1.1, and includes a digital signature created with a private key,
without the certificate being present.
Remedy: The Oracle WSM keystore must contain the signing certificate.
Configuring OWSM for WSS Protocol Communication
43-18 Administrator's Guide for Oracle Access Management
■is of type WSS 1.1, and includes a digital signature created with a private key, with
the certificate being present. In this case, the OWSM keystore will need to contain
either the signing certificate or the issuer's certificate of the signing certificate
Remedy: The Oracle WSM keystore must contain either the signing certificate or
the issuer's certificate of the signing certificate
43.6.6 Configuring Oracle WSM Agent for WSS Kerberos Policies
Security Token Service provides services to various Oracle clients (Oracle Web Services
Manager client) or third party clients (Microsoft and IBM are two). the Oracle WSM
Agent performs only message protection (not authentication) on the incoming request.
The Oracle WSM agent does not attempt to map the incoming Kerberos ticket to a user
record in the OPSS Identity Store.
If Oracle WSM is the client that will interact with Security Token Service using WSS
Kerberos policies, then the entire Oracle WSM Kerberos setup section in Oracle Fusion
Middleware Security and Administrator's Guide for Web Services applies.
However, if the client is not Oracle WSM, see Table 43–2 and disregard sections on
how to configure the client, sections related to authenticating the user referenced in the
Kerberos ticket.
See Also: Chapter 44, "Managing Security Token Service Certificates
and Keys"
Table 43–2 Configuring a Non-Oracle WSM Client for WSS Kerberos Policies
Perform Tasks for Non-Oracle Client Skip These Tasks for Non-Oracle Client
Configure the KDC
Initialize and Start the MIT Kerberos KDC
Create Principals
Configure the Web Service Client to Use the Correct
KDC
Set the Service Principal Name In the Web Service
Client
Set the Service Principal Name In the Web Service
Client at Design Time
Configure the Web Service to Use the Right KDC
Use the Correct Keytab File in Enterprise Manager
Extract and Export the Keytab File
Modify the krb5 Login Module to use the Keytab
File
Authenticate the User Corresponding to the Service
Principal
Create a Ticket Cache for the Web Service Client
Use Active Directory with Kerberos and Message
Protection
Set Up the Web Service Client
Create a User Account
Create a Keytab File
Set the Service Principal Name
Set Up the Web Service
Managing and Migrating Security Token Service Policies
Configuring Security Token Service Settings 43-19
43.7 Managing and Migrating Security Token Service Policies
This section provides the following topics:
■About Managing and Migrating Security Token Service Policies
■Managing Security Token Service Policies
■Migrating Security Token Service Policies
43.7.1 About Managing and Migrating Security Token Service Policies
Security Token Service policies for endpoints reside in sts-policies.jar. This jar is copied
to following location under $WLS_HOME ($Oracle_IDM1, for example):
$WLS_HOME/oam/server/policy
The sts-policies.jar contains the stspolicies.prop file at the following location in the
JAR:
META-INF/policies/sts/
This file lists all the policies packaged in the directory as file names to allow the server
to read the JAR entries programmatically when migrating policies to destination
repository.
43.7.2 Managing Security Token Service Policies
The following procedure outlines the various scenarios for policy updates.
Task overview: Updating policies and stspolicies.prop
1. Add a Policy to sts-policies jar: Before creating the new jar, you must also update
the stspolicies.prop file at META-INF/policies/sts/ to include this new policy file
name.
2. Delete a Policy from sts-policies jar: You must also delete the entry from file
META-INF/policies/sts/stspolicies.prop.
3. Update Existing Policy File Name: When re-naming a policy file at
META-INF/policies/sts/, you must also update the corresponding entry in the
file META-INF/policies/sts/stspolicies.prop file.
4. Update Existing Policy Content: When updating the content of a policy file,
without touching the file name, there is no need to do anything else.
43.7.3 Migrating Security Token Service Policies
During installation a check is performed to establish whether SOA is deployed within
the domain where Security Token Service is being installed:
■If SOA is not installed, the Oracle WSM protocol is set to classpath and policies are
read from the JAR on the class path.
Note: Be sure to update policies and stspolicies.prop as needed
before migration.
Logging Security Token Service Messages
43-20 Administrator's Guide for Oracle Access Management
■If SOA is present within the domain, Security Token Service reads the policies
from sts-policies.jar and migrates them to the Oracle WSM PM repository by
calling Oracle WSM Mbeans.
■If SOA is installed after Security Token Service within the same domain, ensure
smooth operations between SOA and Security Token Service as follows:
–The Oracle WSM protocol must be set to 'remote'.
–Security Token Service policies from sts-policies jar must be migrated to Oracle
WSM PM repository using Oracle WSM provided tools.
43.8 Logging Security Token Service Messages
Logging is the mechanism by which components write messages to a file.
Administrators can use the logging mechanism to capture critical component events.
Access Manager uses the same logging infrastructure and guidelines as any other
component in Oracle Fusion Middleware 11g. This is accomplished by using the
package
java.util.logging
, which is standard and available in all Java environments.
The logging system writes output to flat files only. Logging to an Oracle Database
instance is not supported.
Configuring logging and locating log files are the focus of this section. Diagnosing
problems using the information in log files is outside the scope of this manual.
Log messages are used for problem diagnosis. The logging infrastructure records
messages from Access Manager. The Administrator controls the amount of
information that is logged in a message by specifying log levels for each component or
service for which a logger is defined.
By default, the log level for Access Manager is the Notification level. Logging at the
Error level produces a small amount of output while other log levels can result in
voluminous logging output, which can impact OAM performance. In production
environments, logging is usually either disabled or the log level is set to a level that
results in a small volume of logging output (the error level, for example).
Access Manager and Security Token Service uses the WebLogic container's logging
defaults:
■Logging File: $DOMAIN_
HOME/servers/SERVER-NAME/logs/SERVER-NAME-diagnostics.log
■Logging Configuration File: Provides logging level and other configuration
information for logging. This file is stored in the following path: $DOMAIN_
HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml
See Also: "Using and Managing WSS Policies for Oracle WSM
Agents" on page 43-12.
Note: Generally, you enable logging to produce files that you send to
Oracle Technical Support for problem diagnosis. Documentation for
log messages is not available. In some cases, you might be able to
diagnose problems on your own by reading log files.
Auditing the Security Token Service
Configuring Security Token Service Settings 43-21
43.9 Auditing the Security Token Service
Oracle Fusion Middleware auditing provides a measure of accountability and answers
to the "who has done what and when" types of questions. Audit data can be used to
create dashboards, compile historical data, and assess risks. Analyzing recorded audit
data allows compliance officers to perform periodic reviews of compliance policies.
Configuring common auditing settings for Security Token Service and validating your
auditing configuration is the subject of this section; analyzing and using audit data is
outside it's scope.
The Oracle Fusion Middleware Common Audit Framework supports auditing for a
number of run-time events, and administrative events (changes to the system). It also
provides uniform logging, and exception handling and diagnostics for all audit events.
While auditing can be enabled or disabled, it is typically enabled in production
environments. Auditing has minimal performance impact, and the information
captured can be useful (even mission-critical). The Auditing Framework uses
configuration parameters set in the Oracle Access Management Console that enable
data capture for a user or set of users.
Audit data can be written to either a single, centralized Oracle Database instance or to
flat files. Regardless of where the audit record is stored, it contains a sequence of items
that can be configured to meet particular requirements. The audit log file helps the
audit Administrator track errors and diagnose problems if the audit framework is not
working properly. More information is in the following sections.
■About Security Token Service Audit Record Storage
■About Audit Reports and Oracle Business Intelligence Publisher
■About the Audit Log
■About Auditing Security Token Service Events
43.9.1 About Security Token Service Audit Record Storage
Security Token Service can be configured to write audit records to a variety of targets
supported by the Common Audit Framework:
■Local flat files: By default, Security Token Service records audit data to a file.
■Central database: In production environments, Oracle recommends using a
database audit store to provide scalability and high-availability for the Common
Audit Framework. Audit data is cumulative and grows over time. Ideally this is a
database for only audit data; not used by other applications.
■Platform-specific log (Linux Syslog and Windows Event Log)
■Audit Vault
To switch to a database as the permanent store for your audit records, you must first
use the Repository Creation Utility (RCU) to create a database schema for audit data.
The RCU seeds that database store with the schema required to store audit records in a
database. After the schema is created, configuring a database audit store involves:
■Creating a data source that points to the audit schema you created
Note: Security Token Service integrates with Oracle Business
Intelligence Publisher which provides a pre-defined set of compliance
reports.
Auditing the Security Token Service
43-22 Administrator's Guide for Oracle Access Management
■Configuring the audit store to point to the data source
43.9.2 About Audit Reports and Oracle Business Intelligence Publisher
The data in the database audit store is exposed through pre-defined reports in Oracle
Business Intelligence Publisher. These reports allow you to drill down the audit data
based on various criteria, such as user name, time range, application type, and
execution context identifier (ECID).
Out-of-the-box, there are several sample audit reports available with Security Token
Service and accessible with Oracle Business Intelligence Publisher. You can also use
Oracle Business Intelligence Publisher to create your own custom audit reports.
43.9.3 About the Audit Log
An audit log file helps the audit Administrator track errors and diagnose problems
when the audit framework is not working properly. An audit log file records several
fields including: Date, Time, Initiator, EventType, EventStatus, MessageText, ECID,
RID ContextFields, SessionId, TargetComponentType, ApplicationName, and
EventCategory to name a few.
43.9.4 About Auditing Security Token Service Events
Specific administrative and run-time events that you can audit for Security Token
Service are grouped together in Chapter 8, "Auditing Administrative and Run-time
Events". Included with the events are the common instructions for setting up and
validating auditing. For details, see:
■Security Token Service Events You Can Audit
■Setting Up Auditing for Oracle Access Management
■Validating Auditing and Reports
See Also:
■Oracle Fusion Middleware Application Security Guide
■"Setting Up the Audit Database Store" on page 8-21
■"Adding, Viewing, or Editing Audit Settings" on page 8-24
See Also: "About Audit Reports and Oracle Business Intelligence
Publisher" on page 8-4
See Also: The topic on audit logs in the chapter on configuring and
managing auditing in the Oracle Fusion Middleware Security Guide
44
Managing Security Token Service Certificates and Keys 44-1
44
Managing Security Token Service Certificates
and Keys
This chapter provides the following sections:
■Prerequisites
■Introducing the Security Token Service Certificates and Keys
■Managing Security Token Service Encryption/Signing Keys
■Managing Partner Keys for WS-Trust Communications
■Managing Certificate Validation
44.1 Prerequisites
Security Token Service services must be running, as described in "Enabling and
Disabling Security Token Service" on page 43-7.
44.2 Introducing the Security Token Service Certificates and Keys
Depending on the public key infrastructure, the digital certificate establishes
credentials for Web-based transactions, as described in "About Certificates,
Authorities, and Encryption Keys" on page C-3.
Public Keys at Run Time: There are distinct cases where public key infrastructure
materials are used at run time. For instance, during Web Services Security (WSS)
protocol communication between Requesters and Security Token Service (with OWSM
Agent). See also Table 44–1.
Introducing the Security Token Service Certificates and Keys
44-2 Administrator's Guide for Oracle Access Management
44.2.1 About Keystores and Security Token Service
Following is a brief summary of the keystore files distributed across all OAM Servers
in the domain by the JMX framework and used for Security Token Service:
■.oamkeystore: For keys and certificates associated with OAM Server instances
■.oamkeystore: Partner Keystore for keys and certificates used to establish trust
with partners, clients, and agents.
■amtruststore: Trust Keystore for keys and certificates that are used to establish
trust in entities that are interacting with the OAM Server instances
■amcrl.jar: Certificate Revocation Lists (CRL) are used by the OAM Server instances
when performing CRL-based certificate revocation checking
The files in Table 44–2, are distributed across all OAM Servers in the domain by the
JMX framework. The $DOMAIN_HOME/config/fmwconfig /mbeans directory
defines a registration mbeans.xml for each file that indicates the MBean to manage the
file and also identify that the file should be propagated across the domain.
The token security key pair is populated to the common keystore shared by Security
Token Service. This eliminates the need for Oracle Web Services Manager agents to
interact with the common keystore.
Table 44–1 Security Token Service Public Keys Used at Run Time
When Security Token Service ... Description
Issues SAML Assertions ■Security Token Service Signing Assertions using a key defined
in the STS Global settings
■Security Token Service using the Requester's signing certificate
as a proof key for Holder-of-Key of type Public Key
confirmation method
■Security Token Service using the Relying Party's encryption
certificate to encrypt the secret proof key for Holder-of-Key of
type Secret Key confirmation method
■Security Token Service using the Requester's encryption
certificate to encrypt a secret proof/entry in the RSTR for
Holder-of-Key of type Secret Key confirmation method
Issues tokens ■Security Token Service uses the Relying Party's encryption
certificate to encrypt the outgoing token
Validates SAML Assertions ■Security Token Service uses the Issuing Authority's signing
certificate to verify the signature of the incoming SAML
Assertion
Uses Web Services Security (WSS) protocol
communication
Between Requesters and Security Token Service (with OWSM
Agent)
See Also: "Introduction to Oracle Access Management Keystores" on
page 5-31
Table 44–2 Keystore Mbeans
Keystore Mbean and Description
System/Partner Keystore:
.oamkeystore
Configuration of the .oamkeystore is done using the JRE's keytool application.
Trust Keystore: .amtruststore Configuration of the amtruststore is done using the JRE's keytool application.
CRL: amcrl.jar CRL MBean: Can be used to manage CRLs.
Introducing the Security Token Service Certificates and Keys
Managing Security Token Service Certificates and Keys 44-3
You can use a WLST command to retrieve the password for keystores and for the
amtruststore, as described in "Resetting System Keystore (.oamkeystore) and Trust
Keystore (amtruststore) Password" on page 44-4.
44.2.2 About the Oracle Web Services Manager Keystore (default-keystore.jks)
This topic describes the keystore of type JKS required by the Oracle WSM Agent to
contain System and Partner keys and certificates.
Oracle WSM Agent functionality is available to Security Token Service to publish WS
Policies and enforce message protection on inbound and outbound WS messages.
Oracle WSM requires a separate keystore to contain System and Partner keys and
certificates.
The Oracle WSM Agent uses a keystore for various cryptographic operations. For
these tasks, the Oracle Web Services Manager Agent uses the keystore configured for
Oracle Web Services Manager tasks (containing OWSM private keys and OWSM
trusted certificates). The OPSS modules publish a keystore service used by Oracle Web
Services Manager for certificate validation operations, and the $DOMAIN_
HOME/config/fmwconfig/jps-config.xml will contain the settings for the keystore
service. The default name is default-keystore.jks, which is specified in jps-config.xml.
Oracle strongly recommends that the Oracle WSM Agent keystore and the Security
Token Service keystore always be different. Otherwise, keys could be available to any
modules authorized by OPSS to access the keystore and Access Manager keys might
be accessed.
During installation, if the Oracle WSM keystore service has not been configured, the
installer:
■Creates a new keystore in the $DOMAIN_HOME/config/fmwconfig folder
(default name is default-keystore.jks)
■Creates a key entry with the corresponding certificate that will be used by OWSM
for signature and encryption operations. This key entry will be stored in the
OWSM Keystore under the
orakey
alias
■Stores the passwords of the key entry and of the keystore in CSF
Having access to the keystore is sometimes required, to:
■Extract the signing/encryption certificate to distribute to clients if necessary
■Update or replace the signing/encryption key entry
■Add trusted certificates
44.2.3 About Using the OPSS Keystore for Requester Certificates
For the special cases where clients use referencing schemes such as SKI (as opposed to
a certificate token being received as part of the web service request), the requester's
Note: Oracle strongly recommends that the Oracle WSM Agent
keystore and the Security Token Service keystore always be different.
See Also:
■"Configuring OWSM for WSS Protocol Communication" on
page 43-15
Managing Security Token Service Encryption/Signing Keys
44-4 Administrator's Guide for Oracle Access Management
certificates need to be populated in the OPSS Keystore. This is an uncommon scenario
that requires manually provisioning keys to the OPSS keystore.
For more information on this, see "About Agents and Security Token Service" on
page 43-4.
44.3 Managing Security Token Service Encryption/Signing Keys
Security Token Service uses keys to:
■Sign outgoing Assertions
■Decrypt any incoming XML encrypted data contained inside the RST message
(tokens, entropies...), which is not handled by the WSS Protocol
Security Token Service uses the following keystore for storing Encryption and Signing
Certificates.
$DOMAIN_HOME/config/fmwconfig/.oamkeystore
Task overview: Managing Security Token Service Keys
1. Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore)
Password
2. Adding a New Key Entry to the System Keystore (.oamkeystore)
3. Extracting an Security Token Service Certificate
44.3.1 Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore)
Password
Use the following procedure to reset the password that protects keystores, and the key
entries that are using the same password as the keystore.
These keystores were created and configured during installation, as described in the
Oracle Fusion Middleware Installation Guide for Oracle Identity and Access
Management. The password and key entries password were randomly generated.
The WLST
resetKeystorePassword
method allows the Administrator to set the
.oamkeystore password and any key entries with a password identical to the
.oamkeystore password to a new value:
■Updates the .oamkeystore password
■Updates the key entries in .oamkeystore that had the same password as the
keystore
■Updates Access Manager, Identity Federation, and Security Token Service
configuration to reflect the changes
■Updates the amtruststore password (if the keystore is protected by the same
password as the default .oamkeystore)
To reset system and trust keystore passwords
1. Enter the WSLT scripting environment, as usual.
See Also: "Configuring OWSM for WSS Protocol Communication"
on page 43-15
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference
Managing Security Token Service Encryption/Signing Keys
Managing Security Token Service Certificates and Keys 44-5
2. Connect to the WebLogic Server AdminServer, using the
connect()
command.
3. Navigate to the domain runtime tree:
domainRuntime()
.
4. Execute the following:
resetKeystorePassword(
)
5. Enter and confirm the password.
44.3.2 Adding a New Key Entry to the System Keystore (.oamkeystore)
An Administrator can use the following procedure to add a new key entry into the
System keystore (.oamkeystore) using the keytool command to create and add the new
key entry. Once the entry has been added, it must be defined in the Security Token
Service configuration screen so that it can be used to sign assertions and decrypt
incoming messages.
This topic provides the following procedures to add a new entry to sign SAML
Assertions or decrypt XML-Encrypted data not covered by WSS:
■Adding a New Entry
■Configuring a SAML Issuance Template to use a Signing Key
■Setting the Default Encryption Key
44.3.2.1 Adding a New Entry
Prerequisites
Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password
To configure a new entry
1. Locate keytool.
2. Either generate a self signed certificate or generate a certificate request, export the
request to a remote Certificate Authority, and import the certificate issued by the
Certificate Authority.
3. Observe messages on the screen.
4. Proceed as needed:
■"Configuring a SAML Issuance Template to use a Signing Key", if needed
■"Setting the Default Encryption Key", if needed
44.3.2.2 Configuring a SAML Issuance Template to use a Signing Key
Users with valid Administrator credentials can use this procedure as a guide when
editing an existing template to use a signing key.
To configure a SAML Issuance Template to use a signing key
1. Display the list of existing Token Issuance Templates.
Oracle Access Management Console
System Configuration
Security Token Services
See Also:
■About Managing Token Issuance Templates
■Searching for an Existing Template
Managing Security Token Service Encryption/Signing Keys
44-6 Administrator's Guide for Oracle Access Management
Token Issuance Templates
2. Find and open the SAML issuance template that will use the new key. For
example:
saml11-issuance-template
.
3. On the SAML Issuance Template page, click the Security tab.
4. On the Security tab, Signing And Encryption section, click Sign Assertion.
5. From the Signing Keystore Access Template Id list, choose the KeyID as the
Signing Keystore Entry.
6. Click Apply at the top of the page to save this information.
7. Proceed to "Setting the Default Encryption Key", if needed.
44.3.2.3 Setting the Default Encryption Key
Users with valid Administrator credentials can use this procedure as a guide when
editing an existing template to use a signing key.
To set the default encryption key
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, select Security Token Service from the View
drop-down menu in the Settings section.
3. From the Default Encryption Template list, select the new key entry.
4. Click Apply at the top of the page to save this information.
5. Proceed to "Setting the Default Encryption Key".
44.3.3 Extracting an Security Token Service Certificate
In some cases, it is required to distribute the Security Token Service keys used for
SAML Signature operations or XML encryption operations:
■When a Relying Party needs to have access to the Security Token Service signing
key, in order to validate the SAML Assertion issued by Security Token Service
■When a token needs to be encrypted for Security Token Service Server
To distribute the certificate of a key entry used by Security Token Service for SAML
Signature operations or XML encryption operations, use the Certificate Retrieval
Service by specifying the KeyID (listed in System Configuration, Security Token
Service, Security Token Service Settings and the preferred encoding (der vs pem). For
more information, see "Using the Certificate Retrieval Service".
44.3.3.1 Using the Certificate Retrieval Service
To use the Certificate Retrieval service
1. Retrieve the KeyID of the entry for which the certificate should be retrieved (listed
in Oracle Access Management Console System Configuration tab, Security Token
Service section, Security Token Service Settings).
See Also: "About Security Token Service Settings" on page 43-9
Managing Partner Keys for WS-Trust Communications
Managing Security Token Service Certificates and Keys 44-7
2. Create a URL. For example:
http(s)://osts-hostname:osts-port/sts/servlet/samlcert?id=<KEYID>&encoding=<E
NCODING>, with:
■id holding the KeyID of the entry
■encoding representing the format with which the certificate will be returned.
Possible values are pem (PEM format) or der (DER format). (optional, default
value is pem)
3. Review the certificate returned in the browser.
44.4 Managing Partner Keys for WS-Trust Communications
This topic provides the following information:
■About Partner Certificates
■About Downloading the Relying Party's Certificate at Run Time
■Setting the Partner's Signing or Encryption Certificate
44.4.1 About Partner Certificates
During the processing of the WS-Trust messages, Security Token Service might need to
use a partner's certificate. The certificate needed depends on the situation, as described
in Table 44–3.
Table 44–3 Partner Keys for WS-Trust Communications
If Security Token Service Must ... The OAM Server ...
Issue a SAML Assertion encrypted for the
Relying Party
Uses the Relying Party's encryption certificate to encrypt the
outgoing token
Issue a SAML Assertion with the Subject
Confirmation being of type Holder of Key /
Asymmetric
Uses the Requester Partner's signing certificate as the proof key to
be included in the Assertion
Note: if the WS-Trust RST contains a UseKey element referencing
an X.509 Binary Security Token in the SOAP header that was used
in a signature, then Security Token Service will be able to use this
certificate as the proof key.
Issue a SAML Assertion with the Subject
Confirmation being of type Holder of Key /
Symmetric
Uses the Relying Party's encryption certificate to encrypt the secret
proof key to be included in the Assertion.
Issue a SAML Assertion with the Subject
Confirmation being of type Holder of Key /
Symmetric
Can encrypt in the RSTR for the Requester, the secret or the server
entropy.
In this case, the server:
■uses the Requester's encryption certificate to encrypt the secret
(if the secret was generated using only server entropy)
■or uses the server entropy to encrypt the secret in the RSTR (if
the secret was derived from client and server entropy).
Note: if the WS-Trust RST contains a ProofEncryption element
referencing an X.509 Binary Security Token in the SOAP header
that was used in a signature, then Security Token Service will be
able to use this certificate to encrypt the secret or entropy returned
to the client.
Validate an incoming SAML Assertion Uses the Issuing Authority's signing certificate to verify the XML
digital signature present on the Assertion.
Managing Partner Keys for WS-Trust Communications
44-8 Administrator's Guide for Oracle Access Management
44.4.2 About Downloading the Relying Party's Certificate at Run Time
At runtime, Security Token Service is capable of downloading the Relying Party WSS
Policy of the service listed in the AppliesTo field of the RST. If Security Token Service is
configured to download the Relying Party's WS-Sec policy, then ensure that the Proxy
settings are correctly entered, if needed, so that Security Token Service can connect to
the Relying Party.
If the Relying Party Partner Profile is configured to do so, it instructs Security Token
Service to download the WS-Sec Policy from the service. Security Token Service then
extracts the certificate located in the policy and uses it for cryptographic operations, if
necessary. Also:
■If Security Token Service issues a SAML Assertion encrypted for the Relying Party,
the server uses the certificate downloaded from the Relying Party's WS-Sec Policy
to encrypt the outgoing token.
■If Security Token Service issues a SAML Assertion with the Subject Confirmation
of type Holder of Key / Symmetric, Security Token Service uses the certificate
downloaded from the Relying Party's WS-Sec Policy to encrypt the secret proof
key to be included in the Assertion.
To configure the Relying Party Partner Profile to download the certificate at run time,
see "Setting the Partner's Signing or Encryption Certificate".
44.4.3 Setting the Partner's Signing or Encryption Certificate
To set the signing or encryption certificate of a partner, perform the following
operations.
Alternatively: Use the WLST Partner commands to set the signing or encryption
certificate of a specific partner.
Prerequisites
Review Table 44–3, " Partner Keys for WS-Trust Communications"
To set the certificate of a partner
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Partners from the View drop-down menu in the
Security Token Service section.
3. Select the desired tab (Requesters, Relying Parties or Issuing Authorities (see
Table 44–3)).
4. Search for and open (or Create) the Partner for which the certificate must be set.
5. Edit Partner settings as needed (see "Managing Token Service Partners" on
page 46-3) and click Save.
6. Encryption Certificate: Click the Browse button to locate and choose the
Encryption certificate.
7. Signing Certificate: Click the Browse button to locate and choose the Signing
certificate.
8. Save the information and close the page.
9. Proceed with "Managing Certificate Validation".
Managing Certificate Validation
Managing Security Token Service Certificates and Keys 44-9
44.5 Managing Certificate Validation
This section describes managing certificate validation. Conditions for certificate
validation are described in Table 44–4.
Successful validation requirements are listed in Table 44–5.
Certificate validation requires the Trust Anchors Store (.amtruststore). Procedures for
managing this store and validation are described in following topics:
■Managing the Trust Anchors Store (amtruststore)
■Managing Certificate Revocation Lists
■Using a Custom Trust Anchor Store for Security Token Service
44.5.1 Managing the Trust Anchors Store (amtruststore)
The Trust Anchors keystore is managed using the keytool command. Certificates
added to the keystore are detected by the Certificate Validation module.
Prerequisites
Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password
To manage the Trust Anchors store (amtruststore)
1. Locate keytool.
Table 44–4 Conditions for Security Token Service Certificate Validation
STS Validates a Certificate When ...
The security token to be validated is one of the following types:
■X.509
■X.509v3
■PKCS#7
A SAML Assertion must be validated
Security Token Service is configured to validate the signing certificate of a SAML Issuing Authority
Table 44–5 Successful Certificate Validation Requirements
Certificates Must ... How ...
Be linked to a trusted anchor: ■by being a trusted anchor
■or by having its issuer being a trusted
anchor
Not be revoked:
■by being a trusted anchor
■or by having its issuer being a trusted
anchor
The revocation status of a certificate can be
decided by checking:
■Against a list of CRLs that were uploaded
by the Administrator
■Against an OCSP server
■CRL Distribution Points
Note: Notification is performed using the JMX Notification
Framework and might take some time, depending on the notification
refreshing time (60 seconds by default).
Managing Certificate Validation
44-10 Administrator's Guide for Oracle Access Management
2. Execute the following command.
keytool -keystore $DOMAIN_HOME/config/fmwconfig/amtruststore
-storetype JKS -alias orakey -file $CERT_FILE
3. Observe messages on the screen and enter a password if requested.
4. Proceed to "Managing Certificate Revocation Lists".
44.5.2 Managing Certificate Revocation Lists
Security Token Service uses the common infrastructure certification validation module.
Trusted Certificates and Certificate Revocation Lists (CRLs) used during certificate
validation are stored in Trust Keystore and CRL ZIP file. The Security Token Service
configuration stores the OCSP/CDP settings.
This section outlines how to add or remove certificate revocation lists (CLRs) to check
the revocation status of a certificate, perform the following operations.
Prerequisites
Have your Certificate Revocation List ready to import.
Task overview: Manage Certificate Validation and Revocation Lists
1. From the Oracle Access Management Console System Configuration tab, Common
Configuration section, select Certificate Validation.
2. See "Enabling the Certificate Revocation List Functionality" on page 3-8.
3. See "Enabling OCSP Certificate Validation" on page 3-9:
4. See "Enabling CRL Distribution Point Extensions" on page 3-9.
44.5.3 Using a Custom Trust Anchor Store for Security Token Service
Optionally, if a particular deployment requires a set of trust anchors separate from that
of Access Manager, another keystore can be configured as the trusted certificate store
for Security Token Service. This can be done by having the Administrator perform the
following tasks.
Task overview: Deploying a custom keystore for trusted certificates
1. Create the JKS keystore in the $DOMAIN_HOME/config/fmwconfig directory.
2. In the Oracle Access Management Console, Security Token Service Settings page,
enter the full path name of the new trust store and Apply your changes.
3. In the domain where Security Token Service is deployed, the Custom Trust Anchor
Keystore must be propagated manually by the Administrator across all the
servers.
See Also: "Managing Certificate Validation and Revocation" on
page 3-7
Note: Using a Custom Trust Anchor Store is an optional feature that
most customers will not need.
45
Managing Templates, Endpoints, and Policies 45-1
45
Managing Templates, Endpoints, and Policies
[30]
The Security Token Service must be enabled as documented in Section 43.3, "Enabling
and Disabling Security Token Service."
This chapter provides information about managing the templates, endpoints and
policies for the Security Token Service.
■Introduction
■Searching for an Existing Template
■Managing Token Issuance Templates
■Managing Token Validation Templates
■Managing Security Token Service Endpoints
■Managing Token Issuance Policies, Conditions, and Rules
■Managing TokenServiceRP Type Resources
■Making Custom Classes Available
■Managing a Custom Security Token Service Configuration
45.1 Introduction
The Security Token Service controls who can access a Web Service Provider (WSP) by
defining Application Domains that provide access to resources based on configured
policies. Application Domains identify Web Services and the authorization rules that
determine who can request a security token.
The following functionality is established by Trust Issuance Policies. A Trust Issuance
Policy can be managed by clicking the Application Domains link from the Oracle
Access Management Console Launch Pad.
■Resource of type TokenServiceRP representing Relying Parties or Web Service
Providers.
■Token Issuance Policy defining a policy for a set of resources of type
TokenServiceRP.
■Condition defining the identities of the clients that are allowed or denied issuance
of tokens for the resources listed in the policy. The clients can either be Requester
Partners or User from the Default Identity Store.
Security Token Service supports the creation of Relying Party Partner, representing a
remote Web Service Provider that will be the consumer of a security token issued by
Security Token Service.
Searching for an Existing Template
45-2 Administrator's Guide for Oracle Access Management
For each Relying Party Partner, it is possible to define URLs that will be mapped to the
partner, so that WS-Addressing endpoint specified in a WS-Trust Request can be
mapped to an Security Token Service Relying Party Partner.
At runtime, when a client requests a token to be issued, Security Token Service will
evaluate the Trust Issuance Policies to determine whether or not the token can be
issued:
■The client will be identified either as a Requester Partner or as an end user
■If an AppliesTo element was present in the WS-Trust Request and was mapped to
a Relying Party Partner, then the TokenServiceRP resource for the Trust Issuance
Policy evaluation will be the Partner ID of that Security Token Service Relying
Partner.
■If an AppliesTo element was present in the WS-Trust Request and could not be
mapped to a Relying Party Partner, then the TokenServiceRP resource for the Trust
Issuance Policy evaluation will be the UnknownRP defined in the Access Manager
Application Domain.
■If an AppliesTo element was missing in the WS-Trust Request, then the
TokenServiceRP resource for the Trust Issuance Policy evaluation will be the
MissingRP defined in the Access Manager Application Domain.
Security Token Service requires the following items (at a minimum) to process a
request and issue a token based on an incoming request (RST):
■EndPoints
■One Issuance Template
■One Validation Template
■One Requester Partner Profile that contains the token
■One Relying Party Partner Profile
An LDAP server is required for the Security Token Service to map the Username token
that references the user to an LDAP User record, and then use that record to populate
the outgoing token. Partners might need to be provisioned before they are available.
45.2 Searching for an Existing Template
All defined template names appear in the Search Results Table when you open either
the Token Validation Template or Token Issuance Template node. To quickly find a
specific template or set of templates, you can use the Search controls.
This section explains the controls you can use to refine your search, which are similar
whether you are searching for a Token Validation Template or a Token Issuance
Template. It includes the following topics:
■About Template Search Controls
■Searching For a Template
Note: Partners might need to be provisioned.
Searching for an Existing Template
Managing Templates, Endpoints, and Policies 45-3
45.2.1 About Template Search Controls
The following figures show the search pages where you will see many similarities:
■Figure 45–1, "Validation Templates Search Controls"
■Figure 45–2, "Issuance Template Search Controls"
Figure 45–1 Validation Templates Search Controls
Figure 45–2 Issuance Template Search Controls
Table 45–1 describes the controls available to refine a template search. Unless explicitly
stated, all elements are available for both Validation and Issuance Template searches.
Searching for an Existing Template
45-4 Administrator's Guide for Oracle Access Management
45.2.2 Searching For a Template
Users with valid Administrator credentials can use the following procedure to use
search controls to locate a specific template or set of templates. For example, to locate
all templates of a certain token type you can simply choose the type of token. To refine
the search further to all templates of a specific token type and name.
When performing these steps, fill in as much or as little as you want. Skip any steps
that do not apply to you.
Table 45–1 Search Validation Template
Element Description
Match Choose All to search for a template that matches all your specifications.
Choose Any to search for a template that matches at least one of your specifications.
Search Operations List A list of operations from which you choose one to help refine your search.
... Template Name Choose an operation from the list and enter information in the field to help refine your
search.
Description Refine your search using the optional description field.
Token Protocol
Validation Template only
Choose the token protocol from those listed:
■WS-Trust
■WS-Security
Token type Choose the token type. Both standard and custom token types are included.
■Username: Consumption and Creation
■X.509: Consumption
■SAML: Consumption & Creation
■OAM 11g: Consumption using the OBO (on behalf of) field
■Kerberos: Consumption
■Custom: Consumption the OBO (on behalf of) field and Creation
Search Initiates the Search function using criteria in the form.
Reset Resets the Search form with defaults only.
Add Fields A list of additional items you can add as search criteria.
Search Results Table Itemizes the results of your search based on choices in the View menu, described later in this
table.
Actions menu
Shown: Actions for Validation
Templ a te
Provides the following functions that can be performed on a selection in the results table:
Note: Actions menu functions mirror command buttons above the results table. For example:
■New ... Template: Click the New ... Template button at the top of the Search page, or
select New ... Template from the menu, or click the + button above the table.
■Edit: Click a name in the Results Table, or select Edit from the Actions menu, or click the
Edit (pencil) command button above the Results Table.
■Create Like: Select the desired row in the table and either select Create Like from the
Actions menu, or click the Create Like command button above the table
■Remove: Select the desired row in the Results Table and either select Delete from the
Actions menu, or click the Delete (X) command button above the table.
View menu
Validation Template only
A list from which you can identify Validation Template information to display in the results
table.
View menu
Issuance Template only
A list from which you can identify Issuance Template information to display in the results
table.
Up-Down Arrows Controls you can choose to define the order of items listed in the results table:
■Ascending
■Descending
See Also: "About Template Search Controls"
Managing Token Issuance Templates
Managing Templates, Endpoints, and Policies 45-5
To search for a template
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Token Validation Templates or Token Issuance
Tem pl at es the View menu in the Security Token Service section.
3. Edit Search Criteria (Table 45–1). For example:
■Match: All
■Name: contains em
■Token Type: equals Username
4. Click Search, review results, and click the one you want to open.
45.3 Managing Token Issuance Templates
An issuance template contains rules on how a token will be created and is specific to a
token type. Each issuance template indicates Signing and Encryption and also contains
Attribute Name, Value Mapping, and Filtering settings to be sent as part of the token.
This section provides the following information:
■About Managing Token Issuance Templates
■Managing a Token Issuance Template
45.3.1 About Managing Token Issuance Templates
Each Token Issuance Template indicates how to construct a token. In other words,
which signing or encryption to use when constructing a token. Each Token Issuance
Template also defines the attributes mapping and filtering rules to be applied to the
attributes that will be included in the outgoing token. However, Issuance Templates do
not list the attributes that will be sent in the outgoing token: these are defined in the
Relying Party Partner Profile.
Token Issuance Template details which will differ depending on your chosen token
type. Table 45–2 describes where to find more information.
General Details
Figure 45–3 shows the New Issuance Template page with defaults showing. Unless
explicitly stated, General information is the same regardless of the Token Type you
choose. For more information, see Table 45–3. After you fill in General information and
click Save, you cannot return and edit the template name or token type.
Table 45–2 Issuance Template Requirements
Topic Figures and Tables
General Details Figure 45–3, Table 45–3
Issuance Properties: Username Tokens Figure 45–4, Table 45–4
Issuance Properties: SAML Tokens Figure 45–5, Table 45–6
Security: SAML Tokens Figure 45–6, Table 45–6
Attribute Mapping: SAML Tokens Figure 45–9, Table 45–7
Managing Token Issuance Templates
45-6 Administrator's Guide for Oracle Access Management
Figure 45–3 Issuance Template: General Details and Defaults
Issuance Properties: Username Token Type
If the token type is Username, the Issuance Properties shown in Figure 45–4 are
needed for a Username token type template.
Figure 45–4 Issuance Properties: Username Token Type
Table 45–4 describes the Issuance Properties for the Username token type.
Table 45–3 Issuance Template: General Details
Elements Description
Issuance Template Name Enter a unique name for this template.
Description Optional.
Token Type Choose a standard (or custom, if any) token type from those
listed.
SAML, Username, and Custom
Token Types
Send Encrypted Token Click to enable token encryption.
Token Encryption Algorithm When token encryption is enabled, choose a Token Encryption
Algorithm from those listed.
Table 45–4 Issuance Properties: Username Token Type
Element Description
Name Identifier User
Attribute
Attribute to be used to populate the Username element in the
Username Token.
Managing Token Issuance Templates
Managing Templates, Endpoints, and Policies 45-7
Issuance Properties: SAML Token Types
SAML 1.1 and 2.0 token types require the issuance properties illustrated in
Figure 45–5.
Figure 45–5 Issuance Properties: SAML Token Types
Name Identifier User
Attribute Store
Choose the user attribute store type:
■Userstore
■Context
Note: If the Attribute Store is the Userstore, LDAP is used to
retrieve the attribute from the user record. If the Attribute
Store is context, data from the incoming token is used as the
attribute source.
Password Attribute Attribute to be used to populate the Password element in the
Username Token.
Password Attribute Store Choose the password attribute store type:
■Userstore
■Context
Note: If the Attribute Store is the Userstore, LDAP is used to
retrieve the attribute from the user record. If the Attribute
Store is context, data from the incoming token is used as the
attribute source.
Include Nonce Indicates whether or not a Nonce made of random data
should be included in the Username token.
Default: Disabled
Include Timestamp Indicates whether or not a the Created element should be
included in the Username token.
Default: Disabled
Note: These issuance properties differ from those for Username
token type.
Table 45–4 (Cont.) Issuance Properties: Username Token Type
Element Description
Managing Token Issuance Templates
45-8 Administrator's Guide for Oracle Access Management
Table 45–5 describes all Issuance Properties by token type. Only SAML token types
require issuance properties.
Security Details: SAML Tokens
Only SAML token types require Security Details, as shown in Figure 45–6 and
described in Table 45–6.
Table 45–5 Issuance Properties: SAML Token Types
Element Description
Assertion Issuer Specifies the identifier representing the issuer of the assertion.
This string is used to represent this Security Token Service as
the issuer of the assertion.
Name Identifier Format Choose a format from the list and then enter the details in the
text field. Options may include Custom, Kerberos Principal
Name, Unspecified, X509 Subject Name and others.
Name Identifier Qualifier Contains the string that will be set as the Name Identifier
Qualifier.
Name Identifier User
Attribute
References the attribute that will be used to populate the value
of the Name Identifier.
Name Identifier User
Attribute Store
■Userstore
■Context
Note: If the Attribute Store is the Userstore, LDAP is used to
retrieve the attribute from the user record. If the Attribute
Store is context, data from the incoming token is used as the
attribute source.
Include Authentication
Statement
Indicates whether or not a SAML Authentication Statement
should be included in the Assertion.
Default: Disabled
Note: An authentication operation is required for a statement
of this type to be included. An authentication statement will
be included if the incoming token contained some
authentication data and that those were validated (for
example, the incoming SAML Assertion contains an
authentication statement, or a Username Token contains
credentials that were validated).
Include Attribute Statement Indicates whether or not a SAML Attribute Statement will be
included in the outgoing Assertion.
A statement of this type will be included only if this flag is set
to true and if at least one attribute is included in the outgoing
Assertion.
Default: Enabled
Note: the RP PP will determine which attributes need to be
included in an outgoing token.
Validity Period Specify the length of time (in seconds) that the token will be
valid.
Default: 3600 (seconds)
Managing Token Issuance Templates
Managing Templates, Endpoints, and Policies 45-9
Figure 45–6 Security Details: SAML Tokens
Table 45–6 Security Details: SAML Tokens
Elements Description
Signing And Encryption Indicates whether or not the Assertion will be signed using the Key
referenced by the Signing Keystore Access Template ID field.
Sign Assertion Indicates whether or not the assertion will be digitally signed with a
certificate.
Default: Enabled
Include Certificate in Signature Indicates whether or not the signing certificate will be included in the
Assertion. Default: Enabled
Signing Keystore Access Template
Id
References the key to be used to sign assertions created with this
issuance template. The key templates are defined in the Security
Token Service Settings section.
Send Encrypted Name Identifier Indicates whether the encrypted token name identifier will be sent as
part of the digital assertion signature.
Subject Confirmation
Default Subject Confirmation
Method
Indicates which Subject Confirmation Method will be used by default,
if the requester did not specify a method in the WS-Trust request.
Possible values are:
■Bearer
■Holder of Key with Public Key
■Holder of Key with Symmetric Key
■Sender Vouches
Compute Holder-of-Key
Symmetric Key
Default: Enabled
Indicates whether or not Security Token Service will generate random
data when creating the Secret Key for the Holder of Key Symmetric
Key data.
■If true, the server will generate the secret key if the client did not
specify entropy. Otherwise it will derive the key from the client
and server entropy
■If false, the client entropy will be used as the secret key
Managing Token Issuance Templates
45-10 Administrator's Guide for Oracle Access Management
Attribute Mapping: SAML Tokens
When the token type is SAML 1.1 or 2.0, it is possible to define attribute mapping and
filter rules that will be applied to the attributes included in the Assertion.
There are three different rules:
■Attribute name mapping where the local name of an attribute can be changed to
another value. For example, givenname can be changed to firstname.
■Attribute value mapping where the local value of an attribute can be translated to
another value. For example, President to CEO.
■Attribute value filtering where the local value of an attribute can be filtered so it is
not included in the outgoing assertion. For example, some sensitive attribute
values could be removed while others would be issued.
Encrypt RSTR Proof Token Indicates whether or not the Proof Token must be encrypted when
returning the server entropy or secret key to the requester in the
WS-Trust response, when the Subject Confirmation method is Holder
of Key with Symmetric Key
Default: Disabled
Holder-of-Key Symmetric Key
Generation Algorithm
Select the symmetric key generation algorithm that will be used to
create the secret key when the Subject Confirmation method is Holder
of Key with Symmetric Key:
See Also: Token Mapping attributes in Figure 45–9 and Table 45–11.
Table 45–7 Issuance Template: Attribute Mapping, SAML Token
Element Description
Attribute Name Mapping Defines an optional mapping between the local name of an attribute, and
the name used to reference this attribute in the assertion.
The mapping is optional. If an attribute does not have a mapping defined,
then its local name will be used, and the namespace will be set to
urn:oracle:security:fed:attrnamespace
for SAML 1.1 Assertions or the
format will be set to
urn:oasis:names:tc:SAML:2.0:attrname-format:basic
for SAML 2.0
Assertions.
■External Attribute: Contains the externam name of the attribute as it
will appear in the Assertion.
■Local Attribute: Contains the local name of the attribute.
■Format of Namespace: Contains an optional Format or Namespace. If
missing, the namespace will be set to
urn:oracle:security:fed:attrnamespace for SAML 1.1 Assertions or the
format will be set to
urn:oasis:names:tc:SAML:2.0:attrname-format:basic for SAML 2.0
Assertions.
Table 45–6 (Cont.) Security Details: SAML Tokens
Elements Description
Managing Token Issuance Templates
Managing Templates, Endpoints, and Policies 45-11
Attribute Value Condition Filters
This optional value filtering applies to an Attribute Name mapping and will be
included in the Assertion. To define an attribute filtering for an attribute, you must
first define an attribute name mapping for that attribute. The Condition is associated
with the expression to determine whether or not the attribute value should be filtered.
The possible Condition values are:
■regexp: the expression will contain a regular expression, and if it evaluates to true,
the attribute value will be filtered.
■equals: if the attribute value matches the data contained in the expression field,
then it will be filtered.
■not-equals: if the attribute value does not match the data contained in the
expression field, then it will be filtered.
■not-equals: if the attribute value does not match the data contained in the
expression field, then it will be filtered.
■endswith: if the attribute value ends with the data contained in the expression
field, then it will be filtered.
■contains: if the attribute value contains an occurrence of the data contained in the
expression field, then it will be filtered.
■not-contains: if the attribute value does not contains any occurrence of the data
contained in the expression field, then it will be filtered.
■equals-null: if the attribute value is null, then it will be filtered.
Attribute Value Mapping Defines an optional value mapping for an attribute that will be included in
the Assertion.
Note: this attribute value mapping applies to an Attribute Name mapping.
In order to define an attribute mapping for an attribute, it is required to
first define an attribute name mapping for that attribute.
■External Attribute: Contains the value that should be included in the
Assertion, if the local attribute value matches the Local
Attribute/Local Null fields.
■Local Attribute: Contains the local value of the attribute.
■External Null: Indicates if the value to be included in the Assertion
should be null, if the local value of the attribute matches the Local
Attribute/Local Null fields.
■Local Null: Represents a null local value.
■Ignore Case: Indicates whether or not Security Token Service should
ignore case when comparing the attribute value to the Local Attribute
field.
Attribute Value Filters Defines an optional value filtering for an attribute that will be included in
the Assertion.
Note: This attribute value filtering applies to an Attribute Name mapping.
In order to define an attribute filtering for an attribute, it is required to first
define an attribute name mapping for that attribute.
■Condition: Contains the condition associated with the expression to
determine whether or not the attribute value should be filtered. The
possible values are described in "Attribute Value Condition Filters".
■Expression: Contains data that will be used to evaluate the filtering
rule.
■Ignore Case: Indicates whether or not Security Token Service should
ignore case when comparing the attribute value to the expression
field.
Table 45–7 (Cont.) Issuance Template: Attribute Mapping, SAML Token
Element Description
Managing Token Issuance Templates
45-12 Administrator's Guide for Oracle Access Management
■not-equals-null: if the attribute value is not null, then it will be filtered.
45.3.2 Managing a Token Issuance Template
Users with valid Oracle Access Management Administrator credentials can use this
procedure as a guide when developing a new Token Issuance Template (or editing an
existing template) Skip any steps that do not apply to you.
The following procedure describes how to create a new Token Issuance Template for a
Security Assertion Markup Language (SAML) token.
Prerequisites
Confirm that the desired LDAP Identity Store is registered with and configured as the
Default Store.
To create a new token issuance template
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Token Issuance Templates the View menu in the
Security Token Service section.
3. New Token Issuance Template:
a. Click the New Issuance Template button in the upper-right corner (or click
the Add (+) button above the Search Results table).
b. General: Define general information for this template and see:
Table 45–3, " Issuance Template: General Details"
c. Click Save and dismiss the confirmation window (or click Cancel without
saving).
d. Username Token Type: Define issuance parameters for this template and see:
Table 45–4, " Issuance Properties: Username Token Type"
e. SAML Token Type: Define parameters for this template and see:
Table 45–5, " Issuance Properties: SAML Token Types"
Table 45–6, " Security Details: SAML Tokens"
Table 45–7, " Issuance Template: Attribute Mapping, SAML Token"
f. Click Apply (or click Revert without saving it).
g. Close the definition.
4. Find an Existing Template: From the Token Issuance Templates page:
a. Find All: review the results table. All templates are returned by default when
you access the Issuance Templates page.
b. Narrow the Search: Specify your search criteria (Table 45–1), click the Search
Button, and review the results table.
c. Reset the Search Form: Click the Reset button.
See Also:
■About Managing Token Issuance Templates
■Searching for an Existing Template
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-13
5. Edit a Template: Start with the saved page you just created.
Alternatively: Use Step 3 to find the desired template and click the name in the
Search Results table to display the definition.
a. Edit details as needed.
b. Click the Apply button at the top of the page to submit changes (or Revert to
undo your changes).
6. Remove a Template:
a. Click the desired name in the Search Results table to select the item to remove.
b. From the Actions menu, click Delete (or click the Delete (X) command button
above the table.
c. Click the Delete button in the Confirmation window (or click No to cancel the
operation).
45.4 Managing Token Validation Templates
A validation template is used to validate an incoming token and, optionally, map the
incoming token to either a Requester Partner or a user record:
■For OnBehalfOf use cases, a WS-Trust Validation Template must be present.
■For validating an Assertion, one Issuing Authority Partner Profile must be present.
The Security Token Service Endpoint is linked to a WSS Validation Template that
indicates how to validate the token in the WSS header and how to map the token and
binding data to a Requester.
This section provides the following topics.
■About Managing Token Validation Templates
■Managing Token Validation Templates
45.4.1 About Managing Token Validation Templates
A Security Token Service Endpoint is always mapped with a WS-Security Validation
Template that indicates how to map the request to a requester entry or to a user:
■If mapping is required and no match is found, processing will fail.
■If no mapping is required, a default requester partner profile will be used.
■In either case, a requester partner profile is retrieved.
■If a mapping is performed to a user record, a default requester partner profile will
be used.
■If a mapping is performed to a requester partner entry, the requester partner
profile for this partner will be used.
A validation template determines the token validation rules:
■Whether or not to validate and map the incoming token.
■The mapping rules to be used if mapping is enabled.
A validation template is specific to a token type and specific to a protocol as described
in Table 45–8.
Managing Token Validation Templates
45-14 Administrator's Guide for Oracle Access Management
A validation template mapping rules determines how the incoming data is mapped to
a user or a partner, using data from the incoming token:
■Username for Username Token
■UserID for Kerberos Token
■NameID and attributes for SAML Token
■DN Components for X.509 Token
■Attributes from a Custom
Mapping is performed as follows:
■Simple mapping: one incoming attribute matched against one user record
attributes
■Complex LDAP query: LDAP query with placeholders for incoming data (e.g.:
(&(sn=%lastname%)(mail=%email%))
■NameID Mapping table for SAML Token
Figure 45–7 illustrates default General details on the New Validation Template page.
Figure 45–7 New Validation Template page: General Page Defaults
Table 45–9 describes the elements on the New Validation Template, General page.
Table 45–8 Validation Template Protocols
Protocol Description
WS-Security Validates only WS-Security Tokens:
■Possible Mapping actions: no action, map binding data to partner, map
incoming token to partner, map incoming token to user and binding data to
partner, map incoming token to user
■Token Types supported: SAML 1.1, SAML 2.0, Username X.509, Kerberos,
None.
When you toggle the Token Protocol from WS-Trust to WS-Security, options in
the Token Type list do not change. However, the required "Default Partner
Profile" list appears from which you must choose one profile for WS-Security.
WS-Trust Validates only Tokens included in OBO (on behalf of) field of the RST (request):
■Possible Mapping actions: none, map incoming token to user
■Token Types supported: SAML 1.1, SAML 2.0, Username, X.509, Kerberos,
OAM, Custom.
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-15
Figure 45–8 illustrates the General details page when Enable Credential Validation is
checked and, as a result, the Authentication Details section of the page is visible with
its default values. This is specific to username token validation.
Table 45–9 New Validation Template: General Details
Element Description
Back Click this button to return to the previous page.
Next Click this button to proceed to the next page.
Cancel Click this button to dismiss the page.
Validation Template Name The name you choose for this template. For example:
email-wstrust-valid-temp
Description Optional.
Token Protocol The type of Validation Template to be created. Type can be either:
■WS-Trust: This template will be used to validate and map tokens
included in the OnBehalfOf element of the WS-Trust request.
■WS-Security: This template will be used to validate and map tokens
located in the Security SOAP Header of the incoming message
Token Type A list of in-bound token types from which you choose the one to use for this
template. The token type options depends on the protocol type:
■WS-Trust: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM,
Custom
■WS-Security: SAML 1.1, SAML 2.0, Username, X,509, Kerberos, None
Default Partner Profile Only applies to WS-Security Validation Template
References the default requester partner profile to use, in case the incoming
request is not mapped to a requester partner. For example, if the request is
mapped to a user instead.
A requester partner profiles contains settings that are used during the
request processing. If the incoming request was mapped to a requester
partner, then the partner profile for that requester will be retrieved and used
as the requester partner profile
Timestamp Lifespan Applies only to Username and SAML Validation Templates. It determines the
validity time of a Token (for Username Token, only if it contains a Created
element indicating the instant it was created).
Default: 1000 (seconds)
Authentication Details Specific to username token validation template.
Enable Credential
Validation
Check this box to enable validation using credentials contained in the
username token.
When enabled, Security Token Service will validate the username and the
password elements contained in the username token, using the specified
validation source.
Note: password digest as defined in the Username Token WS-Security Profile
is not supported in this release.
See Also: Table 45–10, " New Validation Template: Authentication Details"
Managing Token Validation Templates
45-16 Administrator's Guide for Oracle Access Management
Figure 45–8 New Validation Template: General Authentication Details
Table 45–10 describes Authentication related details that are available when you
choose Enable Credential Validation.
Table 45–10 New Validation Template: Authentication Details
Element Description
Validation Source A list from which you can choose a credential validation sources
There are four types of validation sources when validating the credentials
contained in a username token:
■LDAP: a standalone LDAP server will be used to validate the credentials.
The connection information will need to be entered
■Embedded LDAP: the LDAP server embedded in the WebLogic server will
be used to validate the credentials. No information is required.
■Userstore: the default User Identity Store configured in the Common
Configuration -> Data Sources will be used to validate the credentials. No
information is required in this validation template screen
■Partner: the credentials will be verified against the username/password
information entered in the Requester Partner entries.
Note: When selected, the Token Mapping configuration section is disabled,
because the token will have been mapped to a requester partner after the
credentials validation operation.
LDAP URL The URL of the LDAP server.
Admin User The username of an account used to perform lookups in the LDAP server.
Admin Password The password of an account used to perform lookups in the LDAP server.
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-17
Token Mapping
The Token Mapping section indicates the following:
■If an incoming token needs to be mapped.
■If the incoming token needs to be mapped, what kind of mapping is done. For
example, mapping token to user, mapping token to partner, and so on.
■How the mapping is done. For example, by mapping a token attribute to a
partner/user attribute, or by using an LDAP query involving several token
attributes.
Mapping rules determine how the incoming data is mapped to a user or a partner. The
following data of the incoming token is used:
■Username for UNT
■UserID for Kerberos
■NameID and attributes for SAML
■DN Components for X.509
■Attributes from custom
Mapping is performed using the following:
■Simple mapping: One incoming attribute matched against one user record
attributes.
■Complex LDAP query: An LDAP query with placeholders for incoming data. For
example,
(&(sn=%lastname%)(mail=%email%))
■A NameID Mapping table for SAML
Following are several Token Mapping Examples for a new Validation Template:
■Figure 45–9, "Token Mapping: SAML2 WS-Security Validation Template"
■Figure 45–10, "Token Mapping, username-wstrust-validation-template"
■Figure 45–11, "Token Mapping: x509-wss-validation-template"
Base DN The Base search DN used when looking up user records.
Enable HA Indicates whether or not the LDAP server is in HA mode, fronted by a load
balancer.
Person Object Class The person object class associated with the user records.
Unique Id The attribute of the user record containing the user unique identifier data.
In most cases, is identical to the Credential ID field.
Credential Id The attribute of the user record containing the username data. This field will be
used to lookup user records, based on the username.
Maximum Connections The maximum number of concurrent opened LDAP connections
Default: 50
Connection Wait
Timeout
Maximum amount of time to wait when opening a new connection.
Default: 5000 (seconds)
Connection Inactivity
Timeout
Maximum amount of inactivity time for an LDAP connection, before closing it.
Default: 5000 (seconds)
Connection Read
Timeout
Maximum number of concurrent opened LDAP connections.
Default: 5000 (seconds)
Table 45–10 (Cont.) New Validation Template: Authentication Details
Element Description
Managing Token Validation Templates
45-18 Administrator's Guide for Oracle Access Management
Figure 45–9 shows the mapping configuration settings required for Security Token
Service to map the token to a user record, by matching the NameID value to user
records that have a matching attribute, based on the NameID format:
■Enable Map Token to User
■Enable Simple User Mapping
■Disable Attribute Based User Mapping
Figure 45–9 Token Mapping: SAML2 WS-Security Validation Template
Figure 45–10 shows the mapping configuration settings required for Security Token
Service to map the token to a user record by matching the username element of the
Username token to a user record that has a matching uid. The required settings are:
■Enable Map Token to User
■Enable Simple User Mapping
■Datastore Attribute set to uid
■Disable Attribute Based User Mapping
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-19
Figure 45–10 Token Mapping, username-wstrust-validation-template
Figure 45–11 shows the mapping configuration settings required for Security Token
Service to map the token to a requester partner entry by matching the Subject DN of
the certificate to a Requester Partner that has a match on SSL Client Cert DN
Identification attribute. The required settings are:
■Map Token to Partner
■Disable Simple User Mapping
■Disable Attribute Based User Mapping
■Enable Simple Partner Mapping
Figure 45–11 Token Mapping: x509-wss-validation-template
Managing Token Validation Templates
45-20 Administrator's Guide for Oracle Access Management
Not all elements apply to all token types and token protocols. The elements that you
must define will vary.
Table 45–11 describes the token mapping elements for validation templates.
Table 45–11 New Validation Template: Token Mapping
Element Description
Map Token to WS-Security Validation Template: Map Token to list
■<empty>: no token mapping operation will occur
■Map token to Partner: The token will be mapped to a requester partner
■Map Token to User and map binding data to Partner: The token will be
mapped to a user, and binding data (such as SSL Client Cert DN or HTTP
Basic Auth Username) will be used to map the HTTP request to a requester
partner
■Map token to User: The token will be mapped to a user
- - - - - - - - - -
WS-Trust Validation Template: Map Token to User
Check the box to enable (or clear the checkbox to disable).
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-21
Enable Simple User
Mapping
Simple user mapping consists of mapping the incoming token to a user record by
using a single token attribute and matching it against a single user record
attribute.
WS-Security Validation Template: Only Username, SAML Assertion, Kerberos.
and X.509.
WS-Trust Validation Template: Username, SAML Assertion, Kerberos, X.509,
OAM and custom token. The layout is different, depending on the token type of
this validation template:
Username Token:
■Datastore attribute references the user record attribute that will be matched
against the username element of the username token.
SAML Assertion:
■User Token attribute references an attribute from the incoming token that
will be matched against the Datastore attribute (defined below) of a user
record. The values can be STS_SUBJECT_ID for the NameID Value, or the
name of an Attribute contained in the Assertion's AttributeStatement.
In the Token Mapping section of a SAML Validation template, the User
Token Attribute will either be the NameID selected from the drop down or a
SAML Attribute name entered in the text field.
■Datastore attribute references the user record attribute that will be matched
against the User token attribute referenced above.
In the Token Mapping section of a SAML Validation template, the Datastore
Attribute is the name of the directory attribute that will be used for the
LDAP matching query.
Kerberos:
■User Token attribute references an attribute from the incoming token that
will be matched against the Datastore attribute (defined below) of a user
record. The User Token Attribute can be specified by selecting one of the
pre-populated attribute (Kerberos Principal, Kerberos Principal Primary or
Kerberos Principal No Domain) or by entering a specific value.
■Datastore attribute references the user record attribute that will be matched
against the User token attribute referenced above.
X.509:
■User Token attribute references an attribute from the incoming token that
will be matched against the Datastore attribute (defined below) of a user
record. The User Token Attribute can be specified by selecting one of the
pre-populated attribute (Subject DN, Common Name, Country Name, State
or Province Name, Locality Name, Organizational Name, Organizational
Unit Name or Domain Component) or by entering a specific value (which
can be set to STS_X509_### by replacing ### with the upper case X.500
component name, for example STS_X509_CN to reference the common name
component of the certificate subject).
■Datastore attribute references the user record attribute that will be matched
against the User token attribute referenced above.
OAM:
■Datastore attribute references the user record attribute that will be matched
against the username element of the username token. Should be the user ID
attribute defined in the Default User Identity Store.
Custom:
■User Token attribute references an attribute from the incoming token that
will be matched against the Datastore attribute (defined below) of a user
record. The possible values are the names of the attribute returned by the
custom token validation module.
■Datastore attribute references the user record attribute that will be matched
against the User token attribute referenced above.
Table 45–11 (Cont.) New Validation Template: Token Mapping
Element Description
Managing Token Validation Templates
45-22 Administrator's Guide for Oracle Access Management
Enable User Name
Identifier Mapping
When enabled, define the following:
WSS and WS-Trust Validation Templates will contain the same section for the
Name Identifier mapping settings.
A NameID user mapping operation consists of mapping the incoming SAML
Assertion to a user record by mapping the NameID Value to a single user record
attribute, based on the NameID format
When enabled, Security Token Service evaluates the NameID format, and based
on the Name Identifier mapping table which user record attribute should be
matched against the Name ID value contained in the Assertion. The Name
Identifier mapping table holds the user record attributes to be used for the
mapping operation. It contains standard NameID formats, but it can be
customized to define custom Name ID formats.
To add custom NameID format, click the add button on the Name Identifier
mapping table, and enter the custom URI.
To set an attribute for a specific NameID format to be used for mapping operation,
set the user record attribute on the line for that format.
Enable Attribute
Based User Mapping
WSS Validation Template: only Username, SAML Assertion, Kerberos and X.509.
WS-Trust Validation Template: only Username, SAML Assertion, Kerberos, X.509
and custom token
An Attribute Based User Mapping operation consists of mapping the incoming
token to a user record by using an LDAP query and token attributes. The format
of the LDAP query defines the mapping rule and specifies the token attributes to
be used by their names, surrounded by the percent (%) character. For example, an
LDAP query that will map a token based on two token attributes (firstname and
lastname) would be (&(sn=%lastname)(givenname=%firstname%)).
The possible token attributes depend on the token type.
Username Token
■STS_SUBJECT_ID is the only available token attribute containing the
username element of the Username token.
SAML Assertion
■STS_SUBJECT_ID contains the NameID Value.
■STS_NAMEID_FORMAT contains the NameID Format
■STS_NAMEID_QUALIFIER contains the NameID Qualifier
■STS_SAML_ASSERTION_ISSUER contains the Issuer of the Assertion
■Attributes present in the Assertion's AttributeStatement
Kerberos
■STS_KERBEROS_PRINCIPAL_SHORT contains the Kerberos Principal
attribute.
■STS_KERBEROS_PRINCIPAL_FULL contains the Kerberos Principal
Primary attribute
■STS_KERBEROS_PRINCIPAL_NODOMAIN contains the Kerberos Principal
No Domain attribute
X.509
■STS_SUBJECT_ID contains the Subject DN.
■STS_X509_CN contains the Common Name
■STS_X509_C contains the Country Name
■STS_X509_ST contains the State or Province Name
■STS_X509_L contains the Locality Name
■STS_X509_O contains the Organizational Name
■STS_X509_OU contains the Organizational Unit Name
■STS_X509_DC contains the Domain Component
Custom Token
■The possible values are the names of the attribute returned by the custom
token validation module.
Table 45–11 (Cont.) New Validation Template: Token Mapping
Element Description
Managing Token Validation Templates
Managing Templates, Endpoints, and Policies 45-23
45.4.2 Managing Token Validation Templates
This is a server side configuration. A default Token Validation Template exists. Users
with valid Administrator credentials can use can use the procedure in this section to
add, find, edit, or delete token validation templates. Skip any steps that you do not
need.
Enable Simple Partner
Mapping
Only for WSS Validation Template and for the following token types: Username,
SAML Assertion, Kerberos, and X.509.
A simple partner mapping operation consists of mapping the incoming token to a
partner requester by using a single token attribute and matching it against a
partner identification attributes.
The layout is different, depending on the token type of this validation template
Username Token
■Partner Datastore attribute references the partner identification attribute that
will be matched against the username element of the username token.
SAML Assertion
■Partner Token attribute references an attribute from the incoming token that
will be matched against the Partner Datastore attribute (defined below) of a
Requester Partner. The values can be STS_SUBJECT_ID for the NameID
Value, or the name of an Attribute contained in the Assertion's
AttributeStatement.
■Partner Datastore attribute references the partner identification attribute that
will be matched against the Partner token attribute referenced above
Kerberos
■Partner Token attribute references an attribute from the incoming token that
will be matched against the Partner Datastore attribute (defined below) of a
requester partner. The Partner Token Attribute can be specified by selecting
one of the pre-populated attribute (Kerberos Principal, Kerberos Principal
Primary or Kerberos Principal No Domain) or by entering a specific value.
■Partner Datastore attribute references the partner identification attribute that
will be matched against the Partner token attribute referenced above
X.509
■Partner Token attribute references an attribute from the incoming token that
will be matched against the Partner Datastore attribute (defined below) of a
requester partner. The Partner Token Attribute can be specified by selecting
one of the pre-populated attribute (Subject DN, Common Name, Country
Name, State or Province Name, Locality Name, Organizational Name,
Organizational Unit Name or Domain Component) or by entering a specific
value (which can be set to STS_X509_### by replacing ### with the upper
case X.500 component name, for example STS_X509_CN to reference the
common name component of the certificate subject).
■Partner Datastore attribute references the partner identification attribute that
will be matched against the Partner token attribute referenced above.
Enable Partner Name
Identifier Mapping
When enabled, defines the following only for WSS Validation Template and for
SAML token types:
A NameID user mapping operation consists of mapping the incoming SAML
Assertion to a user record by mapping the NameID Value to a single requester
partner identification attribute, based on the NameID format.
When enabled, Security Token Service will evaluate the NameID format, and
based on the Name Identifier mapping table which partner identification attribute
should be matched against the Name ID value contained in the Assertion. The
Name Identifier mapping table holds the requester partner identification
attributes to be used for the mapping operation. It contains standard NameID
formats, but it can be customized to define custom Name ID formats.
To add custom NameID format, click the Add button on the Name Identifier
mapping table, and enter the custom URI.
To set an attribute for a specific NameID format to be used for mapping operation,
set the requester partner identification attribute on the line for that format.
Table 45–11 (Cont.) New Validation Template: Token Mapping
Element Description
Managing Token Validation Templates
45-24 Administrator's Guide for Oracle Access Management
The Security Token Service Endpoint must be linked to a WS Security Validation
Template that indicates:
■how to validate the token in the Webservice Security header
■how to map the token and binding data to a Requester
The information here can be applied when you want to validate the following:
■WS-Security tokens present in the SOAP Header, of type: Username, SAML 1.1,
SAML 2.0, X.509 and Kerberos.
■WS-Trust tokens present in the OnBehalfOf element or in the ValidateTarget
element of the WS-Trust request, of type: Username, SAML 1.1, SAML 2.0, X.509,
Kerberos, OAM Session Propagation Token and custom tokens.
The following procedure includes several examples of input following specific
parameters. Also, a brief translation appears within parentheses (). For instance: Name
(username-token):
email-wstrust-valid-temp
. Values in your environment will be
different.
Prerequisites
To manage token validation templates
1. Locate and open the desired Token Validation Template as described in "Searching
For a Template" on page 45-4.
2. New Token Validation Template:
a. Click the New Validation Template button in the upper-right corner (or click
the Add (+) command button above the Search Results table).
b. General: Define parameters for this template (Table 45–9). For example:
Name (username-token):
email-wstrust-valid-temp
Token Protocol (WS-Security for token protocol): Webservice
Token Type (username):
email
Default Partner Profile:
requester-profile
c. Authentication: Enable Credential Validation for this template, if needed, and
provide details (Table 45–10). If the token type is username, enable credential
validation if needed for this template and provide the details.
d. Token Mapping: Specify preferences for this template based on your token
type (Table 45–11).
e. Click Save and dismiss the confirmation window (or click Cancel without
saving it).
f. Close the definition (or edit it as described in Step 4).
3. Edit a Template: Start with the saved page you just created.
a. Edit the template definition as needed.
b. Click the Apply button at the top of the page to submit changes (or click
Revert to undo your changes).
See Also:
■"About Managing Token Validation Templates"
■"Searching for an Existing Template"
Managing Security Token Service Endpoints
Managing Templates, Endpoints, and Policies 45-25
4. Remove a Token Validation Template:
a. Click the desired name in the Search Results table to select the item to remove.
b. From the Actions menu, click Delete (or click the Delete (X) command button
above the table.
c. Click the Delete button in the Confirmation window (or click No to cancel the
operation).
45.5 Managing Security Token Service Endpoints
An endpoint is a Web Service published by Security Token Service where clients can
send WS-Trust requests over SOAP. An endpoint is:
■Protected by a WS Security Policy.
■Bound to WSS Validation Template that will indicate how to validate the security
token and how to map it.
■Specific to a token type, namely, the one specified in the WSS Validation Template.
An endpoint is a Web Service endpoint published by Security Token Service and
protected by OWSM Agent. An endpoint is bound to:
■A WS-Security policy that will determine the WSS requirements in terms of
message protection and security tokens
■A WSS Validation template that will indicate how the request will be processed,
how the security token will be validated.
This section provides the following information:
■About Managing Endpoints
■Managing EndPoints
45.5.1 About Managing Endpoints
Security Token Service Endpoint definitions consist of three categories, as shown in
Figure 45–12.
Figure 45–12 Endpoints Page
Note: The WS-Security policy protecting the endpoint must be
compatible with the WSS Validation Template bound to the endpoint.
Managing Security Token Service Endpoints
45-26 Administrator's Guide for Oracle Access Management
Table 45–12 describes the required Endpoints categories.
Once an Endpoint is created, you can remove it but you cannot edit the definition.
45.5.2 Managing EndPoints
Users with valid Oracle Access Management Administrator credentials can perform
the following task to add, edit, or remove an Endpoint.
Prerequisites
Creating a Token Validation Template to reference
To create or delete an endpoint
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Endpoints from the View menu in the Security
Token Service section.
3. New Endpoint: see Table 45–12 and
a. Click the Add (+) button above the table (or choose New Endpoint from the
Actions menu).
b. Enter the new Endpoint URI.
c. Choose one of the Oracle WSM policies to protect this Endpoint.
d. Choose the Validation Template to use with this Endpoint.
e. Click Apply to submit the definition and dismiss the confirmation window (or
click Revert to dismiss the page without submitting it).
f. Close the page.
4. Remove Endpoint:
a. Highlight a row in the Endpoints table and click the Delete (X) button (or
choose Delete Selected from the Actions menu).
b. Confirm removal (or cancel the removal).
Table 45–12 Endpoints Page
Elements Description
Endpoint URI The path to the Endpoint, relative to the Security Token Service
base URL The Security Token Service base URL is /sts.
Policy URI Choose from a listing of Oracle WSM policies the one used to
protect this Endpoint.
Oracle Access Management Administrators can add a new
custom policy to the available listing.To show this newly
created Policy URI in the endpoints table list, use the following
wlst command to update the owsmpolicies map:
putStringProperty("/stsglobal/owsmpolicies/<index>",
"<newcustom_policypath>)
For example:
putStringProperty("/stsglobal/owsmpolicies/31",
"sts/newcustom_policy")
Validation Template ID Choose from a listing of Validation Template names to identify
one for use with this Endpoint.
Managing Token Issuance Policies, Conditions, and Rules
Managing Templates, Endpoints, and Policies 45-27
45.6 Managing Token Issuance Policies, Conditions, and Rules
This section provides the following topics:
■About Token Issuance Policies
■About Managing Token Issuance Conditions and Rules
■Managing Token Issuance Policies and Conditions
45.6.1 About Token Issuance Policies
A Token Issuance Policy defines the rules under which a token can be issued for a
resource (Relying Party Partner) based on the client's identity, with the client either
being a Requester Partner or an end user. If a Requester is NOT present, it is assumed
that the User (represented by the on-behalf-of (OBO) token or WSS Token) is trying to
access the RelyingParty.
When issuing a token, Security Token Service will determine for which Relying Party
that token is created, and it will then evaluate if the client is authorized to request the
token for that Relying Party. In order to issue a token, a Token Issuance Policy must be
created with the resource involved in the operation, and with possibly a condition. At
runtime if the policy evaluation is successful, the token will be issued.
You can add Conditions, Rules, and Responses to this Token Issuance Policy.
45.6.2 About Managing Token Issuance Conditions and Rules
The Token Issuance Policy allows the Administrator to define conditions along with
"Allow" and "Deny" rules for the policy. Each Token Issuance Policy can contain one or
more conditions, and rules that determine whether access to the requested resource
should be granted or denied:
■An Allow type rule specifies who is authorized to access a protected resource.
Only partners and users listed in the Condition are granted access; everyone else is
denied access to the resource.
■A Deny type rule specifies explicitly who is denied access to the protected
resource.
Only partners and users listed in the Condition are denied access; everyone else is
granted access to the resource.
Managing Token Issuance Conditions is similar to managing Authorization
Conditions and Rules. Figure 45–4 shows the Conditions tab of a Token Issuance
Policy.
Note: When adding User conditions, the identity store from which
the users are to be chosen can be selected from a list. Ensure that you
choose the Default User Identity Store, which is the only one used by
Security Token Service.
Managing Token Issuance Policies, Conditions, and Rules
45-28 Administrator's Guide for Oracle Access Management
Figure 45–13 Token Issuance Policies and Conditions
Table 45–13 describes the Token Issuance Condition requirements.
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social" for details about Adding a Token Issuance Policy for
Mobile and Social Authentication Service
Table 45–13 Conditions tab: Token Issuance Policy
Element Description
Summary tab
Name A unique name for this Token Issuance Policy.
Description Optional.
Conditions tab Table 25–11 describes elements and controls on the Conditions tab.
Class Only Token Requester Identity is allowed for Token Issuance Policy
conditions. You choose this in the Add Condition dialog box.
Rules tab Table 25–22 describes the elements and controls on the Rules tab for
Simple Mode evaluations.
Table 25–23 describes the elements on the Rule tab in Expression mode.
Condition Details
Managing Token Issuance Policies, Conditions, and Rules
Managing Templates, Endpoints, and Policies 45-29
45.6.3 Managing Token Issuance Policies and Conditions
Users with valid Administrator credentials can use the following procedure to add a
Token Issuance Policy and Conditions to an Application Domain. When adding
resources to this policy, you might want to add the UnknownRP and MissingRP
resources.
Prerequisites
The Application Domain must already exist.
To manage Token Issuance Policies and conditions
1. Locate the desired domain as described in "Searching for an Existing Application
Domain" on page 25-12.
2. On the individual Application Domain page, select the Token Issuance Policies
tab.
3. Create a Token Issuance Policy:
a. In the desired domain, click the Token Issuance Policies tab and then click the
Create Token Issuance Policy button to open a fresh page.
b. On the Summary page, enter a unique name and optional description.
4. Add Resources: This step presumes that the resource has been defined in the
Application Domain and is ready to be added to policies.
a. Click the Resources tab.
b. Click the Add (+) button.
c. Click the Search button to display a list of defined resources you can add.
d. Click the desired resource in the results table, then click Add Selected.
e. Repeat as needed to add any other resources to this policy.
Add Choose from the following populations:
■Add Identities: This choice opens a Search window where you can
set the Store Name, Choose an Entity Type (All, User, or Group),
and Provide an Entity Name. You then choose one or more results
from those listed and click Add Selected to populate the condition.
■Add Partners: This choice opens a Search window where you can
locate specific partners to populate the condition. Enter your search
criteria (or click the arrow key beside the field to find all partners),
then choose one or more results and click Add Selected to populate
the condition.
Entity Name The name of the User or Group, as defined in the selected User Identity
Store.
Entity Type The type of entity you want to locate during a search to add identifies to
the condition: User, or Group.
Store Name Choose the name of the User Identity Store to search for users or groups
to populate the condition. Remember, Security Token Service uses only
the Default Identity Store.
Note: You can add Token Issuance Policies to the IAM Suite
Application Domain.
Table 45–13 (Cont.) Conditions tab: Token Issuance Policy
Element Description
Managing TokenServiceRP Type Resources
45-30 Administrator's Guide for Oracle Access Management
5. Add Conditions to a Policy: The only types available are Token Requester
Identity or Tru e.
a. Click the Conditions tab, then click the Add button on the Conditions tab to
display the Add Condition window.
b. Enter a unique name for this condition in the dialog box.
c. Choose Token Requester Identity from the Type list.
d. Click Add Selected.
e. Proceed with Step 5 to add details for Token Requestor Identity. Otherwise,
skip to Step 6.
6. Add Conditions Details:
a. Click the Condition name to display Conditions: Details.
b. From the Selected Identities table, click the Add button and choose either:
Add Partners: In the Search field, enter criteria (or click the arrow key beside
the field to find all partners); click one or more results then click Add Selected
to populate the condition.
Add Identities: Select the Store Name, select the desired Identity Type, enter
search criteria and click the Search button; choose one or more results and
click Add Selected to populate the condition.
c. Click the Save button on the Condition Details panel.
7. Add Rules: Perform these steps to Allow or Deny access based on your
Conditions.
a. Click the Rules tab.
b. Check the Rule Mode: Simple or Expression.
c. Expression Mode: Build your expression by entering operators (Table 25–24)
and choosing and inserting conditions (Table 25–23).
d. Simple Mode: Click to Match either All or Any of the selected conditions,
then using arrows for Allow (or Deny) Rule, move desired conditions from the
Available Conditions column into the Selected Conditions column.
8. Click Apply and then close the Confirmation window.
9. Find (or Add) TokenServiceRP Resources in the Application Domain: See
"Managing TokenServiceRP Type Resources".
45.7 Managing TokenServiceRP Type Resources
A Token Issuance Policy defines the rules under which a token can be issued for a
resource (Relying Party Partner) based on the client's identity, with the client either
being a Requester Partner or an end user.
When issuing a token, Security Token Service will determine for which Relying Party
that token is created, and it will then evaluate if the client is authorized to request the
token for that Relying Party.
Managing TokenServiceRP Type Resources
Managing Templates, Endpoints, and Policies 45-31
The resource(s) in a policy can be:
■A TokenServiceRP type resource represents resources for, and is based on, the
Token Service Relying Party (required for Mobile and Social REST clients).
■The pre-existing UnknownRP resource which is needed when Security Token
Service is not able to map the Service URL referenced in the
AppliesTo
element of
the WS-Trust request to an Security Token Service Relying Party Partner entry.
■The pre-existing MissingRP resource which is needed when the
AppliesTo
element of the WS-Trust request is missing.
A resource of type TokenServiceRP, Figure 45–14, represents an Security Token Service
Relying Party Partner defined in the Security Token Service Partner Store.
Figure 45–14 Pre-defined Resource Type: TokenServiceRP
Resources of type TokenServiceRP are used in Token Issuance Policies, which are
evaluated when Security Token Service issues tokens at run time. This is a predefined
resource type, which cannot be deleted. However, additional operations can be
created, edited or deleted as needed. Predefined operations are shown with a lock
icon.
For more information, see:
■About Managing TokenServiceRP Type Resources in Access Manager
■Managing TokenServiceRP Type Resources in Application Domains
Note: To issue a token, a Token Issuance Policy must be created with
the resource involved in the operation and, possibly, with a condition.
At run time if the policy evaluation is successful, the token will be
issued.
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social" for details about Configuring Access Manager for Mobile
and Social Authentication Service
Note: Both the MissingRP and UnknownRP are defined in the IAM
Suite Application Domain.
Managing TokenServiceRP Type Resources
45-32 Administrator's Guide for Oracle Access Management
45.7.1 About Managing TokenServiceRP Type Resources in Access Manager
Use the Search controls for the Application Domain to locate resources of a specific
type within the domain. Figure 45–15 shows the search controls for the IAM Suite
resources. Resource Type TokenServiceRP is the search criteria. The Search Results
table lists all resources of this type within the Application Domain.
Figure 45–15 Search: Resource Type TokenServiceRP in Application Domain
The TokenServiceRP resources in this domain include those provided out of the box,
and described earlier:
■UnknownRP resource
■MissingRP resource
45.7.2 Managing TokenServiceRP Type Resources in Application Domains
Users with valid Administrator credentials can use the following procedure to add
TokenServiceRP resources to an Application Domain.
To manage TokenServiceRP Resources
1. Locate the desired Application Domain as described in "Searching for an Existing
Application Domain" on page 25-12.
2. Add TokenServiceRP Resource to the Application Domain:
a. Click the New Resource button on the Application Domain Search page.
b. Specify the Resource Type as TokenServiceRP.
c. Enter a Resource URL that is the Relying Party ID for whom the token
issuance policy will be defined.
Note:
■If
AppliesTo
is present in the RST but the requester could not be
mapped, use the
TokenServiceRP:UnknownRP
resource.
■If
AppliesTo
is not present, use
TokenServiceRP:MissingRP
,
otherwise select the appropriate resource.
See Also: "About Managing TokenServiceRP Type Resources in
Access Manager"
Making Custom Classes Available
Managing Templates, Endpoints, and Policies 45-33
d. Click the Apply button at the top of the page to submit this and dismiss the
confirmation window.
e. See Also: "Defining Resources in an Application Domain" on page 25-27.
3. Find TokenServiceRP Resources:
a. In the desired Application Domain, open the Resources tab to display the
Search controls.
b. From the Resource Type, choose TokenServiceRP, and click Search.
c. Review the Search Results table and click a name to open the Resource
Definition.
45.8 Making Custom Classes Available
When Security Token Service does not support the token that you want to validate or
issue out-of-the-box, a developer can write custom validation and issuance module
classes. This section describes how to make custom classes available using the console.
The information here can be applied when you have:
■WS-Security User Name Token
■WS-Trust Custom Token
■Issuing Custom Token
This section provides the following topics:
■About Making Classes Available
■About Narrowing a Search for Custom Tokens
■Managing Custom Tokens
45.8.1 About Making Classes Available
After writing the custom token validation and/or issuance classes, you must add
Custom Token Configuration to Security Token Service to indicate when and how
these classes should be used.
On the New Custom Token page only the Token Type Name is required (identified
with an asterisk, *), as shown in Figure 45–16. Not all elements apply to all custom
tokens. However, if you submit information that is incomplete, a dialog box appears to
identify what is missing.
Note: You can also write a script that includes WebLogic Scripting
Tool commands for any operation that you can accomplish through
the console. For more information, see Oracle Fusion Middleware
WebLogic Scripting Tool Command Reference.
Making Custom Classes Available
45-34 Administrator's Guide for Oracle Access Management
Figure 45–16 New Custom Token Page
For the custom token, you must decide on the XML Element Name, XML Element
Namespace, Binary Security Token Type, and so on. Table 45–14 describes the elements
on a Custom Token page based on the examples in this chapter.
Table 45–14 New Custom Token Elements
Element Description
Token Type Name The unique name you choose for this custom token. For example:
email_token
Note: After you save a new custom token configuration, you cannot
edit this name.
Default Token URI The URI for this custom token. This URI can then be used in the RST to
request that a custom token of this type should be issued. For the
example in this chapter, the value would be:
oracle.security.fed.sts.customtoken.email
XML Element Name The name you decide on, which will be associated with the Token Type
Name. For example:
email
If you specify
email
as the XML Element Name, each time the element
name,
email
, appears in an incoming token it will be associated with
the Token Type Name (in this case
email_token
).
Note: Minimally, you need either an XML Element Name or Binary
Security Token Type.
Validation Classname The name of the custom token validation class that you made available
to Security Token Service. For example:
oracle.security.fed.sts.tpe.providers.email.EmailTokenValidat
orModuleImpl
Note: Minimally, you need either an issuance class name or validation
class name, depending on whether you want to issue or validate a
custom token.
Making Custom Classes Available
Managing Templates, Endpoints, and Policies 45-35
Task overview: Adding custom tokens for custom classes
1. Create a JAR file containing only your custom
TokenIssuerModule or
TokenValidatorModule
classes (or both). No XML metadata or manifest is needed.
2. Review information in Table 45–14.
3. Add the JAR to the OAM Server hosting Security Token Service and create a new
custom token, as described in Section 45.8.3, "Managing Custom Tokens".
45.8.2 About Narrowing a Search for Custom Tokens
Figure 45–17 illustrates the Custom Tokens Search controls and Results table. These
appear when you double-click the Custom Tokens node in the navigation tree. By
default, all currently defined custom tokens are listed when the Search Results table is
displayed.
XML Element Namespace The namespace of the custom token element name. For example:
http://email.example.com
Issuance Classname The name of the custom token issuance class that you made available
to Security Token Service. For example:
oracle.security.fed.sts.tpe.providers.email.EmailTokenIssuerM
oduleImpl
Note: Minimally, you need either an Issuance classname or Validation
classname, depending on whether you want to issue or validate a
custom token.
Binary Security Token Type Enables the class to validate a custom token sent in as a
BinarySecurityToken.
The ValueType of the BinarySecurityToken for this custom token. If
Security Token Service receives a Binary Security Token with this
ValueType, it will be forwarded to this custom token's Validation class
for validation.
Validation Attributes This section enables you to add (or remove) validation attributes. The
table displays existing validation attributes, if any. For this example:
■Attribute Name:
testsetting
■Attribute Type:
String
Note: You will add a value to the attribute when creating a Token
Validation Template.
Issuance Attributes This section enables you to add (or remove) issuance attributes. The
table displays the following information for existing issuance
attributes.
■Attribute Name:
testsetting
■Attribute Type:
String
Note: You will add a value to the attribute when creating a Token
Issuance Template.
Save Click this button on the New Custom Tokens page to save your
configuration information.
Cancel Click this button to dismiss your configuration details.
Apply Click this button to submit your changes.
Revert Click this button to dismiss your changes.
Table 45–14 (Cont.) New Custom Token Elements
Element Description
Making Custom Classes Available
45-36 Administrator's Guide for Oracle Access Management
Figure 45–17 Custom Tokens Search Page and Controls
Table 45–15 describes the Custom Tokens Search elements and controls. No wild cards
(*) are allowed in Custom Token searches.
Table 45–15 Custom Tokens Search Elements and Controls
Element Description
Default Token URI The URI that was defined for the custom token. You can enter the
entire URI or only part of it. For instance, if you enter "ai" the Search
Results table will display all custom tokens defined with a token URI
that includes the letters "ai".
Note: Wild cards are not allowed in Custom Token searches.
Search Initiates the Search function using criteria provided in the form.
Reset Resets the Search form with defaults only.
Search Results Provides the results of your search based on your choices in the View
menu.
Actions menu Provides the following functions that can be performed on a selection
in the results table:
Note: Actions menu functions mirror command buttons above the
results table. For example:
■New Custom Token: Click the New Custom Token button at the
top of the Search page, or select New Custom Token from the
menu, or click the + button above the table.
■Edit: Double-click a name in the Token Type Name column of the
Search Results table, or select Edit from the Actions menu, or click
the Edit (pencil icon) command button above the Results Table.
■Create Like: Select the desired row in the table and either select
Create Like from the Actions menu, or click the Create Like
command button above the table
■Remove: Select the desired row in the table and either select Delete
from the Actions menu, or click the Delete (X) command button
above the table.
View menu Provides functions you can use to display various information in the
results table:
Up-Down Arrows Controls affecting the ordering of items listed in the results table:
■Ascending
■Descending
Making Custom Classes Available
Managing Templates, Endpoints, and Policies 45-37
45.8.3 Managing Custom Tokens
Users with valid Administrator credentials can use the procedure in this section to
manage custom tokens for custom Token Module classes.
The following procedure includes steps to add, edit, and delete custom tokens or
attributes of a custom token. Skip any steps that you do not need.
Prerequisites
Refer to the developer creating the custom tokens and the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management for details about:
Writing a TokenValidatorModule Class
Writing a TokenIssuanceModule Class
To make custom classes available
1. Create and add the JAR containing your Issuance and Validation classes to the
OAM Server hosting Security Token Service using one of these methods:
■Add the custom token jar and the sts-common.jar that is available in
$DOMAIN_HOME/config/fmwconfig/mbeans/oam to the Managed Server
classpath by editing the startup script.
■Add the custom token jar and the sts-common.jar that is available in
$DOMAIN_HOME/config/fmwconfig/mbeans/oam to the $DOMAIN_
HOME/lib directory to automatically add these jars to the Managed Server
classpath.
■Restart the OAM Server.
2. New Custom Token:
a. In the Oracle Access Management Console, click Federation at the top of the
window.
b. Select Create Custom Token from the Create (+) drop-down menu in the
Security Token Service section.
c. Fill in the New Custom Token page with details for your custom classes
(Table 45–14).
d. Click Save and dismiss the confirmation window (or click Cancel to dismiss
the page without submitting it).
e. Close the page (or edit as described in Step 4).
f. Proceed to Step 4, if needed, or to "Managing a Custom Security Token Service
Configuration" on page 45-38.
3. Find Custom Tokens: In the Federation console, select Custom Tokens from the
View menu in the Security Token Service section.
a. Find All: Click the Search button and view the results table with all custom
tokens listed.
b. Narrow the Search: Enter some or all characters in the desired Default Token
URI, click the Search Button, and review the results table.
See Also:
■"Making Custom Classes Available" on page 45-33
■"About Narrowing a Search for Custom Tokens" on page 45-35
Managing a Custom Security Token Service Configuration
45-38 Administrator's Guide for Oracle Access Management
c. Reset the Search Form: Click the Reset button.
4. Edit Custom Token Configuration: Start with the saved page you just created.
Alternatively: Use Step 3 to find the desired Custom Token, then double-click the
name in the Search Results table to open the page.
a. In the named Custom Token page, click the appropriate field and edit as
needed.
b. Add Attributes: Click the Add (+) icon for the Attributes table, enter the
Attribute Name and an Attribute Type (Table 45–14).
c. Remove Attributes: From the Attributes table, click the row containing the
attribute to remove, click the Delete (X) icon for the table, and dismiss the
Confirmation window.
d. Apply Changes: Click the Apply button at the top of the page to submit
changes.
5. Remove a Custom Token:
a. Click the desired name in the Search Results table to select the item to remove.
b. From the Actions menu, click Delete (or click the Delete (X) command button
above the table.
c. Click the Delete button in the Confirmation window (or click No to cancel the
operation).
45.9 Managing a Custom Security Token Service Configuration
This tasks consists of the following procedures:
■Creating the Validation Template
■Creating the Issuance Template for a Custom Token
■Adding the Custom Token to a Requester Profile
■Adding the Custom Token to the Relying Party Profile
■Mapping the Token to a Requestor
■Creating an /wssuser EndPoint
45.9.1 Creating the Validation Template
Users with valid Oracle Access Management Administrator credentials can perform
the following task to create a Validation Template with a Token Protocol of Webservice
Trust to map the token to the requester.
The template in this example can be used for the module classes described earlier in
this chapter. Full implementation details are shown in the following figures. As you
review these, notice how specifications for this template reference the module class
code:
■Figure 45–18, "General Details: email-wstrust-valid-temp"
■Figure 45–19, "Token Mapping: email-wstrust-valid-temp"
Managing a Custom Security Token Service Configuration
Managing Templates, Endpoints, and Policies 45-39
Figure 45–18 General Details: email-wstrust-valid-temp
Figure 45–19 Token Mapping: email-wstrust-valid-temp
To create the validation template for the custom module classes
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. Select Create Token Validation Template from the Create (+) drop-down menu in
the Security Token Service section.
3. General: Set the following for use with the custom token.
Validation Template Name: email-wstrust-valid-temp
Token Protocol: Webservice Trust
Token Type: email
Managing a Custom Security Token Service Configuration
45-40 Administrator's Guide for Oracle Access Management
Default Partner Profile: requester-profile
Custom Validation Attributes: test: hello
4. Token Mapping: Set the following for use with the custom token in this chapter.
Check the box beside Map Token To User (to enable it).
Check the box beside Enable Simple User Mapping and enter:
User Token Attribute: STS_SUBJECT_ID
Datastore Attribute: mail
5. Click Save and dismiss the confirmation window.
6. Proceed to "Creating the Issuance Template for a Custom Token".
45.9.2 Creating the Issuance Template for a Custom Token
This is a server side configuration. Users with valid Oracle Access Management
Administrator credentials can perform the following task to create a Token Issuance
Template.
Each Token Issuance Template indicates how to construct a token, and which signing
or encryption to use when constructing a token. Each Token Issuance Template also
defines the attributes to be sent as part of the outbound token for mapping, and
filtering data. However, Issuance Templates do not list mapping or filtering rules,
which are defined in the Relying Party Partner Profile.
The template in this example can be used for the email custom token described earlier
in this chapter. Implementation details are shown in the following figures, and
described in the accompanying procedure. As you review these, notice how
specifications for this template reference the module class code:
■Figure 45–20, "General Details: email-issuance-temp"
■Figure 45–21, "Issuance Properties: email-issuance-temp"
Figure 45–20 General Details: email-issuance-temp
When you have a custom token type deployed, the Issuance Properties are tailored to
accommodate the custom token. For instance, the custom email token type was chosen
for the issuance template show in Figure 45–21.
Managing a Custom Security Token Service Configuration
Managing Templates, Endpoints, and Policies 45-41
Figure 45–21 Issuance Properties: email-issuance-temp
This procedure produces a companion Issuance Template for the custom module
classes in this chapter. For the example:
■Ignore the Token Encryption Algorithm, which is not used for the custom token
type: email.
■Fill in a value for the Custom Token Attribute, which is populated from the
custom token code.
To create the Issuance Template for the custom module classes
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. Select Token Issuance Templates from the View menu in the Security Token
Service section.
3. New Token Issuance Template:
a. Click the New Issuance Template button in the upper-right corner (or click
the Add (+) command button above the Search Results table).
b. General: Set the following for use with the custom token in this chapter.
Issuance Template Name: email-issuance-temp
Token Type: email
c. Click Save and dismiss the confirmation window (or click Cancel without
saving).
d. Issuance Properties: Set the following for use with the custom token in this
chapter.
Custom Token Attribute Value: world
e. Click Apply and dismiss the confirmation window (or click Revert without
saving it).
f. Close the definition (or edit it as described in Step 4).
4. Edit a Template: Find the desired template, edit details, and click Apply.
See Also: Oracle Fusion Middleware Administrator's Guide for Oracle
Access Management
Managing a Custom Security Token Service Configuration
45-42 Administrator's Guide for Oracle Access Management
45.9.3 Adding the Custom Token to a Requester Profile
You can either edit an existing requester profile to add your custom token to the Token
Type Configuration table, or create a new requester profile to use with the custom
token. Either way, configure:
■Token Type: email (your custom token)
■Validation Template: email-wstrust-valid-temp
Prerequisites
Your Custom Token and Validation Template must be defined.
To create or edit a requester profile for the custom token
1. In the Oracle Access Management Console Launch Pad, click Federation at the top
of the window.
2. Select Partner Profiles from the View menu in the Security Token Service section.
3. Select the Requester Profiles tab.
4. Existing Profile:
a. In the Search Results table of the Requester Profiles page, click the name of the
desired profiles.
b. Token and Attributes: Fill in the following details for the custom token in this
chapter and then click the Save button at the top of the page.
Token type:
email
Validation Template:
email-wstrust-valid-temp
c. Click Save, dismiss the confirmation window, and close the page (or click
Cancel to dismiss the page without submitting it).
d. Proceed to "Adding the Custom Token to a Requester Profile".
5. New Profile: Click the New Requester Profile button to display the New Partner
Profile page where you enter details:
a. General: Fill in the following details for the custom token in this chapter and
then click the Next button at the top of the page.
Profile ID:
unique_requesterprofile_name
Default Relying Party Profile:
unique_relyingparty_name
b. Add Token Type Configuration: Fill in the following details for the custom
token in this chapter and then click the Save button at the top of the page.
Token type:
email
Validation Template:
email-wstrust-valid-temp
c. Proceed to "Adding the Custom Token to a Requester Profile".
45.9.4 Adding the Custom Token to the Relying Party Profile
You can either edit an existing Relying Party profile, or create a new one to issue the
custom token by default, and refer to the Issuance Template and related information.
Either way, configure:
■Default token to issue: email (your custom token)
■Issuance Template:
email-issuance-temp
Managing a Custom Security Token Service Configuration
Managing Templates, Endpoints, and Policies 45-43
Prerequisites
Your Custom Token and Issuance Template must be defined.
To edit the requester profile for the custom module classes
1. In the Oracle Access Management Console Launch Pad, click Federation at the top
of the window.
2. Select Partner Profiles from the View menu in the Security Token Service section.
3. Select the Relying Party Profiles tab.
4. Existing Profile:
a. In the Search Results table of the Relying Party Profiles page, click the name of
the desired profile.
b. Click the Token and Attributes tab.
c. Token Type Configuration: Click the Add (+) button above the Token Type
Configuration table and enter the following details:
Token type:
email
Issuance Template:
email-issuance-temp
d. Attributes: Click the Add (+) button above the Attributes table and define the
following:
Attribute name: mail
Store Type:
Userstore
Include in Token:
(check to enable)
Encryption (leave blank)
Value (leave blank)
e. Click Apply, dismiss the confirmation window, and close the page (or click
Cancel to dismiss the page without submitting it).
5. New Profile: Click the New Relying Party Profile button to display the New
Partner Profile page where you enter details:
a. General: Fill in the following details for the custom token in this chapter and
then click the Next button at the top of the page.
Profile ID:
unique_relyingparty-name
Default Token:
email
b. Click the Token and Attributes tab and perform Steps 2c and 2d, then click
Apply.
45.9.5 Mapping the Token to a Requestor
If you don't have a Username Validation Template (username-wss-valid-template), use
the Oracle Access Management Console to create one to map the token to the
requester.
Validation Template Name: username-wss-valid-template
Token Type: Username
Proceed to "Creating an /wssuser EndPoint"
Managing a Custom Security Token Service Configuration
45-44 Administrator's Guide for Oracle Access Management
45.9.6 Creating an /wssuser EndPoint
Prerequisites
Mapping the Token to a Requestor
To create an endpoint
1. In the Oracle Access Management Console Launch Pad, click Federation at the top
of the window.
2. Select Endpoints from the View drop-down menu in the Security Token Service
section.
3. New Endpoint:
a. Click the Add (+) button above the table (or choose New Endpoint from the
Actions menu).
b. Enter the new Endpoint URI: /wssuser
c. Choose the Oracle WSM policy: sts/wss_username_service_policy
d. Choose the Validation Template: username-wss-validation-template.
e. Click Apply to submit the definition and dismiss the confirmation window (or
click Revert to dismiss the page without submitting it).
f. Close the page.
46
Managing Token Service Partners and Partner Profiles 46-1
46
Managing Token Service Partners and Partner
Profiles
This chapter provides the following topics describing management of Token Service
Partners and Partner Profiles:
■Prerequisites
■Introduction Token Service Partners and Partner Profiles
■Managing Token Service Partners
■Managing Token Service Partner Profiles
46.1 Prerequisites
Chapter 41, "Introducing the Oracle Access Management Security Token Service"
Chapter 42, "Security Token Service Implementation Scenarios"
Any task you can perform using the Oracle Access Management Console can also be
performed using the
46.2 Introduction Token Service Partners and Partner Profiles
This section provides the following topics:
■About Token Service Partners
■About Partner Profiles
■About Partner Entries
46.2.1 About Token Service Partners
A Token Service partner represents a partner trusted by the Security Token Service.
Table 46–1 describes the partner types.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference
Table 46–1 Security Token Service Partners
Partner Type Description
Requester Represents a Web Service Client interacting directly with Security Token
Service in order to issue or validate tokens
Relying Party References a Web Service Provider that will be the recipient of tokens issued
by the Security Token Service server
Introduction Token Service Partners and Partner Profiles
46-2 Administrator's Guide for Oracle Access Management
The Security Token Service is capable of interacting with client types described in
Table 46–2.
46.2.2 About Partner Profiles
A Partner Profile contains configuration properties that are common to a set of
partners, and each partner entry is associated to a Partner Profile. Similar to the
partners, there are three types of partner profiles: Requester, and Issuing Authority
Partner Profiles.
■Requester Profile
■Relying Party Profile
■Issuing Authority Partner Profile
46.2.2.1 About Partner Entries
A partner entry contains the information in Table 46–3:
46.2.2.2 About Partner Profile Data
A partner profile entry contains the information in Table 46–4, depending on the type
of profile.
Issuing Authority Represents an Assertion issuer. When validating an Assertion, its issuer must
be a known Issuing Authority Partner entry in Security Token Service
Table 46–2 Security Token Service Clients
Client Type Description
Web Service Client Modules defined as requester partners in Security Token Service
(typically SOAP clients).
End users End users are not defined as requester partners, but possibly present in
the User Identity Store.
Table 46–3 Security Token Service Partner Entry
Partner Entry Description
Certificates Signing and Encryption Certificates
Reference Reference to a Partner Profile
Requester only When the partner is a Requester, the partner entry also contains
Username Token credentials, and Identification strings used to map
incoming data to a requester.
Table 46–4 Security Token Service Partner Profile Data
Client Type Description
Requester ■Claims Mappings
■WS-Trust Validation Templates used to validate tokens present in
the OnBehalfOf element
Relying Party ■Attributes to be sent to RP
■Issuance Templates to be used
Issuing Authority ■Attribute Name/Value Mapping settings
■Specific Mapping Actions Rules used to map an incoming token
to a partner/user
Table 46–1 (Cont.) Security Token Service Partners
Partner Type Description
Managing Token Service Partners
Managing Token Service Partners and Partner Profiles 46-3
46.3 Managing Token Service Partners
This section provides the following topics.
■About Managing Token Service Partners
■Managing a Token Service Partner
■Refining Partner Searches
46.3.1 About Managing Token Service Partners
When you choose to create a new partner, a fresh page appears for the specific Partner
Type you selected. Figure 46–1 shows the New Requester partner page in the Oracle
Access Management Console, which includes all Partner elements.
Figure 46–1 New Requester Partner Page
While most elements are common to all partners (name, description, and whether this
partner is trusted), certain elements depend upon the specific partner type, as
described in Table 46–5.
Table 46–5 Partner Elements for Partner Types
Partner Type Description
Requester partners Can specify an encryption certificate and a signing certificate, as well
as Token Authentication and Identity Attributes.
Managing Token Service Partners
46-4 Administrator's Guide for Oracle Access Management
Figure 46–2 New Relying Party Partners Page
Table 46–6 describes elements for Security Token Service partners. Unless explicitly
stated otherwise, all elements apply to every partner type.
Relying Party partners Can specify only an encryption certificate and Resource URLs.
See Figure 46–2
Issuing Authority partners Can specify only a signing certificate.
Table 46–6 Elements for Security Token Service Partners
Element Description
Partner Name Enter a name for this partner.
Issuer ID
Issuing Authority Only
Unique identifier used in SAML Assertion Issuer field referencing this
Issuing Authority.
Partner Type Uneditable description, depending upon the type of partner you are
creating or editing:
■Requester
■Relying Party
■Issuing Authority
Partner Profile Choose from the profiles listed to define your chosen partner.
Description Optional.
Trusted Check this box to indicate whether or not the partner is trusted. If not
checked, the Security Token Service server will report an error when a
request involves such an entry.
Load Certificate Browse for and upload the requested certificates, which depend on
partner type:
■Encryption and signing certificates
■Encryption certificate
■Signing certificate
Table 46–5 (Cont.) Partner Elements for Partner Types
Partner Type Description
Managing Token Service Partners
Managing Token Service Partners and Partner Profiles 46-5
46.3.2 Managing a Token Service Partner
Users with valid Administrator credentials can use the following procedure to create,
find, edit, or delete a token service partner using Oracle Access Management Console.
Prerequisites
A partner profile must be defined for the type of partner you will create.
To manage a token service partner
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Partners from the View menu in the Security
Token Service section.
Username Token Authentication
Requester only
Values can be entered for the following for Username Token
Authentication:
■Username
■Password
■Confirm Password
New Requester Partner Identification Attributes can be defined in the
STS Settings section and will appear in the requester partner Identity
Attributes table.
Note: the username and password data will be used to validate the
credentials of a username token. It is also possible to only enter a
username and no password, when the data will be used only to map
an incoming token to this requester partner using the username.
Identity Attributes
Requester only
At runtime, Security Token Service will use the data defined in the
section to map an incoming request to a requester partner entry, using:
■The token data or binding data such as the SSL Client
Certificate's Subject DN if present, or HTTP Basic Authentication
username.
■The identity attributes present in each requester partner entry.
New mappings can be added in the Relying Party Partner section as
follows: http://relying.party.test.com/testing.service. At runtime, the
Security Token Service server will use those URLs to map the
AppliesTo service location contained in a WS-Trust request to a
Relying Party Partner.
Resource URL
Relying Party only
Enter the resource URL in the resource pattern column of the table,
and enter a description beside it. For instance:
Pattern:
http://relying.party.test.com/testing/service
The resource URL listed in the table will be used when mapping the
AppliesTo location element from the WS-Trust request to this Relying
Party Partner.
The AppliesTo location value will be mapped to this Relying Party
Partner:
■A Resource URL matches exactly the AppliesTo location value.
For example, the AppliesTo location is
http://relying.party.test.com/testing/service and the Resource URL
is also http://relying.party.test.com/testing/service).
■Or, a Resource URL is the parent of the AppliesTo location value.
For example, the AppliesTo location is
http://relying.party.test.com/testing/service and the Resource URL
is http://relying.party.test.com/testing, or Resource URL is
http://relying.party.test.com/
Table 46–6 (Cont.) Elements for Security Token Service Partners
Element Description
Managing Token Service Partners
46-6 Administrator's Guide for Oracle Access Management
3. Select the desired partner type tab and proceed with following steps as needed.
■Requesters
■Relying Parties
■Issuing Authorities
4. New Partner:
a. Click the New [Partner Type] button to display a fresh page for your
definition.
b. Enter general information for the chosen partner type (Table 46–6).
c. Tru st ed : Click to select (or leave blank if this is not a trusted partner).
d. Certificates: Load any necessary certificates.
e. Relying Party: Enter Resource URLs, if needed.
f. Issuing Authority: Enter the Issuer ID of this Authority.
g. Requester: Enter Username Token credentials, if needed.
h. Click Save to submit (or click Cancel to dismiss the page) and then dismiss the
confirmation window.
5. Refine a Partner Search: "Refining Partner Searches"
a. Perform Steps 1 and 2.
b. Define your query and click the Search button.
c. In the Search Results table, click the name of partner to view, edit, or remove.
6. Edit a Partner:
a. In the Search Results table, click the name of partner to edit and click the Edit
button (or choose Edit from the Actions menu).
b. Make desired changes to partner information (Table 46–6).
c. Click Apply to submit the changes (or Revert to cancel changes) and then
dismiss the confirmation window.
7. Remove a Partner: Use the Search controls to refine and submit your query, as
needed.
a. In the Search Results table, highlight the row containing the partner to
remove.
b. Click the Delete (X) button (or choose Delete Selected from the Actions menu),
then dismiss the confirmation window.
46.3.3 Refining Partner Searches
From the console Launch Pad, when you click Partners, all Partner types can be
viewed from tabs. When you choose a specific Partner, relevant Search controls, and
the Search Results table, become available. Figure 46–3 illustrates a Requester Partner,
where only the results differ from that of other Partner Types.
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-7
Figure 46–3 Partner Search Controls
From the Search page you can simply select a name in the Search Results table, or use
the controls to refine your search to locate a specific Partner or Partners with specific
characteristics.
46.4 Managing Token Service Partner Profiles
This section provides information about Token Service Partner Profiles.
■About Managing Partner Profiles
■Managing a Token Service Partner Profile
■Refining a Profile Search
46.4.1 About Managing Partner Profiles
Figure 46–4 shows a completed Requester Profile page, with both a General tab and
Token and Attributes tab.
Managing Token Service Partner Profiles
46-8 Administrator's Guide for Oracle Access Management
Figure 46–4 Requester Profile: General
Table 46–7 describes the General elements for all profile types.
Table 46–7 Profile: General
Element Description
Profile ID A unique identifier for this profile
Description Optional.
Profile Type Type of profile, which cannot be edited: Requester, Relying
Party or Issuing Authority.
Default Relying Party Profile
Requester Partner Profile Only
References the Relying Partner Profile to use, if the WS-Trust
request does not reference the Relying Party (for example, the
AppliesTo element is missing), or if the AppliesTo element
could not be mapped to a known Relying Party Partner
Profile.
Choose a Relying Party profile to use as the default and enable
or disable the following characteristics as needed:
■Return error for missing claims.
Indicates whether or not Security Token Service will
return an error if the issued token does not contain claims
that were requested by the client.
Since the Relying Party Partner Profile defines the list of
attributes/claims that can be included in the issued token,
it is possible that some claims requested by the client
cannot be returned.
■Allow unmapped claims.
Claims listed in a WS-Trust request are specified in a
dialect that will be translated to map to local attributes
using the Token and Attributes section.
This flag indicates whether or not claims that cannot be
translated should be referenced as is. This allows to
control which claims can be requested by the client.
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-9
Requester Profile: Token and Attributes
Figure 46–5 illustrates the Token and Attributes tab and accompanying tables for the
Requester profile. The Token Type Configuration section indicates which WS-Trust
Validation Template to use to validate tokens contained in the OnBelhalfOf element of
the WS-Trust request, based on the token type. This section defines mappings between
WS-Trust claims requested by the client and local attribute names
Figure 46–5 Requester Profile: Token and Attributes
Table 46–8 describes Requester Profile Token and Attributes elements and controls.
Default Token to Issue
Relying Party Only
This table indicates which Issuance Template to use to issue a
token for Relying Parties linked to this profile.
Choose a token type as the default for this profile:
■SAML 1.1
■SAML 2.0
■Username
■Custom
Check the box beside Download Policy to associate a policy
with the token. When checked, Security Token Service will
download at runtime the WS-Security policy of the Relying
Party referenced by the AppliesTo element in the RST. If
present, Security Token Service will use that URL to download
the policy, and then determine the type of token to return
based on the information located in the policy.
Table 46–8 Requester Profile: Token and Attributes
Element Description
Token Type Configuration Click the + above the table to display a dialog box and then
make one selection from each of the following drop down lists:
■Token Type list provides all supported (and custom) token
types deployed.
■Validation Template list contains all currently defined
WS-Trust validation templates.
Table 46–7 (Cont.) Profile: General
Element Description
Managing Token Service Partner Profiles
46-10 Administrator's Guide for Oracle Access Management
Relying Party Profile: Token and Attributes
Figure 46–6 illustrates the Token and Attributes defined for a Relying Party Profile.
This section allows the Administrator to define which Issuance Template should be
used to issue a token for a Relying Party associated with this profile.
Also, it lists the attributes that might be included in an issued token, by their names,
the source of those attributes, and whether or not the attributes should be included in
the issued token only if requested by the client or always.
On this page, Relying Party Profiles require an Issuance Template in addition to the
token type. Also, the attribute types differ from other profiles.
Figure 46–6 Relying Party Profile Token and Attributes
Table 46–9 describes the elements needed for the Relying Party Profile.
Attribute Name Mapping This table defines how Security Token Service maps a claim,
represented by its name and optional Format/Namespace, to a
local attribute.
Security Token Service supports the Infocard Claims dialect. To
translate Infocard claims to local attributes, a mapping will
need to be defined where the Incoming Attribute will contain
the claim name and the Local Attribute will contain the local
name (The Format/Namespace column will be empty).
For example, one mapping could be:
■Incoming Attribute: surname
■Local Attribute: sn
Another mapping could be:
■Incoming Attribute: givenname
■Local Attribute: givenname
Another mapping could be:
■Incoming Attribute: emailaddress
■Local Attribute: mail
Table 46–8 (Cont.) Requester Profile: Token and Attributes
Element Description
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-11
Relying Party Profile Attributes
When defining an attribute, you can indicate:
■The attribute source: User Store (LDAP), Incoming Token Data or static value.
■Whether or not to include the attribute in the token only if requested by the client
or in all tokens.
■Whether or not to encrypt the attribute (only SAML 2.0; requires the Relying Party
Encryption Certificate).
■The value of the attribute if this is a static attribute.
Example: To include the mail attribute retrieved from LDAP in all outgoing tokens:
■Attribute Name: mail
■Store Type: User Store
■Include in Token: checked
■Encrypt: unchecked
■Value: empty
Example: To include the username element of an incoming Username Token in all
outgoing tokens
■Attribute Name: STS_SUBJECT_ID
Table 46–9 Relying Party Profile Requirements
Element Descrip[tion
Token Type Configuration Click the + above the table to display a dialog box and then
make one selection from each drop down list:
■Token Type list provides all supported (and custom) token
types deployed.
■Issuance Template list contains all currently defined
Issuance Templates.
Attributes The attributes that might be included in an issued token:
■Attribute Name: Indicates the name of the attribute.
■Store Type: Indicates the source of the attribute:
Userstore: the default User Identity Store where the LDAP
user record will be used to retrieve the attribute value.
Incoming Token: the attribute will reference an element of
the incoming token.
Static: the value will be specified in the Value field.
■Include in Token: Indicates whether or not the attribute
should always be included in the issued token. If
unchecked, the attribute will only be included if the client
requested this attribute.
■Encrypt: Indicates whether or not the attribute should be
encrypted.
Note: only supported for SAML 2.0. Also, the Encryption
Certificate must be set in the Relying Party Partner entry,
or it must be present in the WS-Trust request.
■Value: Contains the value to be used if the Store Type is
static value.
See Also: "Relying Party Profile Attributes".
Managing Token Service Partner Profiles
46-12 Administrator's Guide for Oracle Access Management
■Store Type: Incoming Token
■Include in Token: checked
■Encrypt: unchecked
■Value: empty
Example: To include a static attribute in all outgoing tokens:
■Attribute Name: rp-version
■Store Type: Static
■Include in Token: checked
■Encrypt: unchecked
■Value: 2.0
The following attributes are available from the incoming token data. The SAML
attributes referenced by their names are also available as incoming token data:
STS_SUBJECT_ID
Contains the subject identifier (username for Username token, NameID Value for
SAML assertions, Subject DN for X.509 certificates)
STS_NAMEID_FORMAT
Contains the SAML NameID Format.
STS_NAMEID_QUALIFIER
Contains the SAML NameID Format.
STS_SPNAME_QUALIFIER
Contains the SAML NameID Qualifier.
STS_SP_PROVIDED_ID
Contains the SAML NameID SP Qualifier
STS_SESSION_INDEX
Contains the session index.
STS_AUTHENTICATION_INSTANT
Contains the authentication instant (current after Username token credentials
validation, from the authentication statement for SAML Assertions, current for X.509
validation, current for Kerberos Validation, authentication instant for OAM Session
Propagation tokens).
STS_AUTHENTICATION_TIMEOUT
Contains the session expiration time if set (applies to SAML assertions and OAM
Session Propagation tokens if present).
STS_X509_CN
Contains the CN component of the X.509 Certificate's Subject DN
STS_X509_OU
Contains the OU component of the X.509 Certificate's Subject DN.
STS_X509_O
Contains the O component of the X.509 Certificate's Subject DN.
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-13
STS_X509_L
Contains the L component of the X.509 Certificate's Subject DN.
STS_X509_ST
Contains the ST component of the X.509 Certificate's Subject DN.
STS_X509_C
Contains the C component of the X.509 Certificate's Subject DN.
STS_X509_DC
Contains the DC component of the X.509 Certificate's Subject DN.
STS_X509_*
Contains the component identified by * of the X.509 Certificate's Subject DN.
STS_X509_VERSION
Contains the version attribute of the X.509 Certificate.
STS_X509_ISSUER_X500_PRINCIPAL_NAME
Contains the issuer DN of the X.509 Certificate.
STS_X509_NOT_AFTER
Contains the not after attribute of the X.509 Certificate.
STS_X509_NOT_BEFORE
Contains the not before attribute of the X.509 Certificate.
STS_X509_SUBJECT_X500_PRINCIPAL_NAME
Contains the subject DN of the X.509 Certificate.
STS_X509_SUBJECT_ALTERNATIVE_NAMES
Contains the subject alternative name extension value of the X.509 Certificate.
STS_X509_SERIAL_NUMBER
Contains the serial number of the X.509 Certificate.
STS_OAM_LAST_ACCESS_TIME
Contains the last access time of the OAM Session Propagation Token.
STS_OAM_LAST_UPDATE_TIME
Contains the last update time of the OAM Session Propagation Token.
STS_OAM_CREATION_TIME
Contains the creation time of the OAM Session Propagation Token.
STS_KERBEROS_PRINCIPAL_SHORT
Contains the Principal Short value of the Kerberos Token.
STS_KERBEROS_PRINCIPAL_FULL
Contains the Principal Full value of the Kerberos Token.
STS_KERBEROS_PRINCIPAL_NODOMAIN
Contains the Principal No Domain value of the Kerberos Token.
STS_SAML_ASSERTION_ID
Contains the AssertionID of the SAML Assertion.
Managing Token Service Partner Profiles
46-14 Administrator's Guide for Oracle Access Management
STS_SAML_SUBJECT_DNS
Contains the Subject DNS attribute of the SAML Assertion.
STS_SAML_SUBJECT_IP_ADDRESS
Contains the Subject IP Address attribute of the SAML Assertion.
STS_SAML_ASSERTION_ISSUER
Contains the Issuer of the SAML Assertion.
STS_SAML_AUTHN_INSTANT
Contains the authentication instance of the SAML Assertion.
STS_SAML_AUTHN_METHOD
Contains the authentication method of the SAML Assertion.
Issuing Authority Profile: Token and Attributes
The Issuing Authority Partner Profile defines settings that can be common to different
Issuing Authority Partners.
The Token and Attributes section, as shown in Figure 46–7, allows the Administrator
to define mapping rules that will be used to translate the name and value of attributes
to local names and values.
Figure 46–7 Token and Attributes: Issuing Authority
Table 46–10 describes the Token and Attributes elements for Issuing Authority. It is
possible to define attribute mapping rules that will be applied to the attributes
included in the Assertion, when extracting them from the token. There are two
different sets of rules:
■Attribute name mapping where the name of a SAML Attribute can be translated to
a local name (for example, firstname could be translated to givenname).
■Attribute value mapping where the value of a SAML Attribute can be translated to
a local value (for example, President to CEO).
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-15
Issuing Authority Profile: Token Mapping
Using the Token Mapping tab, shown in Figure 46–8, Administrators can override the
Mapping Rules defined in a SAML Validation Template with the ones defined in an
Issuing Authority Partner Profile. This way, Security Token Service can map SAML
Assertions based on rules specific to a set of Assertion Issuers.Table 46–10 describes
the Token Mapping elements for the Issuing Authority.
Table 46–10 Token and Attributes Elements: Issuing Authority
Element Description
Attribute Name Mapping Define an optional mapping between the name of a SAML
Attribute and the local name of an attribute.
The mapping is optional. If an attribute does not have a
mapping defined, then its SAML attribute name will be used.
■Incoming Attribute: Contains the external name of the
attribute as it will appear in the Assertion.
■Local Attribute: Contains the local name of the attribute.
■Format or Namespace: Contains an optional Format or
Namespace. If missing, the namespace value for mapping
purposes will be assumed to be
urn:oracle:security:fed:attrnamespace
for SAML 1.1
Assertions or the format value for mapping purposes will
be assumed to be
urn:oasis:names:tc:SAML:2.0:attrname-format:basic
for SAML 2.0 Assertions
Value Mapping Define an optional value mapping for a SAML attribute. This
will indicate how to translate an attribute value to a local
value, if needed.
Note: This attribute value mapping applies to an Attribute
Name mapping. In order to define an attribute mapping for an
attribute, it is required to first define an attribute name
mapping for that attribute.
■External Value: Contains the value of the SAML Attribute.
■Local Value: Contains the local value that will be set, if the
SAML attribute value matches the External
Attribute/Local Null fields.
■External Null: Represents a null SAML attribute value.
■Local Null: Indicates if the local value should be null, if
the SAML attribute value matches the External
Attribute/Local Null fields.
■Ignore Case: Indicates whether or not Security Token
Service should ignore case when comparing the attribute
value to the Local Attribute field.
Managing Token Service Partner Profiles
46-16 Administrator's Guide for Oracle Access Management
Figure 46–8 Issuing Authority Profile: Token Mapping Tab
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-17
Table 46–11 Issuing Authority Token Mapping Elements
Element Description
Override Token Mapping Indicates whether or not the Mapping Rules defined in this section
should override the ones listed in the SAML Validation Template used
to process the assertion. This allows Security Token Service to use
Mapping Rules that are specific to the Assertion Issuer. If true, all the
Mapping Rules will be overridden by the settings listed in this section.
Override Simple User Mapping Simple user mapping consists of mapping the incoming token to a
user record by using a single token attribute and matching it against a
single user record attribute.
■User Token attribute references an attribute from the incoming
token that will be matched against the Datastore attribute
(defined below) of a user record. The values can be STS_
SUBJECT_ID for the NameID Value, or the name of an Attribute
contained in the Assertion's AttributeStatement
■Datastore attribute references the user record attribute that will
be matched against the User token attribute referenced above
Override User Name Identifier
Mapping
When enabled, define a NameID user mapping operation, which
consists of mapping the incoming SAML Assertion to a user record by
mapping the NameID Value to a single user record attribute, based on
the NameID format.
When enabled, Security Token Service will evaluate the NameID
format, and based on the Name Identifier mapping table which user
record attribute should be matched against the Name ID value
contained in the Assertion. The Name Identifier mapping table holds
the user record attributes to be used for the mapping operation. It
contains standard NameID formats, but it can be customized to define
custom Name ID formats.
■To add custom NameID format, click the add button on the Name
Identifier mapping table, and enter the custom URI.
■To set an attribute for a specific NameID format to be used for
mapping operation, set the user record attribute on the line for
that format.
Override Attribute Based User
Mapping
An Attribute Based User Mapping operation consists of mapping the
incoming token to a user record by using an LDAP query and token
attributes.
The format of the LDAP query defines the mapping rule and specifies
the token attributes to be used by their names, surrounded by %
character. For example, an LDAP query that will map a token based on
two token attributes (firstname and lastname) would be:
(&(sn=%lastname)(givenname=%firstname%))
STS_SUBJECT_ID contains the NameID Value.
STS_NAMEID_FORMAT contains the NameID Format
STS_NAMEID_QUALIFIER contains the NameID Qualifier
STS_SAML_ASSERTION_ISSUER contains the Issuer of the Assertion
Attributes present in the Assertion's AttributeStatement
Override Simple Partner Mapping A simple partner mapping operation consists of mapping the
incoming token to a partner requester by using a single token attribute
and matching it against a partner identification attributes.
■Partner Token attribute references an attribute from the incoming
token that will be matched against the Partner Datastore attribute
(defined below) of a Requester Partner. The values can be STS_
SUBJECT_ID for the NameID Value, or the name of an Attribute
contained in the Assertion's AttributeStatement.
■Partner Datastore attribute references the partner identification
attribute that will be matched against the Partner token attribute
referenced above.
Managing Token Service Partner Profiles
46-18 Administrator's Guide for Oracle Access Management
46.4.2 Managing a Token Service Partner Profile
Users with valid Administrator credentials can use this procedure to create, locate,
view, edit, or remove a token service partner profile.
Prerequisites
The prerequisites for Requester Partner Profiles are:
■A Relying Party Partner Profile must exist, in order to be able to set the default
Relying Partner Profile.
■WS-Trust Validation Templates must exist in order to set the templates that will be
used to validate tokens located in the OnBehalfOf element.
The prerequisites for Relying Partner Profiles are:
■Issuance Template must exist in order to configure which templates to use for
token issuance operations.
There are no prerequisites for Issuing Authority Partner Profiles.
To create, find, edit, or remove a partner profile
1. In the Oracle Access Management Console, click Federation at the top of the
window.
2. In the Federation console, select Partner Profiles from the View drop-down menu
in the Security Token Service section.
3. Select the desired profile type tab and proceed with following steps as needed.
■Requester Profiles
■Relying Party Profiles
■Issuing Authority Profiles
4. New Profile:
a. Click the New [Profile Type] button to display a fresh page for your
definition.
b. Enter general information for the chosen profile type (Table 46–7) and click the
Next button.
Override Partner Name Identifier
Mapping
When enabled, define the following: A NameID user mapping
operation consists of mapping the incoming SAML Assertion to a user
record by mapping the NameID Value to a single requester partner
identification attribute, based on the NameID format.
When enabled, Security Token Service will evaluate the NameID
format, and based on the Name Identifier mapping table which
partner identification attribute should be matched against the Name
ID value contained in the Assertion. The Name Identifier mapping
table holds the requester partner identification attributes to be used for
the mapping operation. It contains standard NameID formats, but it
can be customized to define custom Name ID formats.
■To add custom NameID format, click the add button on the Name
Identifier mapping table, and enter the custom URI.
■To set an attribute for a specific NameID format to be used for
mapping operation, set the requester partner identification
attribute on the line for that format.
Table 46–11 (Cont.) Issuing Authority Token Mapping Elements
Element Description
Managing Token Service Partner Profiles
Managing Token Service Partners and Partner Profiles 46-19
c. Token and Attributes: Use the appropriate table to provide details for the
chosen profile type:
Requester Profile Table 46–8
Relying Party Profile Table 46–9
Issuing Authority Profile Table 46–10
d. Click Save to submit (or click Cancel to dismiss the page) and then dismiss the
confirmation window.
5. Refine a Profile Search: "Refining a Profile Search"
a. Perform Steps 1 and 2.
b. Define your query and click the Search button.
c. In the Search Results table, click the name of partner to view, edit, or remove.
6. Edit a Profile:
a. In the Search Results table, click the name of profile to edit and click the Edit
button (or choose Edit from the Actions menu).
b. Make desired changes to partner information.
Requester Profile Table 46–8
Relying Party Profile Table 46–9
Issuing Authority Profile Table 46–10
c. Click Apply to submit the changes (or Revert to cancel changes) and then
dismiss the confirmation window.
7. Remove a Profile: To remove a profile, it is required not to be referenced
anywhere else.
To remove a Requester Partner Profile, it is required that:
■No Requester Partner references the profile.
■No WS-Security Validation Template references the profile
To remove a Relying Party Partner Profile, it is required that:
■No Relying Party Partner references the profile.
■No Requester Partner Profile references the profile.
To remove an Issuing Authority Partner Profile, it is required that:
■No Issuing Authority Partner references the profile
If these prerequisites are met, proceed as follows:
a. In the Search Results table, highlight the row containing the profile to remove.
b. Click the Delete (X) button (or choose Delete Selected from the Actions menu),
then dismiss the confirmation window.
46.4.3 Refining a Profile Search
As with Partner definitions, when you open the Partner Profiles node, all Partner
Profiles nodes become available. When you choose a specific type of Partner Profile
node, relevant Search controls, and the Search Results table, become available.
Managing Token Service Partner Profiles
46-20 Administrator's Guide for Oracle Access Management
Figure 46–3 illustrates a typical Search Profiles page. This one is for a Requester
Profile. However, all controls are the same; only the results differ for different profile
types.
Figure 46–9 Search Partner Profiles Page: Requester Profiles
From the Search page you can simply select a name in the Search Results table to view
or edit the Profile, or use the controls to refine your search to locate a specific Profile or
a Profile with specific characteristics.
47
Troubleshooting Security Token Service 47-1
47
Troubleshooting Security Token Service
This chapter provides troubleshooting tips for Security Token Service:
■Authorization Issues
■Endpoint Issues
■Mapping Operation Issues
47.1 Authorization Issues
Problem: Authorization Failure during Token Issuance operation
During a WS-Trust request issuance operation, the Security Token Service returns an
error.
Error Message
The following are sample error messages that can be seen in the logs:
<Error> <oracle.security.fed.controller.ApplicationController> <STS-12064>
<Exception: {0}
oracle.security.fed.event.EventException:
oracle.security.fed.event.EventException: Authorization Failure for Relying
Party=%RELYING_PARTY_ID%, Requester=%REQUESTER_ID% and User=%USER_ID%
When:
■
%RELYING_PARTY_ID%
indicates the Relying Party Partner ID.
–If the WS-Trust request did not contain an AppliesTo element, then the
%RELYING_PARTY_ID%
is set to MissingRP
–if the WS-Trust request contained an AppliesTo element but it could not be
mapped to a Relying Party Partner, then the
%RELYING_PARTY_ID%
is set to
UnknownRP
–if the WS-Trust request contained an AppliesTo element and it was mapped to
a Relying Party Partner, then the
%RELYING_PARTY_ID%
is set to Relying Party
Partner ID.
■
%REQUESTER_ID%
is set to the Requester Partner ID, if the incoming request was
mapped to a Requester Partner. If
%REQUESTER_ID%
is not null, it will be used when
evaluating the Token Issuance Policy, against any present Identity Condition.
■
%USER_ID%
is set to the User ID, if the incoming request was mapped to a user
record. If
%USER_ID%
is not null and if
%REQUESTER_ID%
is null, it will be used when
evaluating the Token Issuance Policy, against any present Identity Condition.
Endpoint Issues
47-2 Administrator's Guide for Oracle Access Management
Issue
The Token Issuance Policy evaluation failed due to one of the following reasons:
■No TokenServiceRP resource referencing the
%RELYING_PARTY_ID%
is defined and
assigned to a Token Issuance Policy. In this case, create TokenServiceRP resource
referencing the
%RELYING_PARTY_ID%
and assign it to a Token Issuance Policy.
■A TokenServiceRP resource referencing the
%RELYING_PARTY_ID%
exists and is
assigned to a Token Issuance Policy, but the policy contains conditions that are not
met. In this case, review the policy rules: if the policies are correct, then the client
is not allowed to request a token; otherwise, update the policies/conditions to
include the client's identity.
47.2 Endpoint Issues
Problem: Endpoint not found
When accessing an Security Token Service endpoint that has been added via the Oracle
Access Management Console, the server returns an error indicating that the page does
not exist when retrieving the WSDL policy or that the endpoint does not exist.
Error Message
The following are possible error messages:
■When retrieving the WSDL policy, a 404 HTTP error code is returned.
■When sending a WS-Trust request, an error is reported:
<Error> <oracle.webservices.service> <OWS-04115> <An error occurred for port:
PortableProvider: oracle.j2ee.ws.server.EndpointNotFoundException: /PATH.>
Solution
Security Token Service is deployed but not enabled. To enable Security Token Service,
perform the following operations:
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Configuration console, click Available Services.
3. Enable the Security Token Service.
Security Token Service detects the change and publishes the endpoints. No restart is
required.
47.3 Mapping Operation Issues
Problem: Failure to map the AppliesTo element to a Relying Party Partner
When Security Token Service processes a WS-Trust request with an AppliesTo element
referencing the Web Service Provider, the server will attempt to map the location
contained in the AppliesTo element to an Security Token Service Relying Party Partner
using the Resource URL defined in the Partner entry. If such a mapping fails, the
server will log an Info message in the logs indicating that the operation failed and
indicating what was the AppliesTo address used.
Error Message
The following is a sample of an error message:
Mapping Operation Issues
Troubleshooting Security Token Service 47-3
[2011-04-22T15:08:12.632-07:00] [oam_server1] [NOTIFICATION] [STS-15542]
[oracle.security.fed.eventhandler.sts.creation.v13.CreateV13TokenEventHandler]
[tid: [ACTIVE].ExecuteThread: '0' for
queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid:
f00aacae2d3f3ded:125005ed:12f7f412274:-8000-0000000000000016,0] [WEBSERVICE_
PORT.name: wssuser-port] [APP:
oam_server] [J2EE_MODULE.name: sts] [WEBSERVICE.name: wssuser-serviceSoap12]
[J2EE_APP.name: oam_server] The mapping
of the AppliesTo element from the WS-Trust Request to a Relying Party Partner
failed: could not map
http://relying.party.test.com/testing/service
Solution
If the AppliesTo location should have been mapped to a Relying Party Partner, then
the Partner settings should be verified to ensure that the Resource URLs are correctly
defined to:
■be the exact match of the AppliesTo address
■be a parent of the AppliesTo address.
For example, if the AppliesTo address is http://relying.party.test.com/testing/service,
a parent could be http://relying.party.test.com/testing/ or
http://relying.party.test.com/. In both cases, the AppliesTo location would be
mapped to a Relying Party Partner with any of those Resource URLs defined.
In certain cases, failure to correctly map the AppliesTo address to a Relying Party
Partner will result in errors due to:
■Authorization evaluation failures
■Security Token Service not being able to retrieve certificate belonging to the
Relying Party Partner.
Note: this message is recorded at Notification level, thus in order for
Security Token Service to record it, the appropriate logging level must
be set to include the Notification:1 level.
Mapping Operation Issues
47-4 Administrator's Guide for Oracle Access Management
Part XI
Part XI
Managing Oracle Access Management
Mobile and Social
This part documents Oracle Access Management Mobile and Social.
Mobile and Social serves as an intermediary between a user or client seeking to access
protected resources, and the back-end Oracle Access Management and Oracle Identity
Management services that protect the resources. Mobile and Social provides simplified
client libraries that allow developers to quickly add feature-rich authentication,
authorization, and Identity capabilities to registered applications. On the back-end, the
Mobile and Social service's pluggable architecture lets system Administrators
customize the access management services without having to update the installed
software.
Part IX contains the following chapters:
■Chapter 48, "Understanding Mobile and Social"
■Chapter 49, "Configuring Mobile and Social Services"
■Chapter 50, "Configuring Social Identity"
■Chapter 53, "Configuring OAuth Services"
■Chapter 51, "Configuring Social Identity System Settings"
48
Understanding Mobile and Social 48-1
48
Understanding Mobile and Social
This chapter describes the purpose and capabilities of Oracle Access Management
Mobile and Social. It includes the following topics.
■Introducing Mobile and Social
■Understanding Mobile and Social Services
■Understanding the Mobile and Social Services Processes
■Using Mobile and Social Services
■Understanding Social Identity
■Understanding Social Identity Processes
■Using Social Identity
48.1 Introducing Mobile and Social
The Oracle Access Management Mobile and Social service acts as an intermediary
between a user or client seeking to access protected resources, and the back-end Access
Management and Identity Management services that protect the resources. Mobile and
Social provides simplified client libraries that allow developers to quickly add
feature-rich authentication, authorization, and identity capabilities to registered
applications. On the back-end, the Mobile and Social server's pluggable architecture
lets system administrators customize identity and access management services
without updating the user's client software or mobile applications. Mobile and Social
provides two complimentary feature sets:
■Mobile and Social Services (formerly Mobile Services) connects applications and
devices to the enterprise Access Management and Identity Management services
available in the Oracle Identity Access Management product suite. This makes it
easy to utilize sophisticated authentication and authorization services
functionality (such as mobile device and application registration, and device
fingerprinting) to restrict access to authorized devices only. Client applications can
also implement knowledge-based authentication, a powerful feature that goes
beyond basic password-based authentication.
Mobile and Social Services can be configured to require a valid device and client
credential and a User Token with each application token request. This ensures that
only an authorized user can access a protected resource, and then only if the user
Note: Device fingerprinting and knowledge-based authentication
both require Oracle Adaptive Access Manager.
Introducing Mobile and Social
48-2 Administrator's Guide for Oracle Access Management
is running an authorized application on an authorized device. Mobile and Social
Services also provides easy access to User Profile Services if Mobile and Social is
integrated with an LDAP compliant directory server.
■Social Identity allows Mobile and Social to serve as the relying party when
interacting with popular cloud-based identity authentication and authorization
services, such as Google, Yahoo, Facebook, Foursquare, Windows Live, Twitter,
and/or LinkedIn. After deploying Mobile and Social, a user is provided with
multiple log-in options without the need to implement each provider individually.
This allows users to access protected resources using their credentials from a
trusted Identity Provider.
■OAuth Services allows organizations to implement the open standard OAuth 2.0
Web authorization protocol in an Access Manager environment. OAuth enables a
client to access Access Manager protected resources that belong to another user
(that is, the resource owner). Applications that use Mobile and Social Services, and
applications that use OAuth Services can co-exist on the same desktop or mobile
device, but each requires its own separate implementation.
In addition to tight integration with Access Manager, Mobile and Social is "pre-wired"
to work with other back-end Identity and Access Management Service offerings,
including Oracle Adaptive Access Manager and a variety of LDAP compliant
directory servers. On the front-end, Mobile and Social provides easy to use SDKs for
integration of client applications on the Java, Android, and iOS platforms. The client
applications then use simple REST calls to communicate with the Mobile and Social
server.
You can configure Mobile and Social Services and Social Identity to work together. For
example, use Social Identity to let users authenticate with Google, Facebook, Twitter,
and so on, and use Mobile and Social Services to (a) provide local authentication
functionality, or (b) generate a User Token by accepting a User Identity assertion from
a social Identity Provider. Mobile and Social Services can also enhance device
registration security when used in conjunction with Social Identity.
Note: Prior to version 11.1.2.3, Mobile and Social Services was
named Mobile Services.
Note: Prior to version 11.1.2.2, Social Identity was named Internet
Identity Services.
Note: REST (REpresentational State Transfer) is the software
architectural style with which the World Wide Web has been
developed. It is lightweight and especially well-suited to building
web-based applications and services.
Introducing Mobile and Social
Understanding Mobile and Social 48-3
The following sections contain additional information and documentation links
regarding the installation and deployment of Mobile and Social.
■Installing Mobile and Social
■Deploying Mobile and Social
■Enabling Mobile and Social
48.1.1 Installing Mobile and Social
You install Mobile and Social together with Access Manager. You can configure Mobile
and Social to run by itself, or in combination with either Access Manager or Oracle
Adaptive Access Manager (OAAM), or you can deploy all three together. Depending
on the software deployed alongside Mobile and Social, the available features may vary.
Table 48–1 provides the details.
Note: Mobile and Social provides security layer functionality to
registered applications that run on either Android or iOS devices, or
in a Java SE JVM, or that communicate with the service using REST
calls. If you require additional mobile functionality, ADF Mobile, a
complimentary Oracle product offering, provides an application
development framework for creating full-featured applications for
iOS-powered devices. For more information, see the Oracle Fusion
Middleware Mobile Developer's Guide for Oracle Application Development
Framework.
Table 48–1 Features in Mobile and Social Based on the Companion Services Installed
Feature
Mobile and
Social Only
Mobile and
Social +
Access
Manager
Mobile and
Social +
OAAM
Mobile and
Social +
Access
Manager +
OAAM
Access Manager token support
using native Access Manager
authentication dialogs
✔✔
JWT token support for
authentication and
authorization
✔✔ ✔ ✔
Ability to uniquely identify
connecting mobile devices
(Device fingerprinting)
✔✔
Basic (limited) device security
checks during device
registration, access requests
✔✔
Advanced device security
checks during device
registration and access
requests, including risk-based
access controls (for example,
allow or deny access based on
geolocation and other device
attributes)
✔✔
Introducing Mobile and Social
48-4 Administrator's Guide for Oracle Access Management
For installation details, see the Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management.
48.1.2 Deploying Mobile and Social
The following list contains information and links regarding several Mobile and Social
deployments.
■If deploying Mobile and Social together with Access Manager, both can be
deployed together on the same server, either in the same domain or in separate
domains. For details, see the Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management.
■If deploying Mobile and Social alongside Oracle Access Manager 10g or 11gR1
PS1, Mobile and Social and Oracle Access Manager need to be installed on
different servers in different domains. For details, see Section 51.3, "Deploying
Mobile and Social With Oracle Access Manager."
■If deploying Mobile and Social with a WebGate, Mobile and Social can generate
the Oracle Access Management token that clients need to access the
WebGate-protected resources. The following restrictions apply:
–If you deployed Oracle Access Management 11gR2 (11.1.2), Mobile and Social
can generate a token that can access either an 11g WebGate or a 10g WebGate.
–If you deployed either Access Manager 11gR1 (11.1.1) or 10g, Mobile and
Social can generate an Oracle Access Management token that can access a 10g
WebGate only.
Multi-step authentication
support (knowledge-based
authentication and one time
password support)
✔✔
Interact with a Directory server
and support User Profile
services
✔✔ ✔ ✔
Relying party support for
Internet-based Identity
Providers (Facebook, Google,
Twitter, LinkedIn, Yahoo)
✔✔ ✔ ✔
Note: If Access Manager is already installed, you cannot add Mobile
and Social to an Oracle Access Management installation by extending
the OAM domain. Attempting to do so will result in an error similar
to the following:
CFGFWK-64071- the selection conflicted with templates
already installed in the domain OAM with database policy
store 11.1.1.3.0
Table 48–1 (Cont.) Features in Mobile and Social Based on the Companion Services
Feature
Mobile and
Social Only
Mobile and
Social +
Access
Manager
Mobile and
Social +
OAAM
Mobile and
Social +
Access
Manager +
OAAM
Understanding Mobile and Social Services
Understanding Mobile and Social 48-5
■When moving Mobile and Social from a test environment to a production
environment, see Section 51.5, "Configuring Social Identity After Running
Test-to-Production Scripts."
48.1.3 Enabling Mobile and Social
To leverage the Mobile and Social functionality, the service should be explicitly
enabled. Follow these steps to enable the Mobile and Social service.
1. Log in to the Oracle Access Management Console.
The Launch Pad opens.
2. Click Available Services in the Configuration pane.
The Available Services page opens.
3. Click Enable next to Mobile and Social.
48.2 Understanding Mobile and Social Services
Mobile and Social Services connect applications running on client devices to the
security services and products available in the Oracle Identity Access Management
product suite. In addition, User Profile Services is a Mobile and Social Services feature
that connects client applications to many popular LDAP compliant directory servers.
Mobile and Social Services consists of the following components:
■A server component that interfaces with your backend Identity Services
infrastructure. The server acts as an intermediary between supported client
applications (and the users using those applications) and your backend Identity
services. This arrangement decouples the client applications from the backend
infrastructure so that you can modify your backend infrastructure without having
to update your client programs. You can enable the Mobile and Social service to
run by itself or in combination with the Access Manager service and/or the
OAAM product as discussed in Section 48.1, "Introducing Mobile and Social."
■A server-side device store that can store security material, such as security tokens
and security information required by the OAAM Security Handler Plug-in. The
server-side device store provides several benefits: It improves security because
tokens managed by the server-side device store are not sent to the client
application where they can be copied if the device or client app is compromised; it
eliminates the need for mobile client applications to manage and synchronize
security material; and finally it allows security material to be shared and
synchronized among multiple client apps.
■A Mobile and Social Mobile and Social Services Client Software Development Kit
(Client SDK) is available for Android and iOS devices and Java. It is used to build
authentication, authorization, and directory-access functionality into applications
that run on mobile and desktop devices. The Mobile and Social Services Client
SDK can also be used to build a mobile single sign-on (SSO) agent application (for
Android and iOS devices only). Mobile SSO is described in Section 48.2.3,
"Understanding Single Sign-on (SSO) for Mobile and Social Services." The Mobile
and Social Mobile and Social Services Client SDK is described in Section 48.2.4,
"Introducing the Mobile and Social Services Client SDK."
The following sections contain more detailed information regarding the Mobile and
Social Services portion of Mobile and Social.
■Introducing Authentication Services and Authorization Services
Understanding Mobile and Social Services
48-6 Administrator's Guide for Oracle Access Management
■Understanding the Mobile and Social Services Authorization Flow
■Understanding Single Sign-on (SSO) for Mobile and Social Services
■Introducing the Mobile and Social Services Client SDK
■Introducing User Profile Services
48.2.1 Introducing Authentication Services and Authorization Services
Authentication and Authorization Services lets you extend an existing authentication
and authorization infrastructure to include mobile and non-mobile applications.
Mobile and Social Services supports the following common token types:
■A User Token grants the token bearer with the permissions associated with the
person who has been authenticated.
■An Access Token grants access to a specific protected resource, such as a web
resource or a URL.
■A Client Token grants access to a non-mobile hardware device, such as a web
application or server application.
■A Client Registration Handle (similar to a Client Token) is also used by Mobile and
Social Services. It represents a mobile client application running on a mobile
device. Mobile and Social uses the Client Registration Handle to register mobile
devices, whereas non-mobile Service Providers use Client Tokens to authenticate
non-mobile devices.
A mobile device is a device that runs a mobile operating system, such as the Android
mobile operating system from Google or the iOS mobile operating system from Apple,
while a non-mobile device is a device that runs a non-mobile operating system, such
as Mac OS X, Windows 7, and Lynx desktop. Because mobile devices and non-mobile
devices present different security challenges, mobile authentication and non-mobile
authentication are managed separately in Mobile and Social. New mobile devices
come online much more frequently and therefore require greater scrutiny, including
heightened fraud detection measures.
Mobile and Social supports Oracle Access Manager tokens (if Access Manager is
installed with Mobile and Social) and JWT (JSON Web Token) tokens. Each token type
has a corresponding mobile and a non-mobile Service Provider. Mobile and Social
provides six pre-configured Authentication Service Providers:
■OAM Authentication
■Mobile OAM Authentication
■JWT Authentication
■Mobile JWT Authentication
■JWT-OAM Authentication
■Mobile JWT-OAM Authentication
Table 48–2 describes the Authentication Service Providers.
Note: A non-mobile device can use either mobile services or
non-mobile services as long as the correct input is provided.
Understanding Mobile and Social Services
Understanding Mobile and Social 48-7
48.2.2 Understanding the Mobile and Social Services Authorization Flow
The Mobile and Social Services authorization flow is used if the client application
implements mobile security using the Mobile and Social Client SDKs for Android, iOS,
or Java, or if the client app goes through a Mobile SSO Agent app (covered later) to
establish mobile security. In this flow the client app (or the Mobile SSO Agent) collects
user inputs and maintains the user session on the mobile device.
The diagrams in the following sections depict the Mobile and Social Services
authorization flow:
■Section 48.3.1, "Registering a Mobile Device With User Authentication"
■Section 48.3.2, "Authenticating a User With a Registered Device"
■Section 48.3.3, "Using REST Calls for User Authentication"
■Section 48.3.4, "Authenticating the User With a Mobile Browser-Based Web App"
48.2.3 Understanding Single Sign-on (SSO) for Mobile and Social Services
Mobile Single Sign-on (Mobile SSO) lets a user run multiple mobile applications on the
same device without having to provide credentials for each one. Both native and
browser-based applications can participate in Mobile SSO.
Table 48–2 Mobile and Non-Mobile Authentication Service Providers in Mobile and
Social Services
Authentication Service
Provider Description
OAMAuthentication Lets users running a web application from a desktop device
authenticate using Access Manager.
MobileOAMAuthentication Lets users using mobile devices authenticate using Access
Manager
JWTAuthentication Lets users running a web application from a desktop device
authenticate using the JSON Web Token format. JSON Web
Token is a compact token format that is suitable for
space-constrained environments such as HTTP
Authorization headers.
MobileJWTAuthentication Lets users using mobile devices authenticate using the JSON
Web Token format.
JWTOAMAuthentication Allows lightweight, long-duration JWT tokens to be
exchanged for OAM tokens. OAM tokens provide SSO and
OAM resource access to clients. This provider allows users
using non-mobile applications to get a new OAM token
without having to provide credentials if they have a valid,
long-duration JWT token.
MobileJWTOAMAuthentication Allows lightweight, long-duration JWT tokens to be
exchanged for OAM tokens. OAM tokens provide SSO and
OAM resource access to clients. This provider allows users
using mobile applications to get a new OAM token without
having to provide credentials if they have a valid,
long-duration JWT token.
Note: Mobile and Social Services apps and Mobile OAuth apps
require separate SSO implementations. For information about single
sign-on for Mobile OAuth applications, see Section 52.8,
"Understanding Mobile OAuth Services Server-Side Single Sign-on."
Understanding Mobile and Social Services
48-8 Administrator's Guide for Oracle Access Management
Understanding the Mobile SSO Agent App
A special app installed on a mobile device can be designated as a Mobile SSO Agent.
This app serves as a proxy between the remote Mobile and Social server and the other
apps on the device that need to authenticate with the back-end Identity services. The
Agent can either be a dedicated agent (that is, an app that serves no other purpose), or
a business (client) app that also provides agent functionality.
The Mobile SSO Agent handles device registration and advanced authentication
schemes (including multi-factor authentication and one time password
authentication), so this functionality does not have to be built into each mobile
application. When the Mobile SSO Agent is present, user credentials are never exposed
to the mobile business applications. The Mobile SSO Agent and SSO Client interact as
follows:
■The SSO Client app sends the device registration request, the application
registration request, and the User Token request to the SSO Agent.
■The SSO Agent makes the necessary acquisitions on behalf of the SSO Client.
■The SSO Client app then requests any Access Tokens it needs using the
registration handle and User Token.
■The SSO Agent app stores tokens and security material on behalf of the mobile
SSO Client, similar to the server-side device store.
A browser-based business app can also be configured to use a Mobile SSO Agent for
authentication. If that is the case, launching a browser-based business app invokes the
Mobile SSO Agent and causes the agent to collect a user name and password, and send
them to the Mobile and Social server. If the business app and the agent are authorized
for SSO, the Mobile and Social server authorizes access. The agent then requests an
Access Token for the resource (on behalf of the business app) and redirects the browser
to the URL of the business app with the Access Token included in the headers.
From the user's perspective, native and browser-based apps open on the device
without asking the user to provide credentials. If the agent is not installed on the
mobile device, or if the business app is not approved for Mobile SSO, the user will
have to directly and independently send his or her credentials to the Mobile and Social
server with each and every app that is launched.
The Mobile SSO Agent can time-out idle sessions, manage global logout for all apps,
and assist in device selective wipe outs. Furthermore, it supports basic offline
authentication. The agent one-way encrypts user passwords for local storage. During
offline authentication, the agent validates the user name and password with the locally
stored version. The agent then enforces all session idle time-outs and local password
expiration policies.
When using a mobile SSO agent, apps open on the device without asking the user to
provide credentials. If the agent is not installed on the mobile device, or if the business
app is not approved for Mobile SSO, the user will have to directly and independently
send his or her credentials to the Mobile and Social server with each and every app
that is launched.
Note: Before an app can use the Mobile SSO agent app to
authenticate with the Mobile and Social server, you must configure the
app as either a Mobile SSO Agent or Client on the server. For more
information about configuring Mobile and Social Services security for
Mobile SSO, see Section 49.7, "Defining Service Domains."
Understanding Mobile and Social Services
Understanding Mobile and Social 48-9
Oracle does not provide a pre-built Mobile SSO Agent, however, documentation is
provided so that you can build a Mobile SSO Agent app using the Mobile and Social
Services Client SDK for Android or iOS. For more information about creating a Mobile
SSO Agent app, refer to either the Android or the iOS Mobile and Social Services SDK
documentation in the Oracle Fusion Middleware Developer's Guide for Oracle Access
Management.
48.2.4 Introducing the Mobile and Social Services Client SDK
The Mobile and Social Services Client SDK contains individual SDKs for Android and
iOS devices, and for Java Virtual Machines (JVMs). Table 48–3 documents each Mobile
and Social Services Client SDK feature and the software on which it works.
48.2.5 Introducing User Profile Services
User Profile Services makes it possible to build an application that lets a user in your
organization access the User Profile Services from mobile devices. User Profile Services
allows Web, mobile, and desktop applications to perform a variety of LDAP compliant
directory server tasks including:
■Create, read, update, and delete functionality for users and groups
■Search functionality
■Org (organization) chart reporting functionality
Towards this end, the Mobile and Social server can interface with many popular LDAP
compliant directory servers including:
■Microsoft Active Directory
■Novell eDirectory
■Oracle Directory Server Enterprise Edition
■Oracle Internet Directory
■Oracle Unified Directory
■Oracle Virtual Directory
■Open LDAP
Note: The Mobile SSO Agent is only supported on Android and iOS
devices.
Table 48–3 Android, iOS, and Java Features of the Mobile and Social Services Client
SDK
Feature Android iOS Java
Build a mobile application that can acquire Client
Registration Handle, User, and Access Tokens
through a Mobile and Social Server
✔✔
Build a desktop application that can acquire Client,
User, and Access Tokens through a Mobile and
Social Server
✔
Interact with a Directory server and implement User
Profile Services
✔✔✔
Create a mobile single sign-on (SSO) application ✔✔
Understanding the Mobile and Social Services Processes
48-10 Administrator's Guide for Oracle Access Management
■WebLogic Server Embedded LDAP
Refer to the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for
sample code that demonstrates how to use the SDK for User Profile Services.
48.3 Understanding the Mobile and Social Services Processes
When a user tries to access a protected resource, Mobile and Social requires either a
Client Token (if the user is connecting through a server or a computer which securely
stores client credentials) or a Client Registration Handle (if the user is using a mobile
device). Thus, client devices (including mobile devices) and client applications must
register with Mobile and Social before access to protected resources can be granted.
Client applications running on mobile devices follow this high-level authentication
process before the mobile application can access a protected resource.
1. The user enters a user name and password at the application login screen and
authenticates with the Mobile and Social server.
2. If a mobile device has not previously registered with the Mobile and Social server,
the server sends the mobile device a Client Registration Handle after
authenticating the user.
3. The Client Registration Handle is submitted back to the Mobile and Social server
to get a User Token.
4. The Client Registration Handle and User Token are submitted back to the Mobile
and Social server to get an Access Token.
A non-mobile application can also make use of Authentication Services provided by
Mobile and Social Services. In such cases, a Client Token takes the place of the Client
Registration Handle. After the Client Token is obtained, a User Token and Access
Token can be requested as documented above. Additional scenarios are documented in
these sections.
■Registering a Mobile Device With User Authentication
■Authenticating a User With a Registered Device
■Using REST Calls for User Authentication
■Authenticating the User With a Mobile Browser-Based Web App
■Authorization Using the Mobile OAuth Authorization Flow
48.3.1 Registering a Mobile Device With User Authentication
When the mobile device attempting to access a protected resource has not previously
registered with Mobile and Social, a Mobile SSO Agent must be installed. The
registration authentication process is documented in the following flow. Figure 48–1
Note: Any device capable of HTTP communication can use User
Profile Services by sending REST calls to the Mobile and Social server.
See "Sending Mobile and Social REST Calls With cURL" in the Oracle
Fusion Middleware Developer's Guide for Oracle Access Management.
Note: Applications are also typically configured to require a User
Token and an Access Token.
Understanding the Mobile and Social Services Processes
Understanding Mobile and Social 48-11
and Figure 48–2 follow the text and illustrate the process.
1. The user launches an application on a mobile device.
2. The application redirects the user to the Mobile SSO Agent.
3. The Mobile SSO Agent displays a login page.
4. The user enters a user name and password.
5. The Mobile SSO Agent sends the user name and password to the Mobile and
Social server along with the device attributes and application ID.
6. The Mobile and Social server forwards the user name and password to Access
Manager which authenticates the user.
7. The Mobile and Social server sends device attributes and other authentication
results to the OAAM Mobile Security Handler Plug-in which executes the policy
stored on the OAAM server.
The OAAM Security Handler Plug-in creates two security handles (snippets of
data that Mobile and Social stores with either the Mobile SSO Agent or the
business application itself). Each handle stores a name, value, and expiration
timestamp.
■The
oaam.device
handle represents the mobile device. (Different client
applications on the same device all have the same device handle value.)
OAAM uses this handle as a key to retrieve the full device profile stored in the
OAAM database. This handle has a relatively long life span.
■The
oaam.session
handle represents an OAAM login session for a client
application. (Each client application on a device has a unique session handle
value.) OAAM uses this handle as a key to retrieve details about the OAAM
session stored in the OAAM database. When the user logs out from the client
application, the
oaam.session
handle is removed.
8. The Mobile and Social server returns the Mobile Client Registration Handle and
OAAM device and session handles to the Mobile SSO Agent.
9. The Mobile SSO Agent gets a User Token by passing the Client Registration
Handle and OAAM device handles that it previously received to the server.
10. The Mobile SSO Agent requests an Access Token from Access Manager. The
request contains the Client Registration Handle and OAAM device handles. See
Figure 48–2.
Note: OAAM has two registration flows—active and passive. The
active flow prompts the user with a challenge before allowing the
device registration process to proceed. The passive flow continues
without challenging the user.
Understanding the Mobile and Social Services Processes
48-12 Administrator's Guide for Oracle Access Management
Figure 48–1 First Time Device/Application Registration and Authentication Process
Mobile User
Customer
App (Mobile
Device)
Mobile
SSO
Agent
Mobile and
Social
Server
Access
Manager OAAM
Access App
getSession() &
getAccessToken()
Get App Profile
Register (User, password, device attributes, appID)
Register App (appID, device profile attribute)
OAAM Device Handle and
OAAM Session Handle
*Authenticate (User, password, attributes)
Mobile Client Registration Handle,
OAAM Device and Session Handles
Get User Token
Get Access To ke n
Successful User Authentication
Present Login Page
User name/Password
Understanding the Mobile and Social Services Processes
Understanding Mobile and Social 48-13
Figure 48–2 Mobile SSO Agent Requests Access Token from Access Manager
48.3.2 Authenticating a User With a Registered Device
This scenario describes a user with a mobile device (already registered with Mobile
and Social) launching a Mobile and Social compatible business application. In this
scenario the Mobile SSO Agent is already installed and the user needs to access a
protected resource that requires an Access Token. The business application must first
acquire the User Token before it can request the Access Token. The accompanying
figures (Figure 48–3 and Figure 48–4) illustrate the process.
1. The user launches the business application on a mobile device.
2. The business application asks the Mobile SSO Agent for a User Token and one of
the following occurs.
a. If a valid User Token exists in the local credential store, the Mobile SSO Agent
returns it to the business application. The business application inserts the User
Mobile User
Customer
App (Mobile
Device)
Mobile
SSO
Agent
Mobile and
Social
Server
Access
Manager OAAM
Access App
getSession() &
getAccessToken()
Get App Profile
Register App (appID, oaam device handle,
device profile attributes)
OAAM Result/ Action
Authenticate (User, password, attributes)
Client Registration Handle for Customer App
Get Access Token
Successful Authentication
Present Login Page
User name/Password
Understanding the Mobile and Social Services Processes
48-14 Administrator's Guide for Oracle Access Management
Token into a direct request to the Mobile and Social server for the Access
Token. The flow completes when the business application uses the Access
Token returned by the server to access the protected resource (as in
Figure 48–3).
Figure 48–3 Mobile SSO Agent Has Valid Access Token in Credential Store
b. If a valid User Token does not exist in the local credential store, the login flow
continues (as in Figure 48–4).
3. The Mobile SSO Agent presents a login page and the user enters a user name and
password.
4. The Mobile SSO Agent sends the user name, password, and Client Registration
Handle to the Mobile and Social server. (Step 2 in Figure 48–4).
5. The Mobile and Social server validates the Client Registration Handle,
authenticates the user credentials (with either the JWT token service or the Access
Manager token service), invokes OAAM for risk analysis and then returns the
User Token to the Mobile SSO Agent. (Step 3 in Figure 48–4).
6. The Mobile SSO Agent stores a copy of the user token in its local credential store
and returns the User Token to the business application. (Step 4 in Figure 48–4).
7. The business application uses the User Token to make a direct request to the
Mobile and Social server for the Access Token. (This step is not shown in the
diagram.)
8. The Mobile and Social server returns the Access Token to the Mobile SSO Agent.
9. The business application uses the Access Token to make calls to the resource
protected by Access Manager or Oracle Enterprise Gateway (OEG). (Step 5 in
Figure 48–4).
Access
Manager
Mobile and Social
Client
REST/
SOAP
Server
OAAM
1
Access
To k e n
Authentication
REST/SOAP
2
3
Mobile SSO Agent
User App
Client Web Tier
Understanding the Mobile and Social Services Processes
Understanding Mobile and Social 48-15
Figure 48–4 Mobile SSO Agent Does Not Have Valid Access Token in Credential Store
48.3.3 Using REST Calls for User Authentication
In this scenario an application running on a mobile device interfaces with the Mobile
SSO Agent, which communicates with the Mobile and Social server using REST calls.
The server interfaces with Access Manager and OAAM as needed and returns the
necessary tokens to the Mobile SSO Agent (again using REST calls). The agent
forwards the tokens back to the application, which can now access the protected
resource using either REST or SOAP calls. The process is documented in the following
flow. Figure 48–5 follows the text and illustrates the process.
1. The user launches an application on a mobile device.
2. Because the client application needs to access a resource protected by Access
Manager, the client application asks the Mobile SSO Agent for an Access Token.
3. The Mobile SSO Agent gets the Application Profile from the Mobile and Social
server.
4. The Mobile SSO Agent prompts for a user name and password.
5. The Mobile SSO Agent sends the user name and password to the Mobile and
Social server along with the device attributes and application ID.
6. The Mobile and Social server registers the device and authenticates the user.
7. The server returns an Access Token to the Mobile SSO Agent.
8. The Mobile SSO Agent saves the hashed password in its local credential store.
9. The Mobile SSO Agent passes the Access Token to the client application.
10. The client application accesses the protected resource by presenting the Access
Token.
Client App (Mobile)
Request User Token
Use token to make
REST/SOAP calls to
client server protected by
Access Manager or OEG
Mobile SSO Agent Mobile and Social Server
(Server)
2
4
5
13
Oracle
SDK
• If valid User token exists in
localcredential store,
return the token to App.
Else continue below.
• Present login page.
• Accept username/password.
• Extract device attributes
and ID contexts.
• Makes authentication call
with user/password, and
device attributes.
• Stores User/Access To ke n
• Returns token to Client App
• Authenticates with
Access Manager
• Publishes ID context to
Access Manager
• Invokes OAAM for risk
analysis
• Responds User/Access
To ke n s
Understanding the Mobile and Social Services Processes
48-16 Administrator's Guide for Oracle Access Management
Figure 48–5 User Authentication Using REST
48.3.4 Authenticating the User With a Mobile Browser-Based Web App
This scenario describes a user with a Mobile and Social registered mobile device
launching a Mobile and Social compatible browser-based web application. In this
scenario the Mobile SSO Agent is installed. The legacy authentication process is
documented in the following flow. Figure 48–6 follows the text and illustrates the
process.
1. The user opens a URL in a web browser on a mobile device.
2. The application web server redirects the browser to Access Manager.
3. Access Manager sends the web browser a URL redirect.
4. The web browser responds to the redirect by launching the Mobile SSO Agent.
If the agent is not installed, a link with instructions to install the Mobile SSO Agent
application is displayed.
5. The Mobile SSO Agent displays the User login page.
6. The user enters a user name and password.
7. The Mobile SSO Agent sends the user name, password, and Client Registration
Handle to the Mobile and Social server. (This step is not shown in the diagram.)
8. The Mobile and Social server validates the Client Registration Handle,
authenticates the credentials with Access Manager, publishes the ID context to the
Access Manager server, and invokes OAAM for risk analysis.
9. Access Manager returns a User Token or an Access Token to the Mobile and Social
server which, in turn, returns the User Token or the Access Token to the Mobile
SSO Agent. (This step is not shown in the diagram.)
Client Web Tier
Access
Manager
OAAM
Mobile
and Social
Client
REST/
SOAP
Server
Agent
7
Mobile Device
Mobile SSO Agent
Mobile and Social
SDK
Native App #1...#n
IDM SDK
2 6
1
3
5
Prompt Login
Store Credential
Device
Registration
REST/SOAP
Device
Provisioning
/Deprovisioning
Database
• Register Device/App
• Authenticate User
• Get Access To ke n
• Get User Attributes
4
Understanding the Mobile and Social Services Processes
Understanding Mobile and Social 48-17
10. The Mobile SSO Agent directs the browser to the Mobile and Social server where it
injects a cookie.
11. The Mobile SSO Agent sends the web browser a URL redirect and an Access
Token.
12. The mobile web browser responds to the redirect and opens the original web URL
because the access request now includes an Access Token.
13. The application web server sends the requested pages to the mobile web browser.
Figure 48–6 Authenticating User From Browser-based Web App on Registered Mobile
Device
48.3.5 Authorization Using the Mobile OAuth Authorization Flow
The following diagram shows at a high level the interactions between a mobile app
and the Oracle Access Management OAuth service in the context of Mobile and Social
Services. To understand the difference between the legacy authorization flow and the
Mobile OAuth authorization flow, see Section 48.2.2, "Understanding the Mobile and
Social Services Authorization Flow."
For a detailed look at the OAuth authorization flow in the context of the OAuth
Service, see Section 52.3, "Understanding OAuth Services Authorization for Mobile
Clients."
Mobile User
Browser
(Mobile
Device)
Mobile
SSO
Agent
App Web
Server
Mobile and
Social Server
Access
Manager &
OAAM
Access Web URL
App Pages
Redirected to original Web URL
Fingerprint & Authenticate
Access To ke n
Pages from App Web Server
Inject cookie
Redirect
Present Login Page
Redirect to local app
Redirect to Access Manager
Redirect
User name/Password
Understanding the Mobile and Social Services Processes
48-18 Administrator's Guide for Oracle Access Management
1. The mobile app requests a client verification code by sending a device token.
The OAuth service returns the client verification code. If the APNS/GCM option is
enabled, the OAuth service returns half of the code using push notification, and
the other half over HTTPS. Push notification provides an extra level of assurance
for confirming the identity of the application and device.
2. The mobile app requests an authorization code by sending device claims and the
client verification code.
The OAuth service:
■Authenticates the user
■Requests the user's consent to register the app (optional)
■Invokes OAAM for risk analysis
■Returns the authorization code using push notification (optional) and HTTPS
3. The mobile app requests a Client Token by sending the authorization code and
device claims.
The OAuth service returns the Client Token using push notification (optional) and
HTTPS.
4. The mobile app requests an Access Token by sending the Client Token, the
authorization code, and the device claims.
The OAuth service returns the Access Token.
5. The mobile app requests access to the protected resources using the Access Token.
(Not shown in the diagram.)
The resource server returns the protected resources to the client application. (Not
shown in the diagram.)
Using Mobile and Social Services
Understanding Mobile and Social 48-19
Figure 48–7
48.4 Using Mobile and Social Services
The following sections describe how you might use the Mobile and Social Services.
■Protecting the Mobile Client Registration Endpoint
■Exchanging Credentials
■Protecting User Profile Services And Authorization Services
■Using Mobile and Social Services with Oracle Access Manager
■Using Mobile and Social Services with Oracle Adaptive Access Manager Services
48.4.1 Protecting the Mobile Client Registration Endpoint
A mobile device attempting to access a protected resource must register with the
Mobile and Social server as the server rejects anonymous requests sent to its
registration endpoint. Additionally, each Service Domain should be configured to
require either a User password or a User Token to register an application. The
following is a sample registration endpoint for mobile clients and mobile applications:
https:// host : port /idaas_rest/rest/mobileservice1/register
Using Mobile and Social Services
48-20 Administrator's Guide for Oracle Access Management
When registering with the Mobile and Social server, client applications using either the
Java Client SDK or the REST API must present valid credentials to the server using
one or more of the following schemes:
■HTTP Basic Authentication
■User ID and Password (UIDPASSWORD)
■OAM Token Authentication
Client applications using the Android or iOS SDK will acquire a Client Registration
Handle which uses the UIDPASSWORD authentication scheme to secure registration.
48.4.2 Exchanging Credentials
The Android, iOS, and Java SDKs will send the tokens, credentials, and other data
required by the Mobile and Social server. Table 48–4 describes the tokens required and
returned based on the client device or application.
Note: For a detailed look at the credentials, see “Mobile and Social
Services REST Reference: Authentication and Authorization” in the
“Sending Mobile and Social REST Calls With cURL” chapter of the
Oracle Fusion Middleware Developer's Guide for Oracle Access
Management.
Table 48–4 Token Requirements for the Mobile and Social Server
Device or App Type
Seeking to Register
Token(s), Credentials, and/or Data
Required by the Mobile and Social
Server Type of Token Returned
Non-Mobile Device
(Unregistered)
An ID and password associated with
a client application sent over
HTTPS.
Client Token
Mobile SSO Agent App ■A user ID and password sent
over HTTPS.
■Device profile data for the
Mobile Device.
■The name of the application
(that is, the Client ID).
Note - An Administrator must
also add the name of the mobile
SSO Agent to a Service Domain.
Client Registration
Handle
Using Mobile and Social Services
Understanding Mobile and Social 48-21
48.4.3 Protecting User Profile Services And Authorization Services
You can choose to protect User Profile Services and Authorization Services as follows
when configuring a Mobile and Social Services Service Domain.
User Profile Services - Configure User Profile Services security by making the
following selections for the Service Profile:
■Choose the Authentication Service Provider (OAMAuthentication,
MobileOAMAuthentication, JWTAuthentication, Mobile JWT Authentication,
Social Identity Authentication, and so on)
■Protect the service by requiring a “Secured Application” security token and a
“Secured User” security token
■Set the “Allow Read” and “Allow Write” options
Authorization Services - Configure Authorization Services security by making the
following selections for the Service Profile:
■Choose the Authentication Service Provider (OAMAuthentication,
MobileOAMAuthentication, JWTAuthentication, Mobile JWT Authentication,
Social Identity Authentication, and so on)
■Protect the service by requiring a “Secured Application” security token and a
“Secured User” security token.
48.4.4 Using Mobile and Social Services with Oracle Access Manager
Developers can quickly create applications that access resources protected by either
Oracle Access Management Access Manager, or the 10g or 11gR1 PS1 (11.1.1.5)
Mobile SSO Client App
(For example, a business
application that uses the
Mobile SSO Agent App to
register with Mobile and
Social.)
■One of the following:
A user ID and password sent to
the Mobile and Social server
over HTTPS.
- or -
A User Token.
■Device profile data for the
Mobile Device.
■The name of the application
(that is, the Client ID).
Note - An Administrator must
also add the name of the mobile
SSO Client application to a
Service Domain.
■The
oaam.device
handle (if
Mobile and Social is integrated
with OAAM).
■Mobile SSO Client Registration
Handle (previously obtained for
the SSO agent), if the SSO Client
application tries to register
through the SSO agent
application.
Client Registration
Handle
Table 48–4 (Cont.) Token Requirements for the Mobile and Social Server
Device or App Type
Seeking to Register
Token(s), Credentials, and/or Data
Required by the Mobile and Social
Server Type of Token Returned
Understanding Social Identity
48-22 Administrator's Guide for Oracle Access Management
versions of Oracle Access Manager. The Mobile and Social SDK handles authentication
programatically after it collects user credentials using the credential collection
interface. The SDK then uses the Mobile and Social REST interfaces to authenticate the
user with the token service configured for the application. For more information about
the Mobile and Social Services' authentication flow with Access Manager, see
Section 48.3.1, "Registering a Mobile Device With User Authentication."
48.4.5 Using Mobile and Social Services with Oracle Adaptive Access Manager
Services
Oracle Adaptive Access Manager (OAAM) can be used to make runtime
authentication decisions, such as blocking authentication if the user is authenticating
from an unauthorized country or location. The following functionality is also
supported.
■Multi-part login flows - for example, OAAM can challenge the user with
knowledge-based authentication questions, or require the user to authenticate
using one-time password (OTP) functionality if OAAM detects a risky or unusual
usage pattern (using the device at unusual hours or if the user is geographically
distant from the place where authentication last took place).
■Check device attributes (such as the MAC Address assigned to a device) and
verify that the device is not jail broken. Based on device attributes, OAAM can
allow or deny access.
■Device-selective wipeouts are also an option when using OAAM together with
Mobile and Social.
■Based on registered device info, OAAM can white-list or black-list specific devices.
For more information about using Mobile and Social with OAAM, see Section 49.9.2,
"Configuring Mobile and Social Services for Oracle Adaptive Access Manager."
48.5 Understanding Social Identity
Social Identity lets Mobile and Social serve as the relying party (RP) when interacting
with cloud-based Identity Authentication and Authorization Services, such as Google,
Yahoo, Facebook, Twitter, Windows Live, Foursquare and/or LinkedIn. Allowing
users to log in to a protected resource using their credentials from a trusted Identity
Provider is a convenience for the user. By deploying Mobile and Social, you can
provide users with a convenient multiple log-in option without the need to implement
each Provider individually. Users can use their credentials from cloud-based identity
services to log in to any of the following application types.
■Web applications that run on Java-compliant application servers. To add Social Identity
functionality to a Web application, a developer connects the Web application to the
Mobile and Social server using the Social Identity Client SDK. For details, see the
"Developing Applications Using the Social Identity Client SDK" chapter in the
Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
■Applications protected by either Access Manager, or the 10g or 11.1.1.5 versions of
Oracle Access Manager. Applications protected by either the Access Manager
service in the Oracle Access Management product, or the 10g or 11gR1 PS1
versions of Oracle Access Manager can be configured to work with Social Identity
without using an SDK. For details about the authentication flow, see Section 48.6.4,
"Authenticating a User With Access Manager and Social Identity."
■Mobile applications running Android or iOS. Mobile applications running Android or
iOS can be configured to authenticate with an Social Identity Provider. To connect
Understanding Social Identity Processes
Understanding Mobile and Social 48-23
to the Mobile and Social server, Android and iOS applications use the Mobile and
Social Services SDKs for those platforms. A separate SDK is not required.
Social Identity provides services for Identity Providers that support the following
standards:
■OpenID version 2.0
■OpenID Simple Registration Extension 1.0
■Open ID Attribute Exchange Extension 1.0
■OpenID Provider Authentication Policy Extension 1.0
■OAuth 1.0 and 2.0
Native support for the Identity Providers listed in Table 48–5 is provided by Mobile
and Social after installation.
Java programmers can add relying party support for additional OpenID and OAuth
Identity Providers by implementing a Java interface and using the Mobile and Social
console to add the Java class to the Mobile and Social deployment. For more
information, see the “Extending the Capabilities of the Mobile and Social Server”
chapter in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
48.6 Understanding Social Identity Processes
The following scenario documents the basic authentication process when using Social
Identity.
1. A user requests access to a protected resource and is redirected to Mobile and
Social.
2. Mobile and Social (RP) asks the user if they would like to log in using their
credentials from, for example, Google (the Identity Provider).
3. Mobile and Social redirects the user to a Google login page where a user name and
password is entered.
4. Google verifies the credentials and redirects the user back to Mobile and Social. At
the same time the Identity Provider returns identity attributes to Mobile and Social
based on its configuration.
If the user does not have an account with your organization, the user can be
prompted to register for one; the registration form will be prepopulated with the
information that the Identity Provider returns.
Table 48–5 Identity Providers That Mobile and Social Natively Supports
Identity Provider Supported Protocol
Facebook OAuth 2.0
Google OAuth 2.0
LinkedIn OAuth 2.0
Twitter OAuth 2.0
Yahoo OpenID 2.0
Foursquare OAuth 2.0
Windows Live OAuth 2.0
Understanding Social Identity Processes
48-24 Administrator's Guide for Oracle Access Management
Additional scenarios are documented in these sections.
■Authenticating a Returning User With a Local Account
■Authenticating a New User With No Local Account
■Using OAuth For Access Token Retrieval
■Authenticating a User With Access Manager and Social Identity
■Authenticating a User Locally
48.6.1 Authenticating a Returning User With a Local Account
This scenario describes the authentication flow between the User, the Mobile and
Social server (the relying party), the Identity Provider, and the local user
authentication service (represented by Local Auth and ID Repository in the diagram).
In this scenario, the local Identity repository determines that the user already has a
local account. Consequently Mobile and Social does not prompt to create one.
Figure 48–8, following the text, illustrates the process.
1. The user opens a URL for a protected resource in a web browser and the Mobile
and Social server presents the user with a login page and a menu of Identity
Providers (Google, Yahoo, Facebook, Windows Live, Foursquare, Twitter, or
LinkedIn) from which to choose.
2. The user chooses an Identity Provider.
3. The Mobile and Social server redirects the user to the selected Identity Provider
and a login page is displayed.
4. The user enters a user name and password and, upon authentication, the Identity
Provider sends the Mobile and Social server an authentication assertion.
5. The Mobile and Social server checks with the Identity repository to see if the user
has a local account.
The Identity repository could be a directory server, a database, Oracle Identity
Manager, or similar. The user is determined to be a User with a local account:
■If a mobile application or a directly-integrated Web application is
authenticating with Mobile and Social, the Mobile and Social server sends an
authentication assertion to the user's browser.
■If an application protected by Access Manger is authenticating, Access
Manager creates the session for the user only if the user has a local account.
(Newly registered users count as local account holders.)
6. The user's browser sends the authentication assertion sent by Mobile and Social to
the protected resource's Access Management Service.
7. The Access Management Service carries out additional authentication steps as
needed.
8. The Access Management Service allows the user access to the protected resource.
Note: In the case of Access Manager, a user MUST register locally,
otherwise access is not given. If not using Access Manager, the user is
redirected to the protected resource and allowed access even if they
don't register. For details, see Section 48.7.1, "Using Social Identity
With Oracle Access Manager."
Understanding Social Identity Processes
Understanding Mobile and Social 48-25
Figure 48–8 Authenticating a Returning User with a Local Account
48.6.2 Authenticating a New User With No Local Account
This scenario describes the authentication flow between the User, the Mobile and
Social server (the relying party), the Identity Provider, and the local User
authentication service (represented by Local Auth and ID Repository in the diagram).
In this scenario, the User does not have a local account so Mobile and Social prompts
to create one. Figure 48–9, following the text, illustrates the process.
1. The user opens a URL for a protected resource in a web browser and the Mobile
and Social server (RP in the diagram) presents the user with a login page and a
menu of Identity Providers (Google, Yahoo, Facebook, Twitter, or LinkedIn) from
which to choose.
2. The user chooses an Identity Provider.
3. The Mobile and Social server redirects the user to the selected Identity Provider
which displays a login page.
4. The user enters a user name and password and, upon user authentication, the
Identity Provider sends the Mobile and Social server an authentication assertion.
5. The Mobile and Social server checks with the Identity repository to see if the User
has a local account.
The Identity repository could be a directory server, a database, Oracle Identity
Manager or similar. The user is determined to be a user who does not have a local
account. Mobile and Social proceeds as follows:
AAA/Idm or App
User Browser
AuthUI
Mobile and
Social
Server
Local
Auth ID Repository Local
Reg IDP
IDP Select
New or Existing User?
SSO + Attr Protocol (Eg: OPENID)
POST <Assertion>
Existing User: Authentication
AuthUI
New Session
Existing user:
AuthN flow
Understanding Social Identity Processes
48-26 Administrator's Guide for Oracle Access Management
■If the Identity Provider uses the Open ID protocol, the Mobile and Social
server retrieves the user's profile attributes by processing data in the
previously obtained authentication assertion.
■If the Identity Provider uses the OAuth protocol, the Mobile and Social server
makes a separate HTTP call to the Identity Provider with the previously
obtained Access Token to retrieve the user's profile attributes.
6. The Mobile and Social server sends a new user registration form to the user's
browser.
The registration form is pre-populated with the user profile attributes sent by the
Identity Provider in the previous step.
7. The user completes the registration form and sends it to which interfaces with the
user registry (either a directory server or Oracle Identity Manager) to create the
account.
In cases where an Access Token is retrieved from the Identity Provider, the Access
Token is also returned to the client application by way of Mobile and Social.
8. The Access Management Service for the client application carries out additional
authentication steps as needed.
9. The Access Management Service allows the user access to the protected resource.
Understanding Social Identity Processes
Understanding Mobile and Social 48-27
Figure 48–9 Authenticating a New User with No Local Account
48.6.3 Using OAuth For Access Token Retrieval
This section provides supplemental detail about the OAuth authentication and Access
Token retrieval flow between the User, the Mobile and Social server (the relying party),
and an OAuth Identity Provider. (Facebook, Foursquare, and Windows Live use the
OAuth 2.0 protocol, and LinkedIn and Twitter use the OAuth 1.0 protocol.) In this
scenario, the server interfaces with the OAuth Identity Provider to get an
authorization code and Access Token to access a resource protected by the OAuth
Identity Provider. The Client application in this scenario could be either a Web
application running on a Java-compliant application server, or a mobile application.
Figure 48–10, following the text, illustrates the process.
1. The user opens the client application which returns a protected web page to the
user's browser.
2. The user attempts to open the protected resource on the client application.
3. The client application asks the Mobile and Social server for an Access Token so
that the user can access the protected resource.
If Mobile and Social has the valid Access Token in its cache, it will forward the
Access Token to the client application and the authentication scenario would skip
AAA/IdM or App
User Browser
AuthUI [C1]
Mobile and
Social
Server
Local
Auth ID Repository Local
Reg IDP
IDP Select
New or Existing User
SSO + Attr Protocol (Eg: OPENID)
New User: Retrieve user attrs
New User: POST <Assertion>
New User: Registration
AuthUI
Registration Complete
New Session
New User:
Initiate REG flow
Understanding Social Identity Processes
48-28 Administrator's Guide for Oracle Access Management
to step 10. This flow assumes Mobile and Social does not have the Access Token in
its local cache.
4. Because the Access Token is not in its local cache, on behalf of the user, Mobile and
Social initiates an authorization request (utilizing HTTP headers to embed an
OAuth Client ID, scope information, and a redirect URL) with the OAuth Identity
Provider.
5. The OAuth Identity Provider displays a login page.
6. The user enters a user name and password into the OAuth Identity Provider login
page and gives consent to the Identity Provider to provide the user's profile
attributes to the Mobile and Social server (and, by extension, the client
application).
7. The OAuth Identity Provider sends an authorization code to the Mobile and Social
server.
8. The Mobile and Social server sends an Access Token request to the OAuth Identity
Provider.
Included in the request is the authorization code received in the previous step and
the OAuth Client ID and client credential.
9. The OAuth Identity Provider returns an Access Token to the Mobile and Social
server.
10. The Mobile and Social server caches the Access Token (with the User ID and the
OAuth Client ID) and forwards the Access Token to the client application.
11. The client application uses the Access Token to access the protected resource and
returns the protected page to the user's browser.
Understanding Social Identity Processes
Understanding Mobile and Social 48-29
Figure 48–10 Authenticating a User With an OAuth Identity Provider
48.6.4 Authenticating a User With Access Manager and Social Identity
This scenario describes the authentication process between the User, Access Manager,
the Mobile and Social server (the relying party), and the Identity Provider. Note that
the user must either have a local account or must register for a local account when
prompted; otherwise Access Manager will not let the user access the protected
resource and the User will be redirected to the login page. Figure 48–11, following the
text, illustrates the process.
1. The user attempts to open a protected resource on the client application.
2. The WebGate protecting the resource intercepts the access request.
AAA/Idm or App
User Browser
Mobile and
Social
Server
Client
App ID Repository Local
Reg OAuth SP
Client Apps UI to access
OAuth resource
User accesses
protected
resource
1
2
Get Access To ke n
for given scope
3
Persist Access Token with User ID, scope, and return Access Token
to client URL.
9
Access the resource using the Access To ke n
Access Token not found.
Get authorization code with Mobile and Social ID, scope, and redirect URL
4
OAuth Provider returns authorization code to Mobile and Social
User authenticates with the Provider and gives consent to allow resources to be accessed by the client
6
Get Access Token using the authorization code, OAuth Client ID and
Credential used by the Mobile and Social Server.
7
OAuth Provider returns token to Mobile and Social
8
5.1
10
5.2
Understanding Social Identity Processes
48-30 Administrator's Guide for Oracle Access Management
3. Access Manager identifies the authentication policy protecting the resource and
redirects the user to a login page provided by the Mobile and Social server.
4. The login page presents a menu of Social Identity Providers.
5. The user chooses an OpenID Identity Provider and Access Manager redirects the
user's browser to the Mobile and Social server, which redirects the user's browser
to the login page for the selected Social Identity Provider (Google, Facebook,
Twitter, and so on).
6. The user types a user name and password into the Social Identity Provider's login
page.
The Identity Provider completes the authentication process and requests the User's
consent to share Identity information (if applicable).
7. When authentication is complete, the Social Identity Provider redirects the
browser back to the Mobile and Social server.
After further processing of Identity assertions supplied by the Identity Provider
and after retrieving user identity information, the Mobile and Social server
redirects the user's browser to Access Manager. This time HTTP headers in the
page request provide Access Manager with the user's authentication status and
attributes.
8. Access Manager creates a user session and redirects the user to the protected
resource.
Understanding Social Identity Processes
Understanding Mobile and Social 48-31
Figure 48–11 Authenticating a User with Access Manager
48.6.5 Authenticating a User Locally
This scenario describes the authentication process if the user chooses not to
authenticate through a Social Identity Provider but instead authenticates using a local
account. Figure 48–12, following the text, illustrates the process.
1. The user opens a URL for a protected resource in a web browser and the Mobile
and Social server presents the user with a login page and a menu of Identity
Providers from which to choose.
2. The user chooses to use local authentication and types a user name and password
at the login page.
3. The client application's Access Management Service carries out additional
authentication steps as needed.
■If using the JWT Token Service, a User Token may be created.
■The OAM Token Service does not return tokens during the local
authentication flow.
4. The Access Management Service creates a session for the user and the user
accesses the protected resource.
User
Browser
Protected
Application WebGate Credential
Collector
Access
Manager
Mobile and
Social
Social
Identity
Provider
User tries to access
protected application
1
WebGate Intercepts
and redirects to Access Manager
2
Access Manager Identifies the authentication policy and redirects for Credential Collection
3
Credential collector presents Identity Provider Login Selection Page.
4
Access Manager reads the selection and redirect to Mobile and Social as per the contract
5
Mobile and Social redirects to the Access Manager Auth scheme with status and user attributes
7
Access Manager creates a session and completes the access protection
8
Mobile and Social
completes the
authentication process
6
Using Social Identity
48-32 Administrator's Guide for Oracle Access Management
Figure 48–12 Authenticating a User Locally
48.7 Using Social Identity
The following sections contain details about how you might use the Social Identity.
For examples of ways to integrate Social Identity, see Section 48.6, "Understanding
Social Identity Processes."
■Using Social Identity With Oracle Access Manager
■Using Social Identity With Mobile and Social Services
■Using the Social Identity SDK
48.7.1 Using Social Identity With Oracle Access Manager
Users can choose to log in to Access Manager protected resources using credentials
from a Social Identity Provider if you integrate Social Identity with Access Manager. In
this arrangement, users enter their Identity Provider credentials. Access Manager
forwards the User's login request to Mobile and Social, which completes the
authentication process with the Identity Provider in the background. Mobile and
Social (the relying party) redirects the User to Access Manager. At the same time,
Mobile and Social provides Access Manager with the User's authentication status and
User attributes, which were sent by the Identity Provider. For more information about
how Access Manager uses Social Identity for authentication, see Section 48.6.4,
"Authenticating a User With Access Manager and Social Identity."
48.7.2 Using Social Identity With Mobile and Social Services
You can configure Mobile and Social Services to allow mobile devices to authenticate
using Social Identity. After an Identity Provider verifies a user's credentials, Social
Identity can prompt the user to create an account with your organization. To
pre-populate the new user registration form with data returned from the Identity
Provider, refer to the "Developing Applications Using the Social Identity Client SDK"
chapter in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
AAA/Idm or App
User Browser
AuthUI
Mobile and
Social
Server
Local
Auth ID Repository Local
Reg IDP
Local Login
Select
Existing User: authentication
AuthUI
New Session
Using Social Identity
Understanding Mobile and Social 48-33
48.7.3 Using the Social Identity SDK
Developers who maintain Java-compliant Web applications can add Social Identity
functionality to their Web offering using the Mobile and Social Social Identity SDK.
This SDK is available for Java-powered Web applications only. For information about
the SDK, see the "Developing Applications Using the Social Identity Client SDK"
chapter in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management.
Using Social Identity
48-34 Administrator's Guide for Oracle Access Management
49
Configuring Mobile and Social Services 49-1
49
Configuring Mobile and Social Services
[31]
Mobile and Social provides a graphical user interface for configuring Mobile and
Social Services. (Prior to version 11.1.2.3, Mobile and Social Services was named
Mobile Services.) This chapter describes how to use the Oracle Access Management
Console to configure Mobile and Social Services and contains the following topics.
■Opening the Mobile and Social Services Configuration Page
■Understanding Mobile and Social Services Configuration
■Defining Service Providers
■Defining Service Profiles
■Defining Security Handler Plug-ins
■Defining Application Profiles
■Defining Service Domains
■Using the Jailbreak Detection Policy
■Configuring Mobile and Social Services with Other Oracle Products
49.1 Opening the Mobile and Social Services Configuration Page
Follow these steps to open the Mobile and Social Services configuration page in the
Oracle Access Management Console.
1. In the Oracle Access Management Console, click Mobile Security at the top of the
window.
2. Click Mobile and Social Services.
Note: Mobile and Social Services can be configured from the
command line using WLST. For more information about the Mobile
and Social WLST commands, see the Oracle Fusion Middleware
WebLogic Scripting Tool Command Reference.
WARNING: Only use tools provided with OAM Mobile and Social
to change passwords, security credentials, or keys. Specifically, do
not use Oracle Enterprise Manager (EM) for this purpose, because it
is not compatible with the Mobile and Social credential store.
Understanding Mobile and Social Services Configuration
49-2 Administrator's Guide for Oracle Access Management
49.2 Understanding Mobile and Social Services Configuration
The Welcome to Mobile and Social - Mobile and Social Services configuration page is
divided into separate panels that can be expanded and collapsed by clicking the arrow
button in the top left corner of the panel. The following sections contain more
information about the Mobile and Social Services panels.
■Understanding Service Providers
■Understanding Service Profiles
■Understanding Security Handler Plug-ins
■Understanding Application Profiles
■Understanding Service Domains
49.2.1 Understanding Service Providers
A Service Provider is defined for each back-end service that you are making available
to client applications. By configuring the back-end service as a Service Provider, the
Mobile and Social server knows how to communicate with it. You can configure a
back-end service as one of the following Service Provider types.
■Authentication Service Provider - Interfaces with an Identity Provider so that the
back-end service can authenticate users, mobile devices, client applications, access
permissions, and issue authentication tokens accordingly. Mobile and Social
supports Access Manager and JSON Web Tokens (JWT) with their own Service
Provider and Service Profile configuration objects. Further, mobile client
authentication and non-mobile client authentication is managed separately so each
token type has a separate mobile and non-mobile Service Provider and Service
Profile. The following pre-configured Authentication Service Providers are
available for typical deployments.
–OAMAuthentication - Oracle Access Manager Authentication Token Service
Provider
–MobileOAMAuthentication - Mobile Oracle Access Manager Authentication
Token Service Provider
–JWTAuthentication - JSON Web Token Authentication Service Provider
–MobileJWTAuthentication - Mobile JSON Web Token Authentication Service
Provider
–JWTOAMAuthentication - Allows lightweight, long-duration JWT tokens to
be exchanged for OAM tokens. OAM tokens provide SSO and OAM resource
access to clients. This provider allows users using non-mobile applications to
get a new OAM token without having to provide credentials if they have a
valid, long-duration JWT token.
–MobileJWTOAMAuthentication - Allows lightweight, long-duration JWT
tokens to be exchanged for OAM tokens. OAM tokens provide SSO and OAM
resource access to clients. This provider allows users using mobile applications
Note: Mobile and Social includes pre-configured objects to support
typical deployment scenarios. These objects are designed to help you
get Mobile and Social up and running with only minor modifications
required. Each section lists the pre-configured objects available after
installation.
Understanding Mobile and Social Services Configuration
Configuring Mobile and Social Services 49-3
to get a new OAM token without having to provide credentials if they have a
valid, long-duration JWT token.
–InternetIdentityAuthentication -The Social Identity JSON Web Token
Authentication Service Provider provides pre-configured support for apps
using Mobile and Social Services to accept an authentication result from the
Mobile and Social Social Identity (as described in Section 48.5, "Understanding
Social Identity").
Also see Section 49.3.1, "Defining, Modifying or Deleting an Authentication
Service Provider" for instructions on how to create a custom Authentication
Service Provider.
■Authorization Service Provider - Interfaces with a back-end Identity Provider that
makes authorization (access) decisions. The pre-configured OAMAuthorization
Authorization Service Provider is provided for typical deployments. See
Section 49.3.2, "Defining, Modifying or Deleting an Authorization Service
Provider" for instructions on how to create a custom Authorization Service
Provider.
■User Profile Service Provider - Interfaces with a directory server to lookup and
update User Profile records. The pre-configured User Profile Service Provider is
provided for typical deployments. See Section 49.3.3, "Defining, Modifying or
Deleting a User Profile Service Provider" for instructions on how to create a
custom User Profile Service Provider.
49.2.2 Understanding Service Profiles
After defining a Service Provider, you configure one or more Service Profiles for it. A
Service Profile is a logical envelope that defines a Service Endpoint URL for a Service
Provider on the Mobile and Social server. You can create multiple Service Profiles for a
Service Provider to define different token capabilities and service endpoints. Each
Service Provider instance requires at least one corresponding Service Profile. Mobile
and Social includes a pre-configured Service Profile for each pre-configured Service
Provider configuration object documented in Section 49.2.1, "Understanding Service
Providers."
49.2.3 Understanding Security Handler Plug-ins
A Security Handler Plug-in enhances security by consulting additional logic for trust
and risk analysis. (Such additional logic may deny certain risky operations.) The
Security Handler Plug-in applies the logic during Authentication Service operations,
including client application registration. Using a Security Handler Plug-in is optional.
The Security Handler Plug-ins provided with this version of the software are
optimized for mobile applications. If used, only apply it to mobile-related Service
Domains, its authentication services, and client applications. Do not use a Security
Handler Plug-in with a non-mobile application.
Mobile and Social invokes the Security Handler Plug-in during sensitive security
operations (such as authentication) as well as during operations that involve token
acquisition. Mobile and Social includes the following preconfigured Security Handler
Plug-ins:
■The
OAAMSecurityHandlerPlugin
enables the sophisticated device registration and
risk-based strong authentication logic available in Oracle Adaptive Access
Manager.
■The
Default
Security Handler Plug-in offers more limited device registration
logic.
Defining Service Providers
49-4 Administrator's Guide for Oracle Access Management
49.2.4 Understanding Application Profiles
An Application Profile describes the configuration and security properties of the client
application that will consume services provided by the Service Provider. An
Application Profile is required either when mobile applications are used, or when a
non-mobile application is used with a service that does not have secured application
protection. Attributes defined include an Application Profile name, a short description
of the application, a list of name-value attribute pairs, and its mobile configuration
settings. (Mobile configuration settings include options such as the maximum duration
in minutes that the Profile can be cached, the number of allowable authentication
retries, and whether offline authentication is allowed.) You can also choose which
mobile device attributes (such as
phonecarriername
,
phonenumber
,
osversion
, and so
on) are required for the application. A single Application Profile can be assigned to
multiple Service Domains.
49.2.5 Understanding Service Domains
A Service Domain is a logical grouping that serves to associate a Service Profile with an
Application Profile and (optionally) a Security Handler Plug-in. A Service Domain
specifies how applications are allowed to access services in Mobile and Social.
Typically an organization should have one Service Domain for managing mobile apps,
and a separate Service Domain for managing non-mobile apps. When creating a
Service Domain you:
■Decide whether the Service Domain is for managing mobile applications or
desktop applications.
■Choose an authentication scheme and, optionally, a Security Handler Plug-in for
the Service Domain.
■Add one or more Mobile SSO Agents and configure which agents have priority
over the others.
■Add one or more applications to the Service Domain and configure which can use
a Mobile SSO Agent.
■Choose at least one Service Profile for the Service Domain.
■Configure security settings to protect the Service Domain services.
Mobile and Social includes the following pre-configured Service Domains:
■The Default (Service Domain) is pre-configured for non-mobile applications.
■The Mobile Service Domain is pre-configured for mobile applications.
Use one of these Service Domains as a template to create your own, or modify them to
suit the needs of your organization. Only mobile authentication Service Profiles can be
added to a mobile Service Domain.
49.3 Defining Service Providers
A Service Provider is defined for each back-end service that is available to client
applications. This configures how the Mobile and Social server will interface with the
defined back-end Service Provider. Depending on the services that you are providing,
you may only need to configure one or two of the available Service Provider options.
For example, if you are only providing authentication services, you do not need to
define the User Profile Service Provider or Authorization Service Provider. This section
includes the following procedures:
■Defining, Modifying or Deleting an Authentication Service Provider
Defining Service Providers
Configuring Mobile and Social Services 49-5
■Defining, Modifying or Deleting an Authorization Service Provider
■Defining, Modifying or Deleting a User Profile Service Provider
49.3.1 Defining, Modifying or Deleting an Authentication Service Provider
An Authentication Service Provider allows Mobile and Social to authenticate users, client
applications, and access permissions using a back-end Authentication Service by way
of a token exchange. Upon successful authentication and verification, a token may be
returned to the client application. The following authentication types are supported.
■When installed with Access Manager, Mobile and Social supports JSON Web
Tokens (JWT) and Access Manager (OAM) tokens.
■When installed without Access Manager, only the JSON Web Token (JWT) type is
supported.
The following sections contain more information regarding Authentication Service
Providers.
■Understanding the Pre-Configured Authentication Service Providers
■Understanding the JWT-OAM Token Authentication Service Provider
■Creating an Authentication Service Provider
■Editing or Deleting an Authentication Service Provider
■Requiring User Credentials to Exchange a JWT Token for an OAM Token
■Configuring OAM to use the JWT-OAM + PIN Token Service Provider
49.3.1.1 Understanding the Pre-Configured Authentication Service Providers
Mobile and Social provides pre-configured Authentication Service Providers for the
Authentication Services listed in Table 49–1.
For each token type (Access Manager and JWT), Mobile and Social provides separate
"out-of-the-box" mobile and non-mobile (or desktop) Service Provider configurations.
Separate configurations are provided so that you can optimize each to best meet the
needs of each access mode. Mobile devices must use a mobile Service Provider,
however, non-mobile devices can use either a mobile service provider or a non-mobile
service provider if correct input is provided.
Mobile Service Providers use Client Registration Handles to register mobile devices,
whereas non-mobile Service Providers use Client Tokens to authenticate non-mobile
devices. The Client Token capability in Mobile and Social can be disabled, but the
Client Registration Handle capability cannot.
Note: See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a Webgate.
Defining Service Providers
49-6 Administrator's Guide for Oracle Access Management
Table 49–1 Pre-configured Authentication Service Providers
Authentication
Service
Mobile and Social Service
Provider Name Description
Access Manager OAMAuthentication Provides pre-configured support for users using
desktop devices to authenticate using Access Manager.
This Service Provider can issue a Client Token, but it
cannot register mobile devices.
The following Java class implements this Service
Provider:
oracle.security.idaas.rest.provider.token.OAMSD
KTokenServiceProvider
Mobile Access Manager MobileOAMAuthentication Provides pre-configured support for users using mobile
devices to authenticate using Access Manager.
This Service Provider supports registering new devices
using a Client Registration Handle when the User
authenticates.
The following Java class implements this Service
Provider:
oracle.security.idaas.rest.provider.token.Mobil
eOAMTokenServiceProvider
JSON Web Token JWTAuthentication Provides pre-configured support for users using
non-mobile applications to authenticate using the JSON
Web Token format. JSON Web Token is a compact
token format that is suitable for space-constrained
environments such as HTTP Authorization headers.
This Service Provider can issue a Client Token, but it
cannot register new devices using a Client Registration
Handle.
The following Java class implements this Service
Provider:
oracle.security.idaas.rest.provider.token.JWTTo
kenServiceProvider
Mobile JSON Web
Token
MobileJWTAuthentication Provides pre-configured support for users using mobile
devices to authenticate using the Mobile JSON Web
Token format.
This Service Provider supports registering new devices
using a Client Registration Handle.
The following Java class implements this Service
Provider:
oracle.security.idaas.rest.provider.token.Mobil
eJWTTokenServiceProvider
Defining Service Providers
Configuring Mobile and Social Services 49-7
49.3.1.2 Understanding the JWT-OAM Token Authentication Service Provider
The JWTOAMAuthentication and the MobileJWTOAMAuthentication Service
Provider types require further explanation. The JWT-OAM token provider lets mobile
and non-mobile clients use a JSON Web Token (JWT) to retrieve an OAM User token
and an OAM Master token. Depending on your deployment, you may want to have a
long-duration JWT token instead of one or more long-duration OAM tokens. A JWT
token is lightweight and makes an ideal token to hold for a long duration.
Using the JWT-OAM token exchange feature, your application authenticates the user
with a user name and password, then obtains a JWT token, an OAM user token, and
an OAM master token. You can configure the JWT token to have a very long duration
compared to the duration of OAM tokens. Once the OAM tokens expire, clients use
the still-valid long-duration JWT token to get OAM tokens again.
The presence of OAM tokens can provide mobile and non-mobile clients with access to
resources protected by Access Manager. Exchanging a JWT token for OAM tokens
benefits the user, who does not need to provide credentials to get new OAM tokens to
replace the expired tokens.
As an added security measure, Mobile and Social can require users to enter an
additional credential, such as a PIN, when using a JWT user token to get an OAM
token. For details, see Section 49.3.1.5, "Requiring User Credentials to Exchange a JWT
Token for an OAM Token."
JWT-OAM Token
Provider
JWTOAMAuthentication Allows lightweight, long-duration JWT tokens to be
exchanged for OAM tokens. OAM tokens provide SSO
and OAM resource access to clients. This provider
allows users using non-mobile applications to get a
new OAM token without having to provide credentials
if they have a valid, long-duration JWT token.
Mobile JWT-OAM
Token Provider
MobileJWTOAMAuthentication Allows lightweight, long-duration JWT tokens to be
exchanged for OAM tokens. OAM tokens provide SSO
and OAM resource access to clients. This provider
allows users using mobile applications to get a new
OAM token without having to provide credentials if
they have a valid, long-duration JWT token.
Social Identity Web
Token
InternetIdentityAuthentication Provides pre-configured support for apps using Mobile
and Social Services to accept an authentication result
from Social Identity (for example, Google, Facebook,
Twitter, and so on).
This Service Provider supports registering new devices
using a Client Registration Handle. After the User
authenticates with the Identity Provider, this Service
Provider issues a User Token to the requesting client
application. The User Token allows the User to obtain a
Client Registration Handle for the device.
This service uses the same Java class as the JSON Web
Token service, but it is configured with two additional
name-value attribute pairs.
The following Java class implements this Service
Provider:
oracle.security.idaas.rest.provider.token.JWTTo
kenServiceProvider
Table 49–1 (Cont.) Pre-configured Authentication Service Providers
Authentication
Service
Mobile and Social Service
Provider Name Description
Defining Service Providers
49-8 Administrator's Guide for Oracle Access Management
49.3.1.3 Creating an Authentication Service Provider
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Providers section and choose Create Authentication
Service Provider.
The Authentication Service Provider Configuration page displays.
3. Enter values for the Authentication Service Provider properties.
■Name - Type a unique name for this Authentication Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
■Service Provider Java Class - Type the name of the Java class that implements
this Authentication Service Provider.
4. Add or delete Authentication Service Provider Attributes and their values based
on either Table 49–2 (OAMAuthentication and the MobileOAMAuthentication
Service Provider types), Table 49–4 (JWTAuthentication and the
MobileJWTAuthentication Service Provider types), or Table 49–5 (JWT-OAM
Authentication Service Provider Default Attributes).
■Table 49–2 and Table 49–3 are specific to a Mobile and Social integration with
Access Manager. The values in Table 49–2 apply to both the
OAMAuthentication and the MobileOAMAuthentication Service Provider
types. The values in Table 49–3 configure the Webgate agent.
Note: If you created a custom Authentication Service Provider, use
the Attributes panel to further configure it. For the JWTAuthentication
and MobileJWTAuthentication Service Providers, custom attributes
are not used.
Table 49–2 Access Manager Authentication Service Provider Default Attributes
Name Default Value Notes
OAM_VERSION OAM_11G
Either
OAM_11G
or
OAM_10G
, depending on
the Oracle Access Manager version in
use.
DEBUG_VALUE 0
TRANSPORT_SECURITY OPEN
Specify the method for encrypting
messages between this AccessGate and
the Access Servers. The encryption
methods need to match. Valid values
include:
■
OPEN
■
SIMPLE
■
CERT
To update these settings, see
Section 49.9.1.1, "Configuring Mobile and
Social Services to Work With Access
Manager in Simple and Certificate
Mode."
Defining Service Providers
Configuring Mobile and Social Services 49-9
■Table 49–4 is specific to connecting a Mobile and Social server to JWT
Authentication Service Providers. The configuration values in this section
apply to both the JWTAuthentication and the MobileJWTAuthentication
Service Provider types.
OAM_SERVER_1 localhost:5575
Specify the host name and port number
of the primary Oracle Access
Management server.
OAM_SERVER_1_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_1. The default value is 4.
OAM_SERVER_2 oam_server_2:5575
Specify the host name and port number
of the secondary Oracle Access
Management server.
OAM_SERVER_2_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_2. The default value is 4.
IDContextEnabled true
Add this attribute with a value of
true
to
enable Identity Context, as described in
Section 55.5.7, "Configuring Oracle
Access Management Mobile and Social."
OAM_LOCAL_MODE true
Specifies if Mobile and Social should use
"local mode" or "remote mode" to
communicate with the OAM server. If the
attribute value is set to false, Mobile and
Social communicates with OAM over
TCP/IP. If set to true (or if this attribute
is undefined), Mobile and Social uses a
direct connection to communicate with
OAM.
Prior to version 11.1.2.3, Mobile and
Social only communicated with OAM
using TCP/IP (that is, remote mode).
Now communication defaults to local,
which is faster.
To configure Mobile and Social to
communicate with OAM 10g, set the
OAM_LOCAL_MODE
attribute to false.
Table 49–3 Webgate Agent for Authentication Service Provider Default Attributes
Name Default Value Notes
Webgate ID
Type the Webgate agent name that
identifies the Webgate instance to which
you are connecting.
Encrypted Password Copy and paste the
encrypted password for
the Webgate ID
Locate the
OAM-Domain-Directory
/output/
Profile-N
ame
/ObAccessClient.xml
file and copy
the encrypted password value located in
the element
ParamName=accessClientPasswd
.
Table 49–2 (Cont.) Access Manager Authentication Service Provider Default Attributes
Name Default Value Notes
Defining Service Providers
49-10 Administrator's Guide for Oracle Access Management
Table 49–5 is specific to the JWTOAMAuthentication and the
MobileJWTOAMAuthentication Service Provider types.
Table 49–4 JWT Authentication Service Provider Default Attributes
Name Default Value Notes
Identity Directory
Service Name
Select from the menu the
Directory Service that should be
used to verify the User.
The JWT token service verifies the
user with a directory server.
Crypto Scheme RS512
The cryptographic algorithm used
to sign the contents of the JWT
token. The default value is
RS512
.
(RSA encryption using SHA-512
hash algorithm.)
Validity Period 3600
The length of time in seconds that
the token is considered to be valid.
The default value is
3600
.
Relying Party Token Enabled
Select Enabled if the Service
Provider should accept security
tokens from an external issuer.
Issuer
If Relying Party Token is enabled,
specify the Security Token Service
issuer
Table 49–5 JWT-OAM Authentication Service Provider Default Attributes
Name Default Value Notes
OAM_VERSION OAM_11G
Either
OAM_11G
or
OAM_10G
, depending on
the Oracle Access Manager version in
use.
DEBUG_VALUE 0
TRANSPORT_SECURITY OPEN
Specify the method for encrypting
messages between this AccessGate and
the Access Servers. The encryption
methods need to match. Valid values
include:
■
OPEN
■
SIMPLE
■
CERT
OAM_SERVER_1 localhost:5575
Specify the host name and port number
of the primary Oracle Access
Management server.
OAM_SERVER_1_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_1. The default value is 4.
OAM_SERVER_2 oam_server_2:5575
Specify the host name and port number
of the secondary Oracle Access
Management server.
OAM_SERVER_2_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_2. The default value is 4.
Defining Service Providers
Configuring Mobile and Social Services 49-11
user.Authenticator
■Default value
for
JWTOAMAuthent
ication
provider:
oracle.securi
ty.idaas.rest
.provider.tok
en.OAMSDKToke
nServiceProvi
der
■Default value
for
MobileJWTOAMA
uthentication
provider:
oracle.securi
ty.idaas.rest
.provider.tok
en.JWTTokenSe
rviceProvider
Optional. Specify which of two available
authenticators to use for user
authentication.
■For OAM Authentication:
oracle.security.idaas.rest.prov
ider.token.OAMSDKTokenServicePr
ovider
■For IDS Authentication:
oracle.security.idaas.rest.prov
ider.token.JWTTokenServiceProvi
der
UserAuthenticationInput UIDPASSWORD
Specify how the client application should
authenticate the user. The only supported
value is
UIDPASSWORD
.
UserAuthenticationOutput USERTOKEN
Specify all possible token types that the
client application will receive if user
authentication is successful.
Configure this parameter with any
combination of the following:
■
USERTOKEN::JWTUT
■
USERTOKEN::OAMUT
■
USERTOKEN
::
OAMMT
JWTUT
specifies the JWT-type user token.
OAMUT
specifies the OAM-type user token.
OAMMT
specifies the OAM-type master
token.
If no value is supplied, all three token
types are assumed.
TokenExchangeInput JWT_UT+CRED
Specifies what is required to exchange a
JWT type user token for an OAM token.
Configure this parameter with one of the
following:
■
JWT_UT
■
JWT_UT+CRED
JWT_UT
specifies that a JWT type user
token is required to get OAM tokens.
JWT_UT+CRED
specifies that, in addition to
a JWT user token, an additional
credential such as a personal
identification number is required to get
OAM tokens.
If no value is supplied, the token
exchange feature is disabled.
Table 49–5 (Cont.) JWT-OAM Authentication Service Provider Default Attributes
Name Default Value Notes
Defining Service Providers
49-12 Administrator's Guide for Oracle Access Management
5. Click Create to create the Service Provider configuration object.
49.3.1.4 Editing or Deleting an Authentication Service Provider
To edit or delete an Authentication Service Provider, select the Service Provider in the
panel and click Edit or Delete on the panel's tool bar.
49.3.1.5 Requiring User Credentials to Exchange a JWT Token for an OAM Token
As an added security measure, Mobile and Social can require users to enter an
additional credential, such as a PIN, when using a JWT user token to get an OAM
token. To enable the user PIN requirement, specify the
JWT_UT+CRED
parameter as
described in Table 49–5 when configuring the
TokenExchangeInput
attribute.
To use this feature, the user PIN or other credential must be present in the user entry in
the directory server. Mobile and Social does not put restrictions on credential values; it
simply validates the credential value submitted by the user with the value present in
the user entry. For security reasons, user credentials should be saved as hashed
attributes. See Section 49.3.1.6, "Configuring OAM to use the JWT-OAM + PIN Token
Service Provider" for the steps required to get this configuration to work.
49.3.1.6 Configuring OAM to use the JWT-OAM + PIN Token Service Provider
1. Open your directory server and extend the LDAP Schema for the PIN Attribute.
After the LDAP schema change, you can add new users and modify existing users
to have a PIN value.
a. Create the PIN attribute. See Figure 49–1 for an example using Oracle
Directory Services Manager (ODSM) and Oracle Unified Directory (OUD).
TokenExchangeOutput USERTOKEN::OAMUT,
USERTOKEN::OAMMT
Configure this parameter with any
combination of the following:
■
USERTOKEN::OAMUT
■
USERTOKEN::OAMMT
OAMUT
specifies the OAM type user token.
OAMMT
specifies the OAM type master
token.
OAM_LOCAL_MODE true
Specifies if Mobile and Social should use
"local mode" or "remote mode" to
communicate with the OAM server. If the
attribute value is set to false, Mobile and
Social communicates with OAM over
TCP/IP. If set to true (or if this attribute
is undefined), Mobile and Social uses a
direct connection to communicate with
OAM.
Prior to version 11.1.2.3, Mobile and
Social only communicated with OAM
using TCP/IP (that is, remote mode).
Now communication defaults to local,
which is faster.
To configure Mobile and Social to
communicate with OAM 10g, set the
OAM_LOCAL_MODE
attribute to false.
Table 49–5 (Cont.) JWT-OAM Authentication Service Provider Default Attributes
Name Default Value Notes
Defining Service Providers
Configuring Mobile and Social Services 49-13
Figure 49–1 Using ODSM to create the PIN attribute in OUD
b. Create a PINPERSON object class. See Figure 49–2 for an example using
Oracle Directory Services Manager (ODSM).
Defining Service Providers
49-14 Administrator's Guide for Oracle Access Management
Figure 49–2 Using ODSM to create the pinperson object class
2. Using the OAM Console, create a new IdentityStore for the external LDAP server
that you extended to use the PIN attribute.
a. Log in to the OAM Console and click Configuration at the top of the window.
b. Click User Identity Stores.
c. Click the Create button to create a new IdentityStore in OAM ID Stores. See
Figure 49–3 for details.
Defining Service Providers
Configuring Mobile and Social Services 49-15
Figure 49–3 Using the OAM Console to create an IdentityStore
3. Add a new OAM authentication module for the new Identity Store.
a. In the OAM console, click Application Security at the top of the window.
b. Select Create Custom Authentication Module from the Create (+) drop-down
menu in the Plug-ins section.
c. On the General tab, type a Name--for example,
PINBasedUserPlugin
.
d. On the Steps tab, type the following values:
Step Name:
UI
Plug-in Name:
UserIdentificationPlugIn
Plug-in Parameters:
- KEY_LDAP_FILTER:
(&(uid={KEY_USERNAME})(pin={cred}))
-KEY_IDENTITY_STORE_REF:
OUDIdentityStore
(This data store has to be
added first to do this step.)
Defining Service Providers
49-16 Administrator's Guide for Oracle Access Management
-KEY_SEARCH_BASE_URL:
ou=users,dc=ngam,dc=oracle,dc=com
e. On the Steps Orchestration tab, choose UI from the Initial Step menu.
4. Add a new authentication scheme.
a. In the OAM console, click Application Security at the top of the window.
b. Select Create Authentication Scheme from the Create (+) drop-down menu in
the Access Manager section.
c. Complete the form:
Name:
PINBasedUserAuthNScheme
Authentication Level:
3
Challenge Method:
FORM
Authentication Module: Choose the authentication module you created in the
previous step--for example,
PINBasedUserPlugin
.
5. Change the authentication policy to use the new authentication scheme.
a. In the OAM console, click Application Security at the top of the window.
b. Click Application Domains in the Access Manager section.
c. FInd the IAM Suite domain and open the OICTokenExchangePolicy policy.
d. From the Authentication Scheme drop-down menu, choose
PINBasedUserAuthNScheme.
6. Configure the (Mobile) JWTOAMAuthenticationProvider.
a. In the OAM console, click Mobile Security at the top of the window.
b. Click Mobile and Social Services.
c. Open the MobileJWTOAMAuthentication service provider for editing.
d. From the Identity Directory Service Name drop-down menu, choose the
directory service that points to the IdentityStore you created in step 2.
e. If a desktop (or non-mobile) service is required, repeat steps a and b to
configure the JWTOAMAuthentication provider.
7. Create an application profile.
a. In the OAM console, click Mobile Security at the top of the window.
b. Click Mobile and Social Services.
c. In the Application Profiles section, click the Create button and create a new
application profile (for example,
mobileapp1
).
8. Update the MobileServiceDomain.
a. In the OAM console, click Mobile Security at the top of the window.
b. Click Mobile and Social Services.
c. In the Service Domains section, find the MobileServiceDomain domain and
open it for editing.
d. In the Application Profiles section (subtab), add the application profile you
created in the previous step (
mobileapp1
).
e. Click the Service Profiles subtab to open it and change the Authentication
Service to
MobileJWTOAMAuthentication
.
Defining Service Providers
Configuring Mobile and Social Services 49-17
49.3.2 Defining, Modifying or Deleting an Authorization Service Provider
An Authorization Service Provider allows a back-end Identity service to make
authorization decisions on behalf of a connected application. This section contains the
following topics about Authorization Service Providers.
■Creating an Authorization Service Provider
■Editing or Deleting an Authorization Service Provider
■Understanding the Pre-Configured Authorization Service Provider
49.3.2.1 Creating an Authorization Service Provider
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Providers section and choose Create Authorization
Service Provider.
The Authorization Service Provider Configuration page displays.
3. Enter values for the Authorization Service Provider properties.
■Name - Type a unique name for this Authorization Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
■Service Provider Java Class - Type the name of the Java class that implements
this Authorization Service Provider.
4. Add or delete Authorization Service Provider Attributes and their values based on
Table 49–6.
Table 49–6 Access Manager Authorization Service Provider Default Attributes
Name Value Notes
OAM_VERSION OAM_11G
Either
OAM_11G
or
OAM_10G
, depending on
the Oracle Access Manager version in
use.
DEBUG_VALUE 0
TRANSPORT_SECURITY OPEN
Specify the method for encrypting
messages between this AccessGate and
the Access Servers. The encryption
methods need to match. Valid values
include:
■
OPEN
■
SIMPLE
■
CERT
OAM_SERVER_1 localhost:5575
Specify the host name and port number
of the primary Oracle Access
Management server.
OAM_SERVER_1_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_1. The default value is 4.
OAM_SERVER_2 oam_server_2:5575
Specify the host name and port number
of the secondary Oracle Access
Management server.
Defining Service Providers
49-18 Administrator's Guide for Oracle Access Management
5. Configure the Webgate agent by creating a new agent or entering values for an
existing agent as per Table 49–7. The Webgate agent configuration values are
specific to the integration between Mobile and Social Services and Access
Manager.
6. Click Create to create the Service Provider configuration object.
49.3.2.2 Editing or Deleting an Authorization Service Provider
To edit or delete an Authorization Service Provider, select the Service Provider in the
panel and click Edit or Delete on the panel's tool bar.
49.3.2.3 Understanding the Pre-Configured Authorization Service Provider
Mobile and Social provides a pre-configured Authorization Service Provider for
Access Manager named the OAMAuthorization Authorization Service Provider. The
oracle.security.idaas.rest.provider.authorization.OAMSDKAuthZServiceProvid
er
Java class implements the pre-configured Authorization Service Provider.
49.3.3 Defining, Modifying or Deleting a User Profile Service Provider
A User Profile Service Provider allows an application to query and update a directory
server. Many LDAP compliant directory servers are supported including:
■Microsoft Active Directory
■Novell eDirectory
■Oracle Directory Server Enterprise Edition
■Oracle Internet Directory
■Oracle Unified Directory
■Oracle Virtual Directory (using the Oracle Internet Directory template)
■OpenLDAP
■IBM Tivoli Directory Server (using the OpenLDAP template)
OAM_SERVER_2_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_2. The default value is 4.
Table 49–7 Webgate Agent for Authorization Service Provider Default Attributes
Name Value Notes
Webgate ID
Type the Webgate agent name that
identifies the Webgate instance to which
you are connecting.
Encrypted Password Copy and paste the
encrypted password for
the Webgate ID
Locate the
OAM-Domain-Directory
/output/
Profile-N
ame
/ObAccessClient.xml
file and copy
the encrypted password value located in
the element
ParamName=accessClientPasswd
.
Table 49–6 (Cont.) Access Manager Authorization Service Provider Default Attributes
Name Value Notes
Defining Service Providers
Configuring Mobile and Social Services 49-19
■WebLogic Server Embedded LDAP
Mobile and Social includes a pre-configured User Profile Service Provider that your
organization can use, or you can create your own. Before you can create a User Profile
Service Provider you must first create an Identity Directory Service profile. The Identity
Directory Service (IDS) is a flexible service used by Access Manager as the means for
accessing multiple identity data stores. For more information about the Identity
Directory Service, see Section 5.3, "Managing the Identity Directory Service User
Identity Stores."
The following sections contain more information about User Profile Service Providers.
■Creating a User Profile Service Provider
■Editing or Deleting a User Profile Service Provider
■Understanding the Pre-Configured User Profile Service Provider
49.3.3.1 Creating a User Profile Service Provider
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Providers section and choose Create User Profile
Service Provider.
The Service Provider Configuration page displays.
3. Enter values for the User Profile Service Provider properties.
■Name - Type a unique name for this User Profile Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
4. Add or delete User Profile Service Provider Attributes and their values based on
Table 49–8.
Note: LDAP attribute names are generally not case sensitive but
when communicating with the Oracle Identity Governance
Framework (IGF), LDAP attribute names are case sensitive.
Table 49–8 User Profile Service Provider Default Attribute Names and Values
Name Value Notes
accessControl
false Supported values include
true
or
false
(enable/disable, respectively) depending
on whether the accessControl feature is to
be disabled or enabled.
adminGroup
cn=Administrators,ou=groups,
ou=myrealm,dc=base_domain
If accessControl is enabled, specify the
distinguished name (DN) of the
adminGroup to see if the User is in it.
selfEdit true
Supported values include
true
or
false
depending on if the User can edit his or
her profile for the accessControl feature.
This is also one of the accessControl
feature's configuration properties.
Defining Service Providers
49-20 Administrator's Guide for Oracle Access Management
5. In the Identity Directory Service section, choose from the Name menu the
Identity Directory Service profile to use with this User Profile Service Provider.
■To create an Identity Directory Service profile, see Section 5.3.2, "Creating an
Identity Directory Service Profile."
■If you choose either of the default Identity Directory Services (
userrole
or
idxuserrole
) you can't view or edit the configuration values in this section.
■If you choose an Identity Directory Service connection that you or another
administrator created, select the View option to view and edit additional
properties as documented in Section 49.3.3.2, "Editing or Deleting a User
Profile Service Provider."
6. Click Create to create the Service Provider configuration object.
49.3.3.2 Editing or Deleting a User Profile Service Provider
To edit or delete a User Profile Service Provider, select the Service Provider in the
panel and click Edit or Delete on the panel's tool bar. This section describes the
additional User Profile Service Provider Configuration properties for the Identity
Directory Service connection as they appear when editing a User Profile Service
Provider that you or another Administrator created.
Name - The name of this User Profile Service Provider.
Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Attributes
Add or delete User Profile Service Provider Attributes and their values based on
Table 49–8.
proxyAuth
- Supported values include
true
or
false
depending on if the proxyAuth feature is
enabled or disabled, respectively. This
attribute is required only if proxyAuth is
supported and the Administrator does
not want to use the proxyAuth feature.
This attribute is not included in a new
installation of Mobile and Social. An
Administrator can add this property.
Note: LDAP attribute names are generally not case sensitive but
when communicating with the Oracle Identity Governance
Framework (IGF), LDAP attribute names are case sensitive.
Table 49–9 User Profile Service Provider Default Attribute Names and Values
Name Default Value Notes
accessControl
false Supported values include
true
or
false
(enable/disable, respectively) depending
on whether the accessControl feature is to
be disabled or enabled.
Table 49–8 (Cont.) User Profile Service Provider Default Attribute Names and Values
Name Value Notes
Defining Service Providers
Configuring Mobile and Social Services 49-21
Identity Directory Service
Name - The Identity Directory Service profile that connects the User Profile Service
Provider to one or more directory servers. For more information about the Identity
Directory Service, see Section 5.3, "Managing the Identity Directory Service User
Identity Stores."
■If either of the default Identity Directory Services are selected (either
userrole
or
idxuserrole
) you cannot view or edit the configuration values.
■If an Identity Directory Service connection that you or another Administrator
created is selected, you can view and edit the configuration values as needed.
Relationship Configuration
Type the URI segment used to access the corresponding column in the Identity
Directory Service. Use Add to add a new relationship or Remove to remove a
configured relationship.
■Access URI - Type a URI segment that will be used to access a corresponding data
column in the Identity Directory service. For example, if
memberOf
is the Access
URI, then:
http://host:port/.../idX/memberOf
would be the URI to access related entities of an entity with ID
idX
.
■Identity Directory Service Relation - Choose the Directory Service relationship
that is to be accessed by the Access URI segment. You can configure relationships
on the Relationships tab in the Identity Directory Service configuration section
provided that the Identity Directory Service is not the pre-configured UserProfile
Identity Provider. (You cannot configure Identity Directory Service relationships
for the UserProfile Service Provider.)
■Entity URI Attribute - Type the JSON attribute name to be used in the URI
response sent from the Mobile and Social server. For example, if person-uri is the
specified entity URI attribute, the URI response would be as follows:
{ {"person-uri":uriY1, ...}, {"person-uri":uriY2, ...}, ... }
adminGroup cn=Administrators,ou=groups,
ou=myrealm,dc=base_domain
If accessControl is enabled, specify the
distinguished name (DN) of the
adminGroup to see if the User is in it.
selfEdit true
Supported values include
true
or
false
depending on if the User can edit his or
her profile for the accessControl feature.
This is also one of the accessControl
feature's configuration properties.
proxyAuth
true Supported values include
true
or
false
depending on if the proxyAuth feature is
enabled or disabled, respectively. This
attribute is required only if proxyAuth is
supported and the Administrator does
not want to use the proxyAuth feature.
This attribute is not included in a new
installation of Mobile and Social. An
Administrator can add this property.
Table 49–9 (Cont.) User Profile Service Provider Default Attribute Names and Values
Name Default Value Notes
Defining Service Profiles
49-22 Administrator's Guide for Oracle Access Management
where
uriY1
and
uriY2
are the direct URIs to access each of the related entities.
■Scope for Requesting Recursion - Use Scope attribute values with the scope
query parameter to retrieve a nested level of attributes in a relationship search. To
access related entities recursively, type the value to be used. The Mobile and Social
default configuration uses two scope attribute values:
toTop
and
all
. If the Scope
for Requesting Recursion value is the attribute value
all
, then the following
REST URI example is used to make the request:
http://host:port/.../idX/reports?scope=all
In this example, the URI returns the entities related to the entity with ID
idX
, as
well as all further related entities.
49.3.3.3 Understanding the Pre-Configured User Profile Service Provider
Mobile and Social provides a pre-configured User Profile Service Provider for
LDAP-compliant directory servers named UserProfile. This Service Provider allows
lookup and update tasks to be performed on directory objects using Mobile and Social.
49.4 Defining Service Profiles
A Service Profile defines a Service Endpoint URL for a Service Provider on the Mobile
and Social server. Each Service Provider instance requires at least one corresponding
Service Profile instance. You can create multiple Service Profiles for a single Service
Provider; each Service Profile will define different token capabilities and service
endpoints for the Service Provider.
Create one or more Service Profiles after creating the required Service Provider(s). This
section covers the following topics:
■Defining, Modifying and Deleting an Authentication Service Profile
■Defining, Modifying and Deleting an Authorization Service Profile
■Defining, Modifying and Deleting a User Profile Service Profile
49.4.1 Defining, Modifying and Deleting an Authentication Service Profile
The following sections contain information regarding Authentication Service Profiles.
■Creating an Authentication Service Profile
■Editing or Deleting an Authentication Service Profile
49.4.1.1 Creating an Authentication Service Profile
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Profiles section and choose Create Authentication
Service Profile.
Note: One Service Profile can be assigned to multiple Service
Domains. In general, mobile Service Profiles should be assigned to
mobile Service Domains, and non-mobile Service Profiles should be
assigned to non-mobile Service Domains. See Section 49.7, "Defining
Service Domains."
Defining Service Profiles
Configuring Mobile and Social Services 49-23
The Authentication Service Profile Configuration page displays.
3. Enter values for the Authentication Service Profile general properties.
4. Select an option under Token Support and URI Category Information to enable
support for the token type on the service, or clear the option box to disable
support for the token type on the service.
Token Support applies to Authentication Service Profiles only. The corresponding
uniform resource identifier (URI) is listed alongside each token type.
Table 49–10 Authentication Service Profile Default General Properties
Name Notes
Name Type a unique name for this Authentication Service Profile.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Service Type Shows the type of Service Profile that you are creating (either a
User Profile Service, an Authentication Service, or an
Authorization Service).The value is read-only.
Service Endpoint Create a unique uniform resource identifier (URI) address for this
service by typing a string in the box; for example,
localhost:5575
.
■If creating an Authentication Service Profile, the URI Category
Information section shows the URIs that will be created to
create, validate, manage, and delete the Profile's client, user,
and Access Tokens, as well as the "Client Registration Handle"
URI that is used to register devices.
■If creating an Authorization Service Profile, the URI Category
Information section shows the authorization URI category that
will be created on the Service.
■If creating a User Profile Service Profile, the URI Category
Information section shows the URI categories that will be
created on the Service (one URI to manage Users, and another
to manage Groups).
Service Provider Choose the Service Provider on which this Service Profile should be
based. The contents of this list are determined by the Service Type.
A Service Provider must be defined before you can create a
corresponding Service Profile.
Service Enabled Select the box to enable the service; clear the box to disable.
Table 49–11 Token Support and URI Category Information Default Properties
Name Notes
Client Registration
Handle
Required for mobile token services so that the client device can register
with the Mobile and Social server. The server issues a Client
Registration Handle after authenticating the user. When OAAM and its
Security Handler Plug-in is used in conjunction with a mobile
Authentication Service, the Plug-in can run fraud detection and risk
analysis policy checks, enhancing authenticity and the trust level of a
client. To add an Authentication Service Profile to a mobile Service
Domain, Client Registration Handle must be enabled. Client
Registration Handles are not used in non-mobile Service Domains.
Client Token Select to enable Client Tokens on the Service. A Client Token is a
security grant issued by the Mobile and Social server to prove that a
non-mobile device or client is authenticated. The server issues a Client
Token after authenticating the client based on a name and password or
other credentials. Client Tokens are optional in non-mobile Service
Domains. They are not used in mobile Service Domains.
Defining Service Profiles
49-24 Administrator's Guide for Oracle Access Management
5. Click Create to create the Service Profile configuration object.
49.4.1.2 Editing or Deleting an Authentication Service Profile
To edit or delete an Authentication Service Profile, select the Service Profile in the
panel and click Edit or Delete on the panel's tool bar.
49.4.2 Defining, Modifying and Deleting an Authorization Service Profile
The following sections contain information regarding Authentication Service Profiles.
■Creating an Authorization Service Profile
■Editing or Deleting an Authorization Service Profile
49.4.2.1 Creating an Authorization Service Profile
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Profiles section and choose Create Authorization
Service Profile.
The Authorization Service Profile Configuration page displays.
3. Enter values for the Authorization Service Profile general properties.
User Token Select to enable User Tokens on the Service. A User Token is a security
grant issued by the Mobile and Social server to prove that a user is
authenticated. A User Token can be used to request an Access Token.
Access Token Select to enable Access Tokens on the Service. An Access Token is a
security grant issued by the Mobile and Social server so that a client
application can access a specific protected resource. A client application
can get an Access Token by presenting a User Token, provided that the
user is authorized to access the resource.
Table 49–12 Authorization Service Profile Default General Properties
Name Notes
Name Type a unique name for this Authorization Service Profile.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Service Type Shows the type of Service Profile that you are creating (either a
User Profile Service, an Authentication Service, or an
Authorization Service).The value is read-only.
Table 49–11 (Cont.) Token Support and URI Category Information Default Properties
Name Notes
Defining Service Profiles
Configuring Mobile and Social Services 49-25
4. Click Create to create the Service Profile configuration object.
49.4.2.2 Editing or Deleting an Authorization Service Profile
To edit or delete an Authorization Service Profile, select the Service Profile in the panel
and click Edit or Delete on the panel's tool bar.
49.4.3 Defining, Modifying and Deleting a User Profile Service Profile
The following sections contain information regarding Authentication Service Profiles.
■Creating a User Profile Service Profile
■Editing or Deleting a User Profile Service Profile
49.4.3.1 Creating a User Profile Service Profile
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Profiles panel in the home area and choose Create
User Profile Service Profile.
The User Profile Service Profile Configuration page displays.
3. Enter values for the User Profile Service Profile general properties.
Service Endpoint Create a unique uniform resource identifier (URI) address for this
service by typing a string in the box; for example,
localhost:5575
.
■If creating an Authentication Service Profile, the URI Category
Information section shows the URIs that will be created to
create, validate, manage, and delete the Profile's client, user,
and Access Tokens, as well as the "Client Registration Handle"
URI that is used to register devices.
■If creating an Authorization Service Profile, the URI Category
Information section shows the authorization URI category that
will be created on the Service.
■If creating a User Profile Service Profile, the URI Category
Information section shows the URI categories that will be
created on the Service (one URI to manage Users, and another
to manage Groups).
Service Provider Choose the Service Provider on which this Service Profile should be
based. The contents of this list are determined by the Service Type.
A Service Provider must be defined before you can create a
corresponding Service Profile.
Service Enabled Select the box to enable the service; clear the box to disable.
Table 49–13 User Profile Service Profile Default General Properties
Name Notes
Name Type a unique name for this Authorization Service Profile.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Service Type Shows the type of Service Profile that you are creating (either a
User Profile Service, an Authentication Service, or an
Authorization Service).The value is read-only.
Table 49–12 (Cont.) Authorization Service Profile Default General Properties
Name Notes
Defining Security Handler Plug-ins
49-26 Administrator's Guide for Oracle Access Management
4. Click Create to create the Service Profile configuration object.
49.4.3.2 Editing or Deleting a User Profile Service Profile
To edit or delete a User Profile Service Profile, select the Service Profile in the panel
and click Edit or Delete on the panel's tool bar.
49.5 Defining Security Handler Plug-ins
A Security Handler Plug-in enhances security by consulting additional logic for trust
and risk analysis. Such additional logic may deny access based on certain risky
operations. Mobile authentication invokes the Security Handler Plug-in during
sensitive security operations; for example, during virtually all token acquisition
operations including client application registration.
Mobile and Social includes the following pre-configured Security Handler Plug-ins.
■
OAAMSecurityHandlerPlugin
enables sophisticated device and client application
registration logic as well as the advanced risk and fraud analysis logic found in
OAAM.
■
Default
offers very limited risk analysis logic.
The following sections contain information regarding defining Security Handler
Plug-ins.
■Creating a Security Handler Plug-in
■Editing or Deleting a Security Handler Plug-in
Service Endpoint Create a unique uniform resource identifier (URI) address for this
service by typing a string in the box; for example,
localhost:5575
.
■If creating an Authentication Service Profile, the URI Category
Information section shows the URIs that will be created to
create, validate, manage, and delete the Profile's client, user,
and Access Tokens, as well as the "Client Registration Handle"
URI that is used to register devices.
■If creating an Authorization Service Profile, the URI Category
Information section shows the authorization URI category that
will be created on the Service.
■If creating a User Profile Service Profile, the URI Category
Information section shows the URI categories that will be
created on the Service (one URI to manage Users, and another
to manage Groups).
Service Provider Choose the Service Provider on which this Service Profile should be
based. The contents of this list are determined by the Service Type.
A Service Provider must be defined before you can create a
corresponding Service Profile.
Service Enabled Select the box to enable the service; clear the box to disable.
Note: Security Plug-in usage is optional. If used, it should only be
applied to mobile-related Service Domains and its authentication
services and client applications.
Table 49–13 (Cont.) User Profile Service Profile Default General Properties
Name Notes
Defining Security Handler Plug-ins
Configuring Mobile and Social Services 49-27
■Device Fingerprinting and Device Profile Attributes
49.5.1 Creating a Security Handler Plug-in
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Security Handler Plug-ins section.
The Security Handler Plug-in Configuration page displays.
3. Enter values for the Security Handler Plug-in general properties.
4. Enter name-value pairs for the Security Handler Plug-in Attributes.
■For descriptions of the
OaamSecurityHandlerPlugin
attributes, see
Section 49.9.2.7.3, "Setting Up OTP E-Mail Integration."
■The
DefaultSecurityHandlerPlugin
has a single attribute setting,
allowJailBrokenDevices
. This specifies if jail-broken client devices should be
allowed or denied access to protected resources. Set the attribute's value to
false
to deny access (default setting) or set it to
true
to allow access. The
OAAMSecurityHandlerPlugin does not need to be configured for jailbreak
enforcement. See Section 49.8.1, "Adding a New Jailbreak Detection Policy," for
more information.
5. Click Create to create the Security Handler Plug-in configuration object.
49.5.2 Editing or Deleting a Security Handler Plug-in
To edit or delete a Security Handler Plug-in, select the definition in the panel and click
Edit or Delete on the panel's tool bar.
49.5.3 Device Fingerprinting and Device Profile Attributes
When a mobile application is started, Mobile Client SDK logic in the application will
attempt to detect a number of Device Profile attributes. Some Device Profile attributes
are general attributes that cannot uniquely identify a device, such as OS Type,
OS Version, language locale setting, network setting, and geographic location. Some
attributes are hardware identifiers that can uniquely identify a device. An example of a
hardware identifier is a MAC Address on a mobile device. The mobile OS type and
version will dictate the kinds of Device Profile attributes that can be detected.
When a mobile application requests a token through the Mobile Client SDK, the SDK
logic will send the Device Profile attributes as a part of an HTTP request. This set of
Device Profile attributes enhances security by creating an audit trail for devices that
assists device identification.
Table 49–14 Security Handler Plug-in General Properties
Name Notes
Name Type a unique name for this Authorization Service Profile.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Security Handler Class Choose the Java class that defines the Security Handler Plug-in that
you want to use. This release of Mobile and Social supports two
Security Handler Plug-ins, the DefaultSecurityHandlerPlugin and
the OAAMSecurityHandlerPlugin.
Defining Application Profiles
49-28 Administrator's Guide for Oracle Access Management
When the OAAM Security Plug-in is used, a particular combination of Device Profile
attribute values is treated as a device finger print, known as the Digital Finger Print in
the OAAM Administration Console. Each finger print is assigned a unique fingerprint
number. Each OAAM session is associated with a finger print and the finger print
makes it possible to log (and audit) the devices that are performing authentication and
token acquisition.
49.6 Defining Application Profiles
An Application Profile defines the client application that will consume services
provided by the Service Providers. A single Application Profile can be assigned to
multiple Service Domains. More information can be found in the following sections.
■Creating an Application Profile
■Editing or Deleting an Application Profile
49.6.1 Creating an Application Profile
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Application Profiles section.
The Application Profiles Configuration page displays.
3. Enter values for the Application Profile general properties.
4. Enter name-value pairs for the attributes used by the Mobile and Social server to
perform server functions for this application; for example, creating a Client
Registration Handle.
■
Mobile.clientRegHandle.baseSecret
is a mandatory attribute used by the
server as a private secret to sign each Client Registration Handle for this
application.
■
userId4BasicAuth
is the user ID attribute used by the server and the
application to perform HTTP Basic authentication. For more information see
Section 48.4.1, "Protecting the Mobile Client Registration Endpoint."
■
sharedSecret4BasicAuth
is the shared secret attribute used by the server and
application to perform HTTP Basic authentication.
5. Define the Mobile Application Profile properties.
■Jailbreak Detection - Select the Enabled box to activate Jailbreak Detection for
this application, or clear the box to disable it. If Jailbreak Detection is grayed
out, the Jailbreak Detection Policy is disabled in Mobile and Social. For more
information, see Section 49.8, "Using the Jailbreak Detection Policy."
Table 49–15 Application Profile General Properties
Name Notes
Name The value must be a unique one that distinguishes the application
from all other applications on the server. This value and the
application name value embedded in the client application must
match.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Defining Application Profiles
Configuring Mobile and Social Services 49-29
■Mobile Configuration - Select this option to expose additional mobile
configuration settings on the Application Profile Configuration page.
6. Click Create to create the Application Profile configuration object.
See Section 49.6.2, "Editing or Deleting an Application Profile" for information on
properties that can be configured only after the Application Profile is created.
49.6.2 Editing or Deleting an Application Profile
To edit or delete an Application Profile, select the definition in the panel and click Edit
or Delete on the panel's tool bar. This section describes additional Application Profile
properties as they appear when editing a User Profile Service Provider that you or
another Administrator previously created.
■Configuration Settings
– Profile Cache Duration - The maximum amount of time that the Application
Profile details cached on the mobile device will remain valid. If the time is
elapsed when the mobile client application requests the Application Profile,
the cached Profile is replaced with a freshly downloaded version. If the time is
not elapsed, the cached Profile is used.
– Authentication Retry Count - The maximum number of retries that a User is
allowed if invalid credentials are provided during registration/authentication.
This setting is not honored in the iOS Mobile SDK.
– Offline Authentication - Select the Allowed box to allow users to log in and
authenticate to the application locally. Clear the box to block users from
authenticating locally.
– Claim Attributes - The set of attributes that will be fetched from the device
and passed to the server during registration/authentication.
– Social Identity WebView - Choose Embedded if users should be presented
with the Mobile and Social login page inside the application using the
embedded WebView class, or choose External if the login page should be
presented in an external browser.
■Platform Specific Settings
– URL Scheme - Type the URL scheme that is used to invoke this mobile client
application, as configured in the application itself.
– Apple iOS Bundle ID - Type the unique Bundle ID that is configured in the
mobile client application. Each iOS mobile application has a unique Bundle
ID.
– Android Package - Type the fully qualified name of an activity in the Android
application. This activity should have
<data android:scheme="xyz" />
in its
<intent-filter>
.
For details regarding the
<data>
element, please see the following web page:
http://developer.android.com/guide/topics/manifest/data-element.htm
l
– Android Application Signature - Enter the signature of the Android
application. You can obtain the signature from the certificate with which the
Note: The
scheme (xyz)
should be the same as the URL scheme.
Defining Service Domains
49-30 Administrator's Guide for Oracle Access Management
application is signed. On Linux, you can obtain the signature using the
following command:
keytool -exportcert -alias <alias_name>
-keystore
<keystore_name>
-storepass
<keystore_password>
| xxd -c 256 -ps
You can also retrieve the signature programmatically. For details, see
"Invoking the Mobile Single Sign-on Agent App" in the Developer's Guide for
Oracle Access Management.
■Custom Settings / Mobile Custom Attributes - Configure attributes or properties
specific to the mobile client application. Mobile Custom Attributes are returned by
the server to the mobile application as part of the Application Profile
49.7 Defining Service Domains
Create a Service Domain to associate Service Profiles with Application Profiles and the
corresponding configuration settings. When the Create Service Domain page is
displayed, you can:
■Choose if the Service Domain is for managing mobile applications or desktop
applications.
■Choose an authentication scheme and, optionally, a Security Handler Plug-in for
the Service Domain.
■Add one or more Mobile SSO Agents to the Service Domain and configure which
agents have priority over others.
■Add one or more applications to the Service Domain and configure which
applications can use a Mobile SSO Agent.
■Choose at least one Service Profile for the Service Domain.
■Configure security settings to protect the Service Domain's selected services.
More information can be found in the following sections.
■Creating a Service Domain
■Editing or Deleting a Service Domain
49.7.1 Creating a Service Domain
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. Click Create in the Service Domains panel in the home area.
The Create Service Domain Configuration page displays.
3. Enter values for the Service Domain general properties.
Note: The signature obtained using the above command will have a
carriage return after 256 characters. Remove it before entering the
signature in this field.
Table 49–16 Service Domain General Properties
Name Notes
Name Type a unique name for this Service Domain.
Defining Service Domains
Configuring Mobile and Social Services 49-31
4. Use one or all of the following options to add or select Application Profiles.
If configuring a mobile domain, only mobile apps can be selected. Similarly, if
configuring a non-mobile domain, only desktop apps can be selected
a. Click Browse Application Profiles (under Application Profile Selection) to
open a Search window from which you can search for one or more previously
configured Application Profiles to add to the Service Domain. Select the
Profiles to add and click Select.
b. Alternately, if you know the exact name of the Application Profile, click Add
and type the name directly into the table.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Type Choose Mobile Application or Desktop Application. A mobile
application is an application that runs on a mobile operating system,
such as the Android or iOS operating systems. A desktop application
is an application that runs on a non-mobile operating system.
Credential for
Registering an
Application
If configuring a mobile Service Domain, choose the minimum
credential level required to register an application. If you choose
User Password, the server will prompt the User for a user name
and password every time an application is registered, even if a
mobile single sign-on agent is installed on the device. If you choose
User Token, the server asks the mobile SSO agent to provide the
User name and password. Subsequent application registrations on
that device then will use the User Token issued to the mobile SSO
agent for that purpose. User Password provides added security
around the application registration process. User Token makes the
application registration process more convenient for the User.
Authentication Scheme If configuring a mobile Service Domain, choose Mobile Service
Authentication or Social Identity Authentication. If you choose
Mobile Service Authentication, the client will prompt the User for a
User name and password. If you choose, Social Identity
Authentication, the client will redirect to the Mobile and Social
server and the User will use Social Identity to authenticate with an
Identity Provider, for example Google or Facebook. This selection
determines which Authentication Service Profiles you can choose
on the Service Profile Selection configuration screen.
Security Handler Plug-in
Name
Security Handler Plug-in Name - If configuring a mobile Service
Domain, choose the Security Handler Plug-in to use. For
information about the available Security Handler Plug-ins, see
Section 49.2.3, "Understanding Security Handler Plug-ins."
Table 49–17 Application Profile Selection Properties
Name Notes
Application Profile Name The name that uniquely identifies the client application to Mobile
and Social.
Table 49–16 (Cont.) Service Domain General Properties
Name Notes
Defining Service Domains
49-32 Administrator's Guide for Oracle Access Management
5. Click Next to select a Service Profile.
The Service Profile page displays.
6. Use one or both of the following options to add at least one Service Profile to the
Service Domain.
For a mobile Service Domain, you can add one Service Profile for each
authentication, authorization, and User Profile Services Service Provider. For a
non-mobile Service Domain, you can add multiple Service Profiles for each
authentication, authorization, and User Profile Services Service Provider.
a. Click Select to open a Search window from which you can search for a
previously configured Service Profile. If configuring a mobile Domain, you
can only select a mobile-compatible Authentication Service Profile. Similarly, if
configuring a non-mobile domain, you can only select a desktop-compatible
Authentication Service Profile. Select the Profile to assign and click Select. If
you know the exact name of the Service Profile, click Add and type the name
directly into the table.
b. Click Create to create a new Service Profile.
Mobile Single Sign-on
(SSO) Configuration
If configuring a mobile Service Domain, choose if each application
should participate in mobile single sign-on as an SSO Agent, as an
SSO Client, or not at all (None).
■Choose None if this application does not want to participate in
mobile SSO and instead wants to perform User authentication
with the Mobile and Social server directly.
■Choose As an SSO Agent if the application is a mobile single
sign-on agent that can accept authentication requests from
other apps. For details about creating a custom mobile SSO
agent, refer to the Android or iOS SDK information in the
Developer's Guide for Oracle Access Management.
■Choose As an SSO Client if the application is configured to
work with mobile single sign-on and it delegates user
authentication and user session management responsibilities to
a mobile SSO agent.
Agent Priority Displays the numerical ranking for applications that are configured
as mobile SSO Agents. When multiple agent apps are installed on
the device, the Agent application with highest priority (smallest
numerical rank) acts as the Agent application for all other Agent
apps. If that Agent is deleted from the device, the Agent with the
next highest ranking becomes the active Agent. Click Move Up and
Move Down to reorder the agents by priority.
Description (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
Table 49–18 Service Profile Selection Properties
Name Notes
Authentication Service (Optional) Displays the name of the Authentication Service Profile
configured for this Service Domain and the corresponding Service
Endpoint. If creating a new Service Profile, see Section 49.4.1,
"Defining, Modifying and Deleting an Authentication Service
Profile."
Table 49–17 (Cont.) Application Profile Selection Properties
Name Notes
Defining Service Domains
Configuring Mobile and Social Services 49-33
7. Click Next to configure Service Protection (authentication).
The Service Protection page displays.
8. Configure authentication for the Service Profile using one of the following options.
a. If you previously selected a User Profile Service for this Service Domain,
configure the security settings to protect it.
b. If you previously selected an Authorization Service for this Service Domain,
configure the security settings to protect it.
9. Click Next to verify your selections.
10. Click Finish to create the Service Domain.
Authorization Service (Optional) Displays the name of the Authorization Service Profile
configured for this Service Domain and the corresponding Service
Endpoint. If creating a new Service Profile, see Section 49.4.2,
"Defining, Modifying and Deleting an Authorization Service
Profile."
User Profile Service (Optional) Displays the name of the User Profile Service Profile
configured for this Service Domain and the corresponding Service
Endpoint. If creating a new Service Profile, see Section 49.4.3,
"Defining, Modifying and Deleting a User Profile Service Profile."
Table 49–19 User Profile Service Protection Properties
Name Notes
Authentication Choose from the menu the Authentication Service Profile
configured for this Service Domain, with which you would like to
protect this User Profile service.
Secured Application Select to require the client application to authenticate, either by
presenting a Client Resource Handle or a Client Token.
Secured User Select to require a User to authenticate, either by presenting a User
Token or an Access Token, where the access token is previously
acquired with a User Token.
Allow Read Select to allow users to view User Profile data.
Allow Write Select to allow users to update User Profile data.
Table 49–20 Authorization Service Protection Properties
Name Notes
Authentication Choose the Authentication Service Profile configured for this
Service Domain, with which you would like to protect this
Authorization service.
Secured Application Select to require the client application to authenticate, either by
presenting a Client Resource Handle or a Client Token.
Secured User Select to require a User to authenticate, either by presenting a User
Token or an Access Token, where the access token is previously
acquired with a User Token.
Table 49–18 (Cont.) Service Profile Selection Properties
Name Notes
Using the Jailbreak Detection Policy
49-34 Administrator's Guide for Oracle Access Management
49.7.2 Editing or Deleting a Service Domain
To edit or delete an Service Domain, select the definition in the panel and click Edit or
Delete on the panel's tool bar.
49.8 Using the Jailbreak Detection Policy
Jailbreaking is the process of removing or circumventing the limitations that
manufacturers impose on their mobile devices. While legal, jailbreaking can present a
heightened security risk to protected resources. To counter this risk, Mobile and Social
provides a preconfigured Jailbreak Detection Policy for iOS devices.
The Jailbreak Detection Policy consists of one or more statements that instruct a client
application (built using the Mobile and Social SDK for iOS) to search for files that may
indicate the device is jailbroken. The Mobile and Social server sends the Policy
statements to the iOS client application. The client device then returns a true
(jailbreaking is detected) or false value back to the Mobile and Social server. This value
is forwarded to the Security Handler Plug-in and, depending on the security policies
of the Security Handler Plug-in in use, Mobile and Social can allow access, deny
access, or wipeout any Mobile and Social specific data from the application.
■If the Default Security Handler Plug-in is active and the policy logic says the device
is jail broken, the Plug-in can ALLOW or DENY access to the client device
depending on how the
allowJailBrokenDevices
Plug-in attribute is set.
■If the Oaam Security Handler Plug-in is active and the policy logic says the device
is jail broken, the Plug-in can ALLOW or BLOCK access to the client device
depending on how the OAAM policy rules are configured. (Refer to the
Administrator's Guide for Oracle Adaptive Access Manager for information on the
policy rules as in, for example, the Jail broken Mobile Device rule under the
"OAAM Post-Authentication Security" policy.)
Additionally, if a device is blacklisted, lost or stolen, this Plug-in can send a
WIPEOUT command that will delete any Mobile and Social specific data from the
device and block the device from future requests. If the user recovers the missing
device, the device can be reset in OAAM.
See Section 49.5, "Defining Security Handler Plug-ins" for more information.
The following sections contain more information.
■Adding a New Jailbreak Detection Policy
■Editing the Jailbreak Detection Policy
49.8.1 Adding a New Jailbreak Detection Policy
If you choose to create a new Jailbreak Detection Policy using XML, click the Load
button to overwrite the default Policy completely. A schema file is available from
customer support.
Use the following procedure to create a new Jailbreak Detection Policy with the Oracle
Access Management Console.
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
Note: OAAM's BLOCK and Mobile and Social's DENY mean the
same thing.
Using the Jailbreak Detection Policy
Configuring Mobile and Social Services 49-35
2. Click Jailbreak Detection Policy in the navigation pane.
The Jailbreak Detection Policy page displays.
3. Click Add to configure the Conditions and Detection Logic properties for a new
Jailbreak Detection Policy.
■Jailbreak Detection - Select Enabled to turn the Jailbreak Detection Policy on,
or clear this option to turn it off for all client Application instances. If you
enable the Jailbreak Detection Policy here, you can disable it on an application
by application basis. If you disable the Policy here, you cannot enable or
disable the feature on an application by application basis.
■Min OS Version - The minimum iOS version to which the policy applies. If
the value is 1.0, the policy will apply to iOS devices running at least version
1.0 of iOS.
■Max OS Version - The maximum iOS version to which the policy applies. If
the value is empty, a maximum iOS version number is not checked so the
policy applies to any iOS version higher than the value specified for Min OS
Vers ion.
■Min Client SDK Version - The minimum Mobile and Social Client SDK
version number. For example, 11.1.2.0.0.
■Max Client SDK Version - The maximum Mobile and Social Client SDK
version number. For example, 11.1.2.3.0.
■Policy Expiration Duration - Type the length of time in seconds that the SDK
on the iOS client device should wait before expiring the local copy of the
policy and retrieving a newer version.
■Auto Check Period - Type the interval of time in minutes that the iOS client
device should wait before executing the Jailbreak Detection Policy statements
again.
■Detection Location - The iOS client device uses a logical-OR operator to
evaluate Policy statements. Add a Detection Location as follows:
– File Path - Type the absolute path to the file or directory on the device for
which the Detection Policy should search.
–Action - Select Exists which instructs the Detection Policy to evaluate
whether it can access a file path.
– Success - Select if the Policy should flag the device as jail broken if the
specified files or directories are found on the device. Use this option if the
policy is checking for unauthorized files or directories. Clear this option if
the Policy should flag the device as jail broken if the specified files or
directories are not found. (Use this option if checking for required files or
directories.)
49.8.2 Editing the Jailbreak Detection Policy
In most cases you can use the Policy Statements editor on the Jailbreak Detection
Policy Configuration page to change a Jailbreak Detection Policy.
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. In the Jailbreak Detection Policy section, do one of the following:
Configuring Mobile and Social Services with Other Oracle Products
49-36 Administrator's Guide for Oracle Access Management
■To append changes to the Jailbreak Detection Policy, click Load in the tool bar,
browse to the XML file that contains the Jailbreak Detection Policy statements
that you want to append, choose Append after existing policy statements,
and click OK. A schema file is available from customer support.
■To overwrite the Jailbreak Detection Policy, click Load in the tool bar, browse
to the XML file that contains the Jail-Breaking Detection Policy statements that
you want to load, choose Overwrite existing policy statements, and click OK.
A schema file is available from customer support.
■To edit the Jailbreak Detection Policy, select it in the Policy Statements table to
display its properties, make changes (as per Section 49.8.1, "Adding a New
Jailbreak Detection Policy") and click Apply.
49.9 Configuring Mobile and Social Services with Other Oracle Products
The following sections contain information on configuring Mobile and Social with
other Oracle products.
■Configuring Mobile and Social Services for Access Manager
■Configuring Mobile and Social Services for Oracle Adaptive Access Manager
49.9.1 Configuring Mobile and Social Services for Access Manager
The following sections describe how to configure Mobile and Social to work with
different versions of Access Manager.
■Configuring Mobile and Social Services to Work With Access Manager in Simple
and Certificate Mode
■Configuring an Authentication Service Provider for Remote Oracle Access
Manager Server 10g
■Configuring an Authentication Service Provider for Remote Access Manager
11gR2 or Oracle Access Manager 11gR1 PS1
49.9.1.1 Configuring Mobile and Social Services to Work With Access Manager in
Simple and Certificate Mode
Use the following procedure to configure Mobile and Social Services to work with
Access Manager if Access Manager is configured in Simple Mode.
Change the Server Mode to Simple
1. In the Oracle Access Management Administration Console, click Configuration at
the top of the window.
2. Click Server Instances.
3. Click Search and click oam_server1 in the Search Results.
4. Click Open.
Note: During installation, the Oracle Fusion Middleware
Configuration Wizard generates a domain that supports both Mobile
and Social and Access Manager. For more information, see the
"Configuring Mobile and Social" chapter in the Oracle Fusion
Middleware Installation Guide for Oracle Identity and Access Management.
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-37
5. In the OAM Proxy section, choose Simple from the Mode menu and click Apply.
Change the Webgate Communication Mode to Simple
1. In the Oracle Access Management Administration Console for the target Webgate,
click Application Security at the top of the window.
2. In the Webgates tab, click Search.
3. Select the target Webgate and open it for editing.
4. Change the security mode for the Webgate to Simple, then click Apply.
The system creates a new directory for the Webgate under
~/oam-domain/output/accessgate-oic
with the following files:
■
aaa_cert.pem
■
aaa_key.pem
■
cwallet.sso
■
ObAccessClient.xml
■
password.xml
Change the OIC OAMASDKAuthNProvider Security Mode to Simple
1. Copy the
.jks
files from the
~/oam-domain/output/webgate-ssl
directory to the
~/oam-domain/config/fmwconfig
directory.
2. Go to the
~/oam-domain/output/accessgate-oic
directory and open
password.xml
.
Copy the
passwd
value from the file.
3. Open the Oracle Access Management Administration Console.
The Launch Pad opens.
Go to the Mobile and Social panel and click Mobile and Social Services > Service
Providers > Authentication Service Providers > OAMAuthentication.
4. Add the following name-value pairs to the Attributes table.
5. In the Attributes table, locate
TRANSPORT_SECURITY
and change the value from
OPEN
to
SIMPLE
or
CERT
and click Save.
6. Restart the Oracle Access Management server.
49.9.1.2 Configuring an Authentication Service Provider for Remote Oracle Access
Manager Server 10g
The following procedure documents how to configure an Authentication Service
Provider to work with a remote instance of the Oracle Access Manager 10g server.
1. Log in to the 10g Console and create the WG Profile.
Name Value
PASSPHRASE
The
passwd
value from step 2.
KEYSTORE
<fully qualified
path>
/oam-domain/config/fmwconfig/oamclient-keystore.jks
TRUSTSTORE
<fully qualified
path>
/oam-domain/config/fmwconfig/oamclient-truststore.jks
Configuring Mobile and Social Services with Other Oracle Products
49-38 Administrator's Guide for Oracle Access Management
The OAM 10g Access Management Service must be turned on.
2. Navigate through the Mobile and Social Console to Mobile and Social Services >
Service Providers > Authentication Service Providers.
3. Click New to create a new Authentication Service Provider configuration.
4. Enter the appropriate values for the parameters.
a. Change OAM_VERSION to OAM_10G from OAM_11G.
b. Change WEBGATE_ID to the name you previously used to create the WG
profile.
c. Change OAM_SERVER_1 to the hostname:port# of the machine hosting the
OAM 10G server.
d. Add a new parameter named
AuthNURL
and populate it with the URL for any
protected resource; for example,
http://server1.example.com/index.html
.
5. Save the Authentication Service Provider configuration.
6. Navigate through the Mobile and Social console to Mobile and Social Services >
Service Profiles > Authentication Services > OAMAuthentication.
7. From the Service Provider drop down menu, select the Authentication Service
Provider just created; for example,
10GOAMAuthentication
.
8. Check the Client Token checkbox.
9. Uncheck the Access Token checkbox.
10. Save the OAMAuthentication configuration.
If Mobile and Social is configured to work with a remote instance of the Oracle Access
Manager 10g server, you must also do either of the following:
■Define a
uid
attribute in the directory
DN
entry for user records in the Oracle
Access Manager
UserStore
.
■Define a unique directory user entry attribute that can be used to identify the
directory user entry in Mobile and Social.
The following procedure demonstrates setting the value to
CN
. Set the value to a
unique user entry as configured on your directory server;
uid
or
loginid
may also be
possible choices. Before beginning, confirm that the Oracle Access Manager DN for
UserStore
does not include a
uid
attribute for the Application Profile
profileid1
,
and that the DN is as follows:
"CN=profileid1 profileid1, OU=Test, ..."
Complete the next steps upon confirming that both are true.
1. Open the Application Profile Configuration page for
profileid1
in Mobile and
Social as documented in Section 49.6, "Defining Application Profiles."
2. In the Attributes section, add the following name-value pair and click Apply.
Note: Mobile and Social can dynamically obtain the unique directory
user attribute name from Oracle Access Manager version 11g but the
earlier 10g release requires that you specify the attribute to use when
configuring Mobile and Social. If this attribute is not set, Client Token
validation will fail in Mobile and Social.
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-39
Name:
userPrincipalAttrValue
Val u e:
CN
3. Open the Service Provider Configuration page for your Oracle Access Manager
10g Authentication Service Provider as documented in Section 49.3.1, "Defining,
Modifying or Deleting an Authentication Service Provider."
4. In the Attributes section, add the following name-value pair and click Apply.
Name:
userPrincipalAttrName
Val u e:
CN
49.9.1.3 Configuring an Authentication Service Provider for Remote Access
Manager 11gR2 or Oracle Access Manager 11gR1 PS1
The following procedure documents how to configure an Authentication Service
Provider to work with releases 11gR2 and 11gR1 PS1. The differences for the 11gR1 PS1
release console are documented in notes within each 11gR2 step.
1. Log in to the Oracle Access Management Console and register a Webgate (OAM
Agent) for Mobile and Social.
Be sure to enable the following options.
■Allow Management Operations
■Allow Token Scope Operations
■Allow Master Token Retrieval
■Allow Credential Collector Operations
2. Navigate through the Mobile and Social Console to Mobile and Social Services >
Service Providers > Authentication Service Providers.
3. Click New to create a new Authentication Service Provider configuration.
4. When using an OAM 11.1.2 release console, enter the following values:
a. Keep the default value of
OAM_VERSION
as
OAM_11G
.
b. Change
WEBGATE_ID
to the name you previously used to create the WG profile.
c. Change
OAM_SERVER_1
to the hostname:port# of the machine hosting the OAM
11G server.
Note: See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a Webgate.
Note: If using an OAM 11.1.1.n release console, enable Allow
Management Operations.
Configuring Mobile and Social Services with Other Oracle Products
49-40 Administrator's Guide for Oracle Access Management
5. Save the Authentication Service Provider configuration.
6. Navigate through the Mobile and Social Console to Mobile and Social Services >
Service Profiles > Authentication Services > OAMAuthentication.
7. From the Service Provider drop-down menu, select the Authentication Service
Provider just created; for example,
10GOAMAuthentication
.
8. Select the Client Token checkbox.
9. Clear the Access Token checkbox only if using OAM 11g R1 PS1.
10. Save the OAMAuthentication configuration.
11. Merge the CSF wallet files.
OAM 11G generates the
cwallet.sso
file when the administrator creates the WG
profile for Mobile and Social. To communicate with this WG profile, the
administrator must merge the secret value in
cwallet.sso
into the Mobile and
Social wallet.
a. Copy
cwallet.sso
from OAM (~/domain-home/output) to the Mobile and
Social host machine directory,
/tmp/oam
.
b. Copy
cwallet.sso
from the Mobile and Social host machine directory
(
~/config/fmwconfig
) to the Mobile and Social host machine directory,
/tmp/oic
.
c. Download
merge-creds.xml
to the Mobile and Social host machine directory,
/tmp
.
Example 49–1 is a sample
merge-creds.xml
file.
Example 49–1 Sample merge-creds.xml
<?xml version="1.0" encoding="UTF-8" standalone='yes'?>
<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd"
schema-major-version="11" schema-minor-version="1">
<serviceProviders>
Note: If using an OAM 11.1.1.n release console:
1. Change the default value of
OAM_VERSION
to
OAM_10G
.
2. Change
WEBGATE_ID
to the name you previously used to create the WG
profile.
3. Change
OAM_SERVER_1
to the hostname:port# of the machine hosting the
OAM 11.1.1.5 server.
4. Add a new parameter named
AuthNURL
and populate it with the URL for
any protected resource; for example,
http://server1.example.com/index.html
.
Note: Use the following command to display the wallet before and
after the merge for verification that the merge has been successful.
orapki wallet display -wallet wallet_location
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-41
<serviceProvider
class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider"
name="credstoressp" type="CREDENTIAL_STORE">
<description>File-based credential provider</description>
</serviceProvider>
</serviceProviders>
<serviceInstances>
<!-- Source file-based credential store instance -->
<serviceInstance location="/tmp/oam" provider="credstoressp"
name="credential.file.source">
</serviceInstance>
<!-- Destination file-based credential store instance -->
<serviceInstance location="/tmp/oic" provider="credstoressp"
name="credential.file.destination">
</serviceInstance>
</serviceInstances>
<jpsContexts>
<jpsContext name="FileSourceContext">
<serviceInstanceRef ref="credential.file.source"/>
</jpsContext>
<jpsContext name="FileDestinationContext">
<serviceInstanceRef ref="credential.file.destination"/>
</jpsContext>
</jpsContexts>
</jpsConfig>
d. Set the PATH variable to include ~/oracle_common/bin:~/oracle_
common/common/bin:~
e. Initialize the WebLogic Scripting Tool by running
wlst.sh
on the command
line.
f. Run the
migrateSecurityStore
WLST command.
Following is sample syntax for the WLST command.
$ wlst.sh
wls:/offline> connect("weblogic", "weblogic-passwd", "localhost:<port>")
wls:/WLS_IDM/serverConfig>
migrateSecurityStore(type="credStore",configFile="/tmp/merge-creds.xml",
src="FileSourceContext",dst="FileDestinationContext")
12. Restart the Mobile and Social server.
49.9.2 Configuring Mobile and Social Services for Oracle Adaptive Access Manager
To configure a Service Domain to use the Oracle Adaptive Access Manager (OAAM)
device registration functionality, open the Service Domain Configuration page and
choose the OAAMSecurityHandlerPlugin option from the Security Handler Plugin
Name list. See Section 49.7.1, "Creating a Service Domain."
Configuring Mobile and Social Services with Other Oracle Products
49-42 Administrator's Guide for Oracle Access Management
The following sections describe how to configure the required policies, conditions,
rules, and actions to complete integration between Mobile and Social and OAAM.
■Understanding OAAM Support in Mobile and Social
■Configuring the WebLogic Administration Domain
■Configuring OAAM if Social Identity Authentication is Enabled in Mobile and
Social Services
■Setting up a Lost or Stolen Device Rule
■Configuring Blacklisted Devices and Applications
■Understanding the OAAM Sessions for Mobile Applications
■Registering Users for OAAM Authentication
■Setting up OAAM Knowledge-Based Authentication
■Setting up OAAM One Time Password
49.9.2.1 Understanding OAAM Support in Mobile and Social
Mobile and Social supports the OAAM policies listed (by OAAM checkpoint) in
Table 49–21.
Mobile and Social and OAAM also use similar terminology to describe the security
actions that can be taken to respond to authentication and authorization events.
Table 49–22 maps the the Mobile and Social term to the OAAM term.
Note: During installation, the Oracle Fusion Middleware
Configuration Wizard can generate a domain that supports both
Mobile and Social and Oracle Adaptive Access Manager. Mobile and
Social requires at least Oracle Adaptive Access Manager version 11g
Release 2. For more information, see the "Configuring Mobile and
Social" chapter in the Fusion Middleware Installation Guide for Oracle
Identity and Access Management.
Note: See the Administrator's Guide for Oracle Adaptive Access Manager
for information on how to set up OAAM rule and policy ordering.
Table 49–21 OAAM Policies Supported By Mobile and Social
Checkpoint Supported Policies
Post-Authentication OAAM Post-Authentication Security
OAAM User vs Themselves
OAAM User vs. All Users
OAAM Does User Have Profile
OAAM Predictive Analysis Policy
Challenge OAAM Challenge Policy
Device Identification OAAM Device ID Policy
OAAM System Deep Analysis Flash Policy
OAAM System Deep Analysis No Flash Policy
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-43
■For information about the OAAM policies, rules and checkpoints, see the Oracle
Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.
■To customize OAAM policies and rules, use the Oracle Adaptive Access Manager
Administrator's Console.
49.9.2.2 Configuring the WebLogic Administration Domain
Before configuring OAAM policies, complete the steps in this section.
■Creating an Administrator for OAAM Administration
■Adding Oracle Access Management Server as Target of OAAM Data Source
49.9.2.2.1 Creating an Administrator for OAAM Administration 1.Log in to the Oracle
WebLogic Administration Console for your WebLogic administration domain.
2. In the Domain Structure tab on the left side of the page, select Security Realms.
3. On the Summary of Security Realms page, select the realm that you are
configuring; for example, myrealm.
4. Click New and provide the required information to create a User in the security
realm: Name (for example, user1), Description (optional), Provider (enter
DefaultAuthenticator), Password, and Confirm Password.
5. Click to select the new created User.
6. Click the Groups tab.
7. Assign to the User all groups with an OAAM prefix.
8. Click Save.
49.9.2.2.2 Adding Oracle Access Management Server as Target of OAAM Data Source 1.Log in
to the Oracle WebLogic Administration Console for your WebLogic administration
domain.
2. In the Domain Structure tab on the left side of the page, select Services.
3. On the Summary of Services page, select Data Sources.
4. Open
OAAM_SERVER_DS
in the Data Sources table.
5. Click the Targets tab.
6. Select
oam_server1
.
7. Click Save.
Table 49–22 Mapping Terms Between OAAM and Mobile and Social
OAAM Action Groups Mobile and Social Actions
OAAM Allow ALLOW
OAAM Block DENIED
OAAM Challenge CHALLENGE
OAAM Black-Listed Mobile Device WIPE_OUT
OAAM Lost Device WIPE_OUT
Configuring Mobile and Social Services with Other Oracle Products
49-44 Administrator's Guide for Oracle Access Management
49.9.2.3 Configuring OAAM if Social Identity Authentication is Enabled in Mobile
and Social Services
If Mobile and Social Services is configured to accept an authentication result from
Social Identity, complete the following steps to configure OAAM to work with Mobile
and Social when users authenticate.
1. Log in to the OAAM Administration Console.
2. Click Policies and search for the OAAM Mobile and Social Integration
Post-Authentication Security policy.
3. In the policy find the following rule: Mobile device is not registered.
4. Add a condition:
a. Search on "Session: Check value in comma separated values."
b. Add the following:
Parameter Key : oic.userIdType
Value to Check : URI
Return if in list : false
49.9.2.4 Setting up a Lost or Stolen Device Rule
Users should report lost or stolen devices to the support department so that the
missing device can be added to the OAAM Lost or Stolen Device group. Then if an
authentication attempt comes from the missing device, OAAM can send Mobile and
Social a DENY or WIPE_OUT action to wipe out the application's data associated with
the Mobile and Social server. If a User recovers a missing device, the device status can
be reset in OAAM. The following procedure documents how to create a Lost or Stolen
Device Rule for each device reported as missing by adding the Device ID to the OAAM
Lost or Stolen Devices device group.
1. Log in to the OAAM Administration Console.
2. Double-click Sessions in the Navigation pane.
The Sessions Search page displays.
3. Search by User Name, Client Application name, Device ID or similar to find the
lost or stolen device.
4. Click the Session ID in the Search Results table.
The Session Details page opens.
5. Click Add to Group.
The Add to Group pop-up window opens.
6. In the Choose Data Type to Add section, choose Device and click Next.
7. Select the OAAM Lost or Stolen Devices Group and click Next.
8. Verify your selection and click Finish.
9. Click OK.
For information about managing the Lost Devices policy and group, see the Oracle
Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-45
49.9.2.5 Configuring Blacklisted Devices and Applications
Rules can be configured to block access to specific devices or applications. The
following sections contain more information.
■Setting up a Blacklisted Device Rule
■Setting up a Blacklisted Application Rule
49.9.2.5.1 Setting up a Blacklisted Device Rule Create a Blacklisted Device Rule for each
device to which you want to block access. The following procedure documents how to
create a Blacklisted Device Rule by adding the Device ID to the OAAM Black-listed
Mobile Devices group.
1. Log in to the OAAM Administration Console.
2. Double-click Sessions in the Navigation pane.
The Sessions Search page displays.
3. Use the Search page to find the device to block. For example, search by a User
Name, a Client Application name, a Device ID, and so on.
4. Click the Session ID in the Search Results table.
The Session Details page opens.
5. Click Add to Group.
The Add to Group pop-up window opens.
6. In the Choose Data Type to Add section, choose Device and click Next.
7. Select the OAAM Black-listed mobile devices Group and click Next.
8. Verify your selection and click Finish.
9. Click OK.
49.9.2.5.2 Setting up a Blacklisted Application Rule The task of adding a Blacklisted
Application Rule is broken into the following procedures. Follow them (in order) to
add the application to the OAAM Blacklisted Mobile Devices group.
■Creating a New Alert Group
■Creating a Generic Strings Group to Store Blacklisted Application Names
■Creating a New Blacklisted Application Rule
49.9.2.5.3 Creating a New Alert Group
1. Log in to the OAAM Administration Console.
2. Double-click Groups in the Navigation pane.
The Groups Search page displays.
3. Click New Group.
The Create Group pop-up window opens.
4. Complete the form as follows and click Create:
■Group Name - Type
OAAM Blacklisted mobile application used
. (This is
the name of the mobile application to be blacklisted.)
■Group Type - Choose Alerts from the menu.
■Cache Policy - Choose Full Cache from the menu.
Configuring Mobile and Social Services with Other Oracle Products
49-46 Administrator's Guide for Oracle Access Management
■Description - Type
Session coming from a blacklisted mobile
application
.
5. Click the Alerts tab.
6. Click the Add member to this group button.
The Add Alerts pop-up window opens.
7. In the Options to add a new element section, choose Create new Alerts.
Complete the form as follows and click Add:
■Alert Type - Choose Fraud from the menu.
■Alert Level - Choose Medium from the menu.
■Alert Message - Type
Session coming from a blacklisted mobile
application
.
The Add Alerts window displays a message confirming that the new element was
created successfully.
49.9.2.5.4 Creating a Generic Strings Group to Store Blacklisted Application Names
1. Double-click Groups in the Navigation pane.
The Groups Search page displays.
2. Click New Group.
The Create Group pop-up window opens.
3. Complete the form as follows and click Create:
■Group Name - Type
OAAM blacklisted mobile application
.
■Group Type - Choose Generic Strings from the menu.
■Cache Policy - Choose Full Cache from the menu.
■Description - Type
OAAM blacklisted mobile application
.
4. Click the Generic Strings tab, then click the Add member to this group button.
5. Type the name of the app.
The Add Generic Strings window displays a message confirming that the new
element was created successfully.
Click OK.
49.9.2.5.5 Creating a New Blacklisted Application Rule
1. Double-click Policies in the Navigation pane.
The Policies Search page displays.
2. Choose Post authentication from the Checkpoint menu, then click Search.
3. Click OAAM Post-Authentication Security.
The OAAM Post-Authentication Security page opens.
4. Click the Rules tab.
5. Click the Add Rule button.
Complete the form as follows and click Add:
■Rule Name - Type
Check for blacklisted mobile applications
.
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-47
■Rule Status - Choose Active from the menu.
■Rule Notes - Type
Check if application is in the Oaam blacklisted
mobile application group
.
6. Click the Conditions tab.
7. Click Add Conditions.
The Add Condition pop-up window opens.
8. Complete the form as follows and click Search:
■Condition Name - Type
Check Current Session
■Type - Choose In Session from the menu.
9. In the table of results, click Session: Check Current Session using the filter
conditions.
The filter condition details display.
10. Do the following and click Save:
a. Under Check if select Client Application.
b. Select in as the operator.
c. Select Group as the Target Type.
d. Select Generic Strings as the Group Type.
e. Select OAAM blacklisted mobile application as the Group Name.
In English the condition reads as "Check if the Client Application is in the "OAAM
blacklisted mobile application" group."
11. Click the Results tab.
12. Choose OAAM Block from the Action Group menu.
13. Choose OAAM Blacklisted application used from the Alert Group menu.
14. Click Apply.
49.9.2.6 Understanding the OAAM Sessions for Mobile Applications
The OAAM Session is a commonly used conceptual entity in OAAM rule execution. A
rule can use a session attribute as input (for example, Client App Name and OAAM
Device ID) and affect the status of the session at the output (that is, changing the status
to "Blocked").
When OAAM is used in a non-mobile environment such as a web browser, there is a
one-to-one relationship between a user authentication session (an OAM session, for
example) and the OAAM session. For example, each OAAM session contains data
associated with the following fields:
■User ID
■Client IP Address
■OAAM Device ID and Fingerprint
■(Auth) Status: Success, Pending, Blocked, and so on
■Client Application Name
Configuring Mobile and Social Services with Other Oracle Products
49-48 Administrator's Guide for Oracle Access Management
In a mobile application environment, different apps running on the same device used
by the same user are expected to have different OAAM sessions, even in a mobile SSO
scenario. For example, assume the following apps are installed on a mobile device:
■SSO Security Agent App
■White Pages App
■Expense Report App
These apps are listed together as participants of the same Service Domain and they all
participate in single sign-on. A user just needs to log in once using the mobile SSO
agent app. This means that there will only be a single User Authentication session
(that is, a single Access Manager session) shared by multiple apps on the same device.
On the other hand, if the user uses all three apps simultaneously within the same
Access Manager session, each mobile application will have its own OAAM session
entry and three OAAM sessions will be seen in the OAAM Admin Console.
The reason to have separate OAAM sessions for each mobile application is to allow
rules to take the mobile client application into account. The same rule can block
sessions from some apps, while letting sessions from other apps succeed. (The
Blacklisted Application Rule in Section 49.9.2.5.2 is an example of this.) A more
sophisticated rule can consider multiple factors from a session; for example an
Expense Report application might rate as security sensitive while a "White Pages"
(directory look-up) application might rate as less sensitive. The same Risky-IP rule
may block sessions from the Expense Report application but not the White Pages app,
even if the sessions come from the same medium-risky IP address.
49.9.2.7 Registering Users for OAAM Authentication
OAAM provides strong authentication features, such as Knowledge-Based
Authentication and One-Time Password. One-Time Password delivers a password
using e-mail or a mobile text message. These features require end users to register a
security profile that may contain security questions, mobile phone numbers, and
e-mail addresses.
The following sections contain information on setting up these authentication
processes.
■Setting up OAAM Knowledge-Based Authentication
■Setting up OAAM One Time Password
49.9.2.7.1 Setting up OAAM Knowledge-Based Authentication Mobile and Social provides
support for Knowledge-Based Authentication (KBA) if OAAM is installed. KBA is the
default option for Strong Authentication in OAAM. Administrators do not need to
perform extra configuration for KBA to work. Users should use the OAAM Managed
Server Console to record their KBA questions in their User Profile registration. For
more information about KBA, see the Administrator's Guide for Oracle Adaptive Access
Manager.
49.9.2.7.2 Setting up OAAM One Time Password Mobile and Social provides One Time
Password (OTP) support if OAAM is installed. OTP allows end users to authenticate
themselves by entering a server generated one-time-password that might be received
Note: For more information about the OAAM user registration flow,
see the Authentication Flow section in the Administrator's Guide for
Oracle Adaptive Access Manager.
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-49
by either SMS or e-mail. Because the one-time-password is sent out-of-band, the risk is
reduced that someone other than the valid user could obtain access to it. The following
sections contain more information.
■Setting Up OTP E-Mail Integration
■Setting Up OTP Integration for SMS Messages
■Changing the OAAM Challenge Policy Trigger Combination
49.9.2.7.3 Setting Up OTP E-Mail Integration
Mobile and Social can send e-mail in either of the following ways.
■Using the included SMTP client.
■Using the Oracle User Messaging Service (UMS).
This section contains a procedure for each of these integrations. Choose either Setting
Up SMTP for E-mail or Setting Up UMS for E-mail to begin.
After configuring the SMTP or UMS attribute values, enable the Challenge Types on
the OAAM server as documented in this section's third procedure, Enable "Challenge
Types" on the OAAM Server for E-mail.
Setting Up SMTP for E-mail
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. In the Security Handler Plugins section on the right side of the screen, click
OaamSecurityHandlerPlugin and click Edit in the tool bar.
3. In the Attributes section provide values for the following attribute names and
click Apply.
mail.smtp.host - The SMTP server host.
mail.smtp.port - The SMTP server port.
mail.smtp.security.type - The SMTP security type. Either
SSL
or
TLS
.
mail.smtp.user - The user name to log on to the SMTP server.
mail.smtp.fromadd - The Mobile and Social "From" address, for example:
mobileadmin@example.com
mail.smtp.password - The password for the
mail.smtp.user
account.
mail.smtp.truststore.location - The file name with the location of the trust store to
be used to validate the server identity.
mail.smtp.keystore.location - The file name of the key store containing the client
certificate.
mail.smtp.keystore.password - The key store password.
mail.smtp.truststore.password - The trust store password.
4. Complete the steps in Enable "Challenge Types" on the OAAM Server for E-mail.
Note: Configure either SMTP or UMS. Do not configure both.
Configuring Mobile and Social Services with Other Oracle Products
49-50 Administrator's Guide for Oracle Access Management
Setting Up UMS for E-mail
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
2. In the Security Handler Plugins section on the right side of the screen, click
OaamSecurityHandlerPlugin and click Edit in the tool bar.
3. In the Attributes section provide values for the following attribute names and
click Apply.
ums.service.uri - The UMS server Web service URL, for example:
http://
<UMS Server URL>
:
<UMS Port>
/ucs/messaging/webservice
ums.username - The user name for the UMS server.
ums.password - The password for the UMS server.
ums.from.address - The Mobile and Social "From" address, for example:
mobileadmin@example.com
ums.from.name - The Mobile and Social "From" name.
ums.email.enabled - Set to
true
.
4. Complete the steps in Enable "Challenge Types" on the OAAM Server for E-mail.
Enable "Challenge Types" on the OAAM Server for E-mail
1. Log in to the OAAM Administration Console.
2. Choose Environment > Properties in the Navigation pane and double-click
Properties.
The Properties Search page displays.
3. In the Search box, type
bharosa.uio.default.register.userinfo.enabled
in the
Name field and click Search.
Click to select the record in the Search Results section, change the value to
true
,
and click Save.
4. In the Search box, type
bharosa.uio.default.userinfo.inputs.enum.email.enabled
in the Name field
and click Search.
Click to select the record in the Search Results section, change the value to
true
,
and click Save.
5. In the Search box, type
bharosa.uio.default.challenge.type.enum.ChallengeEmail.available
in the
Name field and click Search.
Click to select the record in the Search Results section, change the value to
true
,
and click Save.
49.9.2.7.4 Setting Up OTP Integration for SMS Messages
Mobile and Social sends SMS messages using the Oracle UMS. Complete Setting Up
SMS Using UMS and then Enable "Challenge Types" on the OAAM Server for SMS.
Setting Up SMS Using UMS
1. Access the Mobile and Social Services configuration page as described in
Section 49.1, "Opening the Mobile and Social Services Configuration Page."
Configuring Mobile and Social Services with Other Oracle Products
Configuring Mobile and Social Services 49-51
2. In the Security Handler Plugins section on the right side of the screen, click
OaamSecurityHandlerPlugin and click Edit in the tool bar.
3. In the Attributes section provide values for the following attribute names and
click Apply.
ums.service.uri - The UMS server Web service URL, for example:
http://
<UMS Server URL>
:
<UMS Port>
/ucs/messaging/webservice
ums.username - The user name for the UMS server.
ums.password - The password for the UMS server.
ums.from.address - The Mobile and Social "From" address, for example:
mobileadmin@example.com
ums.from.name - The Mobile and Social "From" name.
ums.email.enabled - Set to
true
.
4. Complete the steps in the Enable "Challenge Types" on the OAAM Server for SMS.
Enable "Challenge Types" on the OAAM Server for SMS
1. Log in to the OAAM Administration Console.
2. Choose Environment > Properties in the Navigation pane and double-click
Properties.
The Properties Search page displays.
3. In the Search box, type
bharosa.uio.default.register.userinfo.enabled
in the
Name field and click Search.
Click to select the record in the Search Results section, change the value to
true
,
and click Save.
4. In the Search box, type
bharosa.uio.default.challenge.type.enum.ChallengeSMS.available
in the
Name field and click Search.
Click to select the record in the Search Results section, change the value to
true
,
and click Save.
49.9.2.7.5 Changing the OAAM Challenge Policy Trigger Combination
OAAM evaluates the Challenge policy when an event triggers the Challenge action. If
KBA is active for a User, the system challenges the User with questions from the
OAAM Challenge Question Action Group. If the User fails the OAAM challenge
questions three times, the system starts the OAAM SMS Challenge Action group.
You can reorder the Action Group using OAAM Challenge Policy trigger
combinations. So other Challenge Action Groups, such as the OAAM Challenge
E-Mail group or the OAAM Challenge SMS group, will take precedence over the
OAAM Challenge question. The following procedure documents how to change the
OAAM Challenge Policy Trigger Combination.
1. Log in to the OAAM Administration Console.
2. Double-click Policies in the Navigation pane.
The Policies Search page displays.
3. Choose Challenge from the Checkpoint menu, then click Search.
4. Click to select OAAM Challenge Policy in the Search Results table.
Configuring Mobile and Social Services with Other Oracle Products
49-52 Administrator's Guide for Oracle Access Management
5. Click the Trigger Combinations tab.
6. Click Reorder.
The Reorder Trigger Combinations pop-up window opens.
7. Use the controls to move trigger combinations to higher or lower positions.
50
Configuring Social Identity 50-1
50
Configuring Social Identity
[32]
Mobile and Social provides a graphical user interface for configuring Social Identity.
(Prior to version 11.1.2.2, Social Identity was named Internet Identity Services.) This
chapter describes how to use the Oracle Access Management Console to configure
Mobile and Social Services and contains the following topics.
■Opening the Manage Social Identity Page
■Understanding Social Identity Configuration
■Defining Social Identity Providers
■Defining Service Provider Interfaces
■Defining Application Profiles
■Integrating Social Identity With Mobile Applications
■Linking Social Identity Provider Accounts
50.1 Opening the Manage Social Identity Page
Follow these steps to open the Manage Social Identity page in the Oracle Access
Management Console.
1. In to the Oracle Access Management Console, click Federation at the top of the
window.
2. Click Social Identity.
3. Click an OAuth Identity Domain to configure it.
Note: Social Identity can also be configured from the command line
using WLST. For more information about the Mobile and Social WLST
commands, see the Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.
WARNING: Only use tools provided with OAM Mobile and Social
to change passwords, security credentials, or keys. Specifically, do
not use Oracle Enterprise Manager (EM) for this purpose, because it
is not compatible with the Mobile and Social credential store.
Understanding Social Identity Configuration
50-2 Administrator's Guide for Oracle Access Management
50.2 Understanding Social Identity Configuration
The Welcome to Mobile and Social - Social Identity configuration page is divided into
separate panels that can be expanded and collapsed by clicking the arrow button in
the top left corner of the panel. The following sections contain more information about
the Social Identity panels.
■Understanding Social Identity Providers
■Understanding Service Provider Interfaces
■Understanding Application Profiles
50.2.1 Understanding Social Identity Providers
The Social Identity Providers panel is used to edit the (preconfigured) configuration
details for Identity Providers such as Google, Facebook, Twitter, and the like. Once
established, you should not need to modify these settings very often.
You can also define configuration details for Social Identity Providers that you add
yourself by implementing the
oracle.security.idaas.rp.spi.IdentityProvider
Java interface. For information about adding additional Social Identity Providers, see
"Extending the Capabilities of the Mobile and Social Server" in the Developer's Guide for
Oracle Access Management.
More information on Social Identity Providers is in Section 50.3, "Defining Social
Identity Providers."
50.2.2 Understanding Service Provider Interfaces
The Service Provider Interface refers to the set of rules that govern the authentication
flow for the specified Application Profile. Mobile and Social provides the following
Service Provider Interfaces.
■DefaultServiceProviderInterface - provides support for web applications that run
on Java-compliant application servers.
■OAMServiceProviderInterface - provides support for web applications that run
on the Access Manager service.
More information on Service Provider Interfaces is in Section 50.4, "Defining Service
Provider Interfaces."
50.2.3 Understanding Application Profiles
An Application Profile defines an application that uses Social Identity Provider
services on the Mobile and Social server. Use this panel to configure mobile
applications, web applications that run on Java-compliant application servers, and
web applications that are integrated with Access Manager to use Social Identity.
■If a web application is not integrated with Access Manager, integrate the Social
Identity login page with the web application. See the "Developing Applications
Using the Social Identity Client SDK" chapter in the Developer's Guide for Oracle
Access Management for details.
Note: A Java developer can write custom implementations of one or
more of the Identity Provider interface contracts. Use the Service
Provider Interfaces section only if you need to add a custom Service
Provider created by a developer.
Defining Social Identity Providers
Configuring Social Identity 50-3
■If the web application is integrated with Access Manager, edit the preconfigured
Application Profile named OAMApplication. When Access Manager and Mobile
and Social are installed together during Oracle Access Management installation,
both products are registered as trusted partners and the preconfigured Application
Profile is included. As a result, you do not need to write code to integrate web
applications that are integrated with Access Manager and Social Identity. The
OAMApplication Application Profile that is included with Mobile and Social is
preconfigured to work with Access Manager and requires only minor
configuration changes to get working in your environment.
More information on Application Profiles is in Section 50.5, "Defining Application
Profiles."
50.3 Defining Social Identity Providers
The Social Identity Provider collects configuration details for Identity Providers such
as Google, Facebook, Twitter, and the like. Once created, you should not need to
modify Social Identity Provider settings very often. The following sections provide
information regarding creating, modifying and deleting Social Identity Providers.
■Creating a Social Identity Provider
■Editing or Deleting a Social Identity Provider
■Generating the Consumer Key and Consumer Secret for OAuth Providers
■Troubleshooting Facebook Social Identity Providers
50.3.1 Creating a Social Identity Provider
Social Identity Providers can also be created using the WebLogic Scripting Tool. See
the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for details.
1. Access the Manage Social Identity page as described in Section 50.1, "Opening the
Manage Social Identity Page."
2. Click Create in the Social Identity Provider panel in the home area.
The Create New Social Identity Provider configuration page displays.
3. Enter values for the Social Identity Provider properties.
■Name - Type a unique name for this Authentication Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
■Social Identity Provider Protocol - Select the Identity Provider Protocol from
the drop down menu.
–OpenID
–OAuth
–Custom
Select Custom to configure a custom Identity Provider. Your choice here will
change the displayed Protocol Attributes and User Attributes Returned panels
to reflect properties more specific to the authentication protocol being used by
the Social Identity Provider - either OpenID or OAuth.
■Implementation Class - Based on the Social Identity Provider Protocol
selection, the appropriate provider-specific implementation of the
Defining Social Identity Providers
50-4 Administrator's Guide for Oracle Access Management
oracle.security.idaas.rp.spi.IdentityProvider
Java interface will be
populated in this field. (If Custom, enter the corresponding implementation
class that should interact with the Identity Provider.) The Mobile and Social
server will use this information to communicate with this Social Identity
Provider.
4. Enter values for the Protocol Attributes properties based on the protocol being
used by the Social Identity Provider previously selected: OpenID (Table 50–1) or
OAuth (Table 50–2). (If Custom, add all values required by the custom Provider
and related to the authentication protocol used.)
■Provide values required by the Identity Provider implementing the OpenID
protocol as specified in Table 50–1.
■Provide values required by the Identity Provider implementing the OAuth
protocol as specified in Table 50–2.
Table 50–1 OpenID Protocol Attributes
Name Values Notes
Yadis Endpoint Must be an absolute
HTTP or HTTPS URL
Type the published URL that accepts
OpenID authentication protocol
messages for this Identity Provider.
Mobile and Social uses this URL to make
user authentication requests.
Hashing Algorithm ■SHA256 is a 256-bit
key length
algorithm
■SHA1 is a 160-bit
key length
algorithm
■None
Choose a signature algorithm. Mobile
and Social uses this value internally to
configure the Session Type and
Association Type properties for
communicating with the Identity
Provider.
Authentication Policy
Choose Yes to request
that an authentication
policy be applied by the
OpenID Provider when
authenticating a user.
Otherwise, choose No.
Usage of PAPE (Provider Authentication
Policy Extension) allows web developers
to request other modifications to the flow,
such as asking that the Identity Provider
re-prompt the User for their password.
Authentication Policy
Maximum Age
Provide a value greater
than or equal to zero
seconds. Specify
0
to
force a password
re-prompt.
Type the maximum length of time in
seconds that a User who has not actively
authenticated can use a login session
before being required to authenticate
using the requested authentication policy.
Use this parameter to ensure that the
login session of the user at the Identity
Provider is recent.
Preferred
Authentication
Policies
Type zero or more URIs separated by a
space that represent authentication
policies that the Identity Provider must
satisfy when authenticating the user. For
example:
http://schemas.openid.net/pape/poli
cies/2007/06/phishing-resistant
http://schemas.openid.net/pape/poli
cies/2007/06/multi-factor
Defining Social Identity Providers
Configuring Social Identity 50-5
Table 50–2 OAuth Protocol Attributes
Name Value Notes
Authorization URL
The Identity Provider's
published OAuth authorization
URL. If an Identity Provider
changes a published OAuth
URL, update this value to
match.
Mobile and Social directs the User to
this URL after the Identity Provider
returns the request token (see
Request Token URL). The Identity
Provider verifies the User's identity,
and the User grants the Identity
Provider permission to release the
User's protected information to the
Mobile and Social server.
Access Token URL
Type the Identity Provider's
published access token URL.
Mobile and Social uses this URL to
request an access token from the
Identity Provider after the User
authorizes the request token (using
the Authorization URL).
Request Token URL
Type the Identity Provider's
published Request Token URL.
(Not applicable to Facebook.)
Mobile and Social uses this URL to
obtain a request token from the
Identity Provider. After the Identity
Provider grants the request token,
the Mobile and Social server directs
the User to the Identity Provider's
Authorization URL. (The term
temporary credentials supplants the
terms request token and request secret
in RFC 5849, The OAuth 1.0 Protocol.)
Profile URL
Type the Identity Provider's
published Profile URL.
Mobile and Social uses this URL to
request User attributes based on a
OAuth access token.
Consumer Key
Type the value that the Mobile
and Social server should use to
identify itself to the Identity
Provider.
See Section 50.3.3, "Generating the
Consumer Key and Consumer
Secret for OAuth Providers" for
information about requesting a
Consumer Key from the Identity
Provider.
Consumer Secret
Type the secret that the Mobile
and Social server should use to
establish ownership of the
Consumer Key.
See Section 50.3.3, "Generating the
Consumer Key and Consumer
Secret for OAuth Providers" for
information about requesting a
Consumer Secret from the Identity
Provider.
Server Time Sync
If the Mobile and Social server
and a remote Identity Provider
are not time synchronized, type
the number of minutes of skew
to add to the current server time
when sending requests to the
remote Provider. This field
accepts both positive and
negative integers.
Typically LinkedIn requires
synchronized server time values.
Not applicable for Facebook or
Twitter.
In the Attribute Name column type
the local application attribute name
that should be assigned to the
attribute name returned by the
OpenID Identity Provider. In the
Attribute Schema Name column,
type the URL where the Mobile and
Social server can request user data
from the Identity Provider.
If you add attributes in the Attribute
Name column that the Identity
Provider does not support, those
attributes will not be available in
Mobile and Social.
Defining Social Identity Providers
50-6 Administrator's Guide for Oracle Access Management
5. Add values to the User Attributes Returned panel based on the Social Identity
Provider Protocol previously selected: OpenID, OAuth or Custom.
■OpenID: In the Attribute Name column type the local application attribute
name that should be assigned to the attribute name returned by the Identity
Provider. In the Attribute Schema Name column, type the URL where the
Mobile and Social server can request user data from the Identity Provider. If
you add attributes in the Attribute Name column that the Identity Provider
does not support, those attributes will not be available in Mobile and Social.
Table 50–3, " User Attributes Returned By Google" and Table 50–4, " User
Attributes Returned By Yahoo" lists the user attributes supported by Google
and Yahoo.
■OAuth: Specify the User Attributes that the OAuth Identity Provider should
return. In the Attribute Name column type the local application attribute
name that corresponds to the attribute name returned by the Identity Provider.
In the Attribute Schema Name column, type the Identity Provider attribute
name. For OAuth Providers, Attribute Name values and Attribute Schema
Name values are usually the same.
Table 50–3 User Attributes Returned By Google
Attribute Description
country Requests the user's home country. Must be set to:
http://axschema.org/contact/country/home
email Requests the user's Gmail address. Must be set to:
http://axschema.org/contact/email
firstname Requests the user's first name. Must be set to:
http://axschema.org/namePerson/first
language Requests the user's preferred language. Must be set to:
http://axschema.org/pref/language
lastname Requests the user's last name. Must be set to:
http://axschema.org/namePerson/last
Table 50–4 User Attributes Returned By Yahoo
Attribute Description
gender Requests the user's gender. Must be set to:
http://axschema.org/person/gender
email Requests the user's e-mail address. Must be set to:
http://axschema.org/contact/email
fullname Requests the user's full name. Must be set to:
http://axschema.org/namePerson
language Requests the user's preferred language. Must be set to:
http://axschema.org/pref/language
nickname Requests the user's preferred name. Must be set to:
http://axschema.org/namePerson/friendly
Timezone Requests the user's preferred time zone. Must be set to:
http://axschema.org/pref/timezone
Defining Social Identity Providers
Configuring Social Identity 50-7
Table 50–5, " User Profile Attributes Returned By Foursquare" and Table 50–6,
" User Profile Attributes Returned By Windows Live" lists the user attributes
supported by Foursquare and Windows Live.
■Custom: In the Attribute Name column type the local application attribute
name that should be assigned to the attribute name returned by the Custom
Identity Provider. In the Attribute Schema Name column, type the URL
where the Mobile and Social server can request user data from the Identity
Provider.
6. Click Create to create the Social Identity Provider configuration object.
50.3.2 Editing or Deleting a Social Identity Provider
To edit or delete a Social Identity Provider, select the Provider in the panel and click
Edit or Delete on the panel's tool bar. See Section 50.3.1, "Creating a Social Identity
Provider" for attribute descriptions.
Note: LinkedIn does not return an e-mail address or an unencrypted
login ID when it returns User Identity attributes to Mobile and Social.
Please note this limitation when using Identity attributes from
LinkedIn to pre-populate the registration form for Users.
Table 50–5 User Profile Attributes Returned By Foursquare
Attribute Description
id Requests the user's ID.
firstname Requests the user's first name.
lastname Requests the user's last name.
contact.email Requests the user's email address.
homecity Requests the user's home city.
gender Requests the user's gender.
photo Requests the user's photo.
Table 50–6 User Profile Attributes Returned By Windows Live
Attribute Description
id Requests the user's ID.
first_name Requests the user's first name.
last_name Requests the user's last name.
name Requests the user's name.
link Requests the user's link.
email.preferred Requests the user's preferred e-mail address.
gender Requests the user's gender.
locale Requests the user's local.
updated_time Requests the updated time.
Defining Social Identity Providers
50-8 Administrator's Guide for Oracle Access Management
50.3.3 Generating the Consumer Key and Consumer Secret for OAuth Providers
The following sections describe how to generate the Consumer Key and Consumer
Secret for the Social Identity Providers that support the OAuth protocol.
■Generating a Consumer Key and Consumer Secret for Facebook
■Generating a Consumer Key and Consumer Secret for Twitter
■Generating a Consumer Key and Consumer Secret for LinkedIn
■Generating a Consumer Key and Consumer Secret for Foursquare
■Generating a Consumer Key and Consumer Secret for Windows Live
■Generating a Consumer Key and Consumer Secret for Google
50.3.3.1 Generating a Consumer Key and Consumer Secret for Facebook
This section describes how to generate a Consumer Key and Consumer Secret for
Facebook.
1. Open the following URL in a web browser:
https://developers.facebook.com/apps
2. Click Create New App.
3. Complete the Create New App form.
Facebook creates the application and assigns it a unique App ID and App Secret.
4. Complete the information in the Basic Info section.
In the Select how your application integrates with Facebook section, select
Website with Facebook Login.
5. In the Site URL field, provide the URL where the Mobile and Social Server can be
reached. For example:
http://
OAM-Hosted-Machine
:
Port
/
6. Click Save Changes.
7. From the Mobile and Social Console, open the "Social Identity Providers" >
"Facebook" configuration page as described in section Section 50.3.2.
8. Paste the App ID in the Consumer Key field and paste the App Secret in the
Consumer Secret field.
Click Apply to save your changes.
50.3.3.2 Generating a Consumer Key and Consumer Secret for Twitter
This section describes how to generate a Consumer Key and Consumer Secret for
Twitter.
1. Open the following URL in a web browser:
https://dev.twitter.com/apps/new
2. Complete the Create an application form.
Note: The steps in this section are accurate as of the date that this
documentation was published. The steps required to create a
Consumer Key and Consumer Secret using the Facebook, Twitter, and
LinkedIn web sites are subject to change at any time.
Defining Social Identity Providers
Configuring Social Identity 50-9
In the Callback URL field provide the URL where the Mobile and Social Server
can be reached. For example:
http://
OAM-Hosted-Machine
:
Port
/oic_rp/return
Twitter creates the application and assigns it a unique Consumer key and
Consumer secret.
3. (Optional) Configure your Twitter application as needed and save your changes.
4. From the Mobile and Social Console, open the "Social Identity Providers" >
"Twitter" configuration page as described in section Section 50.3.2.
5. Paste the Consumer Key in the Consumer Key field and paste the Consumer
Secret in the Consumer Secret field.
Click Apply to save your changes.
50.3.3.3 Generating a Consumer Key and Consumer Secret for LinkedIn
This section describes how to generate a Consumer Key and Consumer Secret for
LinkedIn.
1. Open the following URL in a web browser:
https://www.linkedin.com/secure/developer?newapp=
2. Complete the Add New Application form.
In the OAuth User Agreement section, add the URL in the OAuth Redirect URL
field where the Mobile and Social Server can be reached. For example:
http://
OAM-Hosted-Machine
:
Managed Server Port
/
3. Click Add Application.
LinkedIn creates the application and assigns it a unique API Key and Secret Key.
4. From the Mobile and Social Console, open the "Social Identity Providers" >
"LinkedIn" configuration page as described in section Section 50.3.2.
5. Paste the API Key in the Consumer Key field and paste the Secret Key in the
Consumer Secret field.
Click Apply to save your changes.
50.3.3.4 Generating a Consumer Key and Consumer Secret for Foursquare
This section describes how to generate a Consumer Key and Consumer Secret for
Foursquare.
1. Open the following URL in a web browser:
https://foursquare.com/developers/register
2. Fill in the application name and website URL.
3. Enter the URL where the Mobile and Social Server can be reached in the Callback
URL field.
For example:
http://
OAM-Hosted-Machine
:
Port
/
4. Save your changes.
From the screen that is displayed, copy the 'Client ID' and 'Client secret' codes.
Defining Social Identity Providers
50-10 Administrator's Guide for Oracle Access Management
5. From the Mobile and Social Console, open the "Social Identity Providers" >
"Foursquare" configuration page as described in section Section 50.3.2.
6. Paste the Client ID in the Consumer Key field and the Client Secret in the
Consumer Secret field and click Apply to save your changes.
50.3.3.5 Generating a Consumer Key and Consumer Secret for Windows Live
This section describes how to generate a Consumer Key and Consumer Secret for
Windows Live.
1. Open the following URL in a web browser:
https://manage.dev.live.com/
2. Sign in with your Windows Live ID and password.
3. Click Create Application.
4. Fill in the application name.
5. Read and accept the terms of use.
From the screen that is displayed, copy the 'Client ID' and 'Client secret' codes.
6. From the Mobile and Social Console, open the "Social Identity Providers" >
"Windows Live" configuration page as described in section Section 50.3.2.
7. Paste the Client ID in the Consumer Key field and the Client Secret in the
Consumer Secret field and click Apply to save your changes.
50.3.3.6 Generating a Consumer Key and Consumer Secret for Google
This section describes how to generate a Consumer Key and Consumer Secret for
Google.
1. Open the following URL in a web browser:
https://code.google.com/apis/console
2. Under APIs & auth (on the left side) click Credentials.
3. Under OAuth click Create new Client ID.
The Create Client ID form opens.
4. Complete and submit the form.
The new Client ID and secret are added.
5. From the Mobile and Social Console, open the "Social Identity Providers" >
"Google" configuration page as described in section Section 50.3.2.
6. Paste the Client ID in the Consumer Key field and the Client Secret in the
Consumer Secret field.
Click Apply to save your changes.
50.3.4 Troubleshooting Facebook Social Identity Providers
This section documents known configuration issues that affect the Facebook Social
Identity Provider.
■Configuring WebLogic Server for Facebook Compatibility
■Configuring WebLogic Server 10.3.5 and Older for Facebook Compatibility
Defining Service Provider Interfaces
Configuring Social Identity 50-11
50.3.4.1 Configuring WebLogic Server for Facebook Compatibility
Follow these steps to configure WebLogic Server to support Facebook.
1. Open the WebLogic Console.
http://
host
:
port
/console
2. Choose Domain > Environment > Servers > Managed Server.
3. Click the SSL tab, then click Advanced.
4. Click Lock and Edit configuration.
5. Change the Host Name Verifier to None.
6. Restart the Managed Server.
If Host Name Verifier is not set to None, the following error may display when trying
to access a protected resource if Facebook is the Identity Provider:
Exception in processRequest method: oracle.security.idaas.rp.RPException:
oracle.security.idaas.rp.RPException: Request failed:
50.3.4.2 Configuring WebLogic Server 10.3.5 and Older for Facebook Compatibility
Facebook's SSL certificate contains
*.facebook.com
as a wildcard host identifier.
WebLogic Server versions 10.3.5 and older have a problem verifying host names that
contain wildcards that can lead to communication failures between Facebook and
installations of Oracle Access Management Mobile and Social deployed on WebLogic
Server. The following workarounds are available.
■If using WebLogic Server versions 10.3.5 or older, follow these steps:
1. In the administration console, choose servers > oam_server_where_Mobile_and_
Social_is_deployed > SSL > Advanced.
2. Change Hostname Verifier to NONE.
■This WebLogic Server bug has been fixed in version 10.3.6 as follows: A new
custom host name verifier
SSLWLSWildcardHostnameVerifier
was implemented,
derived from the default host name verifier, so that it supports everything the
default host name verifier does, including SANs. You must configure your
WebLogic server to use this custom host name verifier if support for wildcard
certificates is required during the SSL handshake. One option is to use the
following WebLogic property:
-Dweblogic.security.SSL.hostnameVerifier=weblogic.security.utils.SSLWLSWildca
rdHostnameVerifier
50.4 Defining Service Provider Interfaces
The Service Provider Interface refers to the set of rules that govern the authentication
flow for the specified Application Profile. Mobile and Social provides the following
Service Provider Interfaces.
■DefaultServiceProviderInterface - provides support for web applications that run
on Java-compliant application servers.
■OAMServiceProviderInterface - provides support for web applications that run
on the Access Manager service.
If necessary, a Java developer can write custom implementations of one or more of the
Identity Provider interface contracts. This section includes the following topics:
Defining Service Provider Interfaces
50-12 Administrator's Guide for Oracle Access Management
■Creating a Service Provider Interface
■Editing or Deleting an Service Provider Interface
■Adding a Custom Service Provider Interface Implementation
50.4.1 Creating a Service Provider Interface
1. Open the Social Identity Home Page in the Oracle Access Management Console as
described in Section 50.1, "Opening the Manage Social Identity Page."
2. Click Create in the Service Provider Interface panel in the home area.
The Create New Service Provider Interface configuration page displays.
3. Enter values for the Service Provider Interface properties.
■Name - Type a unique name for this Authentication Service Provider.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
4. Enter values for the Interface Information properties as specified in Table 50–7.
5. Click Create to create the Service Provider Interface configuration object.
50.4.2 Editing or Deleting an Service Provider Interface
To edit or delete a Service Provider Interface, select the Provider in the panel and click
Edit or Delete on the panel's tool bar. See Section 50.4.1, "Creating a Service Provider
Interface" for attribute descriptions.
50.4.3 Adding a Custom Service Provider Interface Implementation
To add a custom interface implementation, create a new Social Identity Provider and
choose a mix of custom and/or default implementation classes as needed to meet your
business objectives. See "Developing Applications Using the Social Identity Client
SDK" in the Developer's Guide For Oracle Access Management for information.
Table 50–7 Service Provider Interface Information Properties
Name Notes
IDP Selector
Choose the IDP Selector implementation class for the
custom Provider.
NOTE: The console will not check the validity of the
provided class.
Post IDP Selector
Choose the Post IDP Selector implementation class for the
custom Provider.
IDP Interaction Provider
Choose the IDP Interaction Provider implementation class
for the custom Provider.
Registration Status Check
Choose the Registration Status Check implementation class
for the custom Provider.
Session Creation Provider
Choose the Session Creation Provider implementation class
for the custom Provider.
Defining Application Profiles
Configuring Social Identity 50-13
50.5 Defining Application Profiles
An Application Profile defines an application that uses Social Identity Provider
services on the Mobile and Social server. Use this panel to configure mobile
applications, web applications that run on Java-compliant application servers, and
web applications that are integrated with Access Manager to use Social Identity.
■If a web application is not integrated with Access Manager, integrate the Social
Identity login page with the web application. See the "Developing Applications
Using the Social Identity Client SDK" chapter in the Developer's Guide for Oracle
Access Management for details.
■If the web application is integrated with Access Manager, edit the preconfigured
Application Profile named OAMApplication. When Access Manager and Mobile
and Social are installed together during Oracle Access Management installation,
both products are registered as trusted partners and the preconfigured Application
Profile is included. As a result, you do not need to write code to integrate web
applications that are integrated with Access Manager and Social Identity. The
OAMApplication Application Profile that is included with Mobile and Social is
preconfigured to work with Access Manager and requires only minor
configuration changes to get working in your environment.
Typically, when a WebGate is configured in Access Manager, an Application Domain is
created involving resources and policies. In Mobile and Social, OAMApplication is the
Application Profile that corresponds to the Access Manager Application Domain. So, if
you define 10 WebGates in Access Manager, and each represents an application that
needs to use Mobile and Social for user authentication, use OAMApplication as a
template to create 10 corresponding Application Profiles with names that match the 10
Application Domains.
This section provides help for the Create Application Profile wizard and the Edit
Application Profiles page.
The following sections contain more information.
■Creating an Application Profile
■Editing or Deleting an Application Profile
50.5.1 Creating an Application Profile
1. Access the Manage Social Identity page as described in Section 50.1, "Opening the
Manage Social Identity Page."
2. Click Create in the Application Profiles panel in the home area.
The Create New Application Profile configuration page displays.
3. Enter values for the general Application Profile properties.
■Name - Displays the context name of the web application or mobile
application. This name should match the name registered with the agent
protecting the resource. If the application is integrated with Access Manager,
Note: When you install a WebGate to protect an application in
Access Manager, the WebGate setup automatically creates an
Application Domain that has LDAP as the authentication mechanism.
To use Mobile and Social authentication, change the Authentication
Scheme to OICScheme.
Defining Application Profiles
50-14 Administrator's Guide for Oracle Access Management
the Application Domain name as defined in Access Manager is displayed. This
should be the same value as that of the Name defined in the Mobile and Social
Services Application Profile, if applicable.
■Description - (Optional) Type a short description that will help you or another
Administrator identify this service in the future.
■Shared Secret - For mobile or web applications, provide the security secret
that the application and the Mobile and Social server share to facilitate secure
communication. This is needed to use the Mobile and Social user registration
functionality. It can be any string.
■Return URL - This value is not used if the application is a mobile application
but it is a mandatory attribute. So for mobile applications, use the Mobile
Application Return URL. For web applications, provide the URL that Mobile
and Social should use to send back authentication responses. If the application
is integrated with Access Manager, provide the following URL which Mobile
and Social uses to send back authentication responses:
http://oam-host:port/oam/server/dap/cred_submit
■Mobile Application Return URL - For mobile applications, provide the URL
that Mobile and Social should use to send back authentication responses. This
value should match the mobile application's return URL.
4. Enter values for the following Application Profile configuration properties.
■Login Type - If configuring a non-mobile application, choose Local
Authentication and Social Identity Provider Authentication if the User login
page should let users choose between authenticating locally and
authenticating using an Identity Provider. If configuring either a mobile
application or a non-mobile application, choose Social Identity Provider
Authentication only if the User login page should not give the users the
option of authenticating locally.
The Mobile and Social login page supports Social Identity Provider
Authentication only. Local login is not supported.
■Enable Browser Popup - Choose Yes if the login page should open in a
pop-up window. This value should be false if this is a mobile application.
■User Registration - Choose Enabled to allow users to register with the
application after authenticating against a Social Identity Provider. The login
page for the application will show a User Registration form and prompt the
User to register. The User can complete the form and register, or click the Skip
Registration button. Choose Disabled if the login page should not show a
User Registration form and should not prompt the User to register.
■Registration URL - Type the URL that the system should forward the User to
so that the User can register for a local account. Typically the User is directed
to a form with fields that correspond to the registration service attributes
defined in the Application Profile. An encrypted token with attribute objects
in a map are also passed to the client application as a parameter. These
Note: If configuring a mobile application, choose Social Identity
Provider Authentication only from the Login Type menu. The Local
Authentication and Social Identity Provider Authentication option
is not valid for mobile applications.
Defining Application Profiles
Configuring Social Identity 50-15
attributes are used to pre-populate the registration page with the User's profile
data.
■UserID Attribute - Type the attribute name that is used to uniquely identify
the User. This attribute name should also appear in the Application User
Attribute section of the Application Profile Configuration page.
■User Profile Service Endpoint - Choose the User Profile Service endpoint that
the application should use. The User Profile Service directs the application to
the LDAP Directory service where the User will be created upon registration.
User Profile Service endpoints are configured in Mobile and Social Services.
■Authentication Service Endpoint - The Authentication Service endpoint
determines how the user should be authenticated when local login is
requested. If a mobile application, choose InternetIdentityAuthentication or
any custom authentication of the type InternetIdentityAuthentication.
–Choose /oamauthentication to forward the authentication request to
Access Manager. The authentication scheme associated with the Mobile
and Social Authentication Policy inside the IAMSuite Application domain
determines how the user will be authenticated.
–Choose /internetidentityauthentication to use the Identity Store specified
in the corresponding endpoint.
■Application Profile Properties - Click Add to add Application Profile
attributes to the table. The following are supported.
–
app.passwd.field
- Encrypts the password on the registration page. Add
password
as the value. To mask the password with asterisks (*) on the
registration page, add the
app.passwd.field
property and add
password
as the value.
–
oic.app.idp.oauth.token
- Instructs Mobile and Social to include the
OAuth Access Token as part of the final redirect to the application. Add
true
as the value. Only applies if the User selected an OAuth provider
(Facebook, Twitter, LinkedIn).
–
oic.app.user.token
- Creates a JWT User Token when a User
authenticates with an Identity Provider and gets redirected back to the
application. Add
true
as the value. This token contains the Identity
Provider related URI and the User identifier value on record with the
Identity Provider. Use this token to access other protected Mobile and
Social REST services, for example the User Profile REST Service.
5. Click Add to add the Application User Attributes that the Social Identity Provider
should return to the application after authentication.
Configure more details for these attributes in the following Registration Service
Details with Application User Attribute Mapping step.
6. Add rows to the Registration Service Details with Application User Attribute
Mapping table to map local (User) registration attributes to the application
attributes provided by the Social Identity Provider.
Add any additional Application User Attributes in the previous step first. The
following definitions apply to the Registration Service Details with Application
User Attribute Mapping table properties.
■Registration Service Attribute - Choose from the menu the registration
service attribute to configure.
Integrating Social Identity With Mobile Applications
50-16 Administrator's Guide for Oracle Access Management
■User Attribute Display Name - For the attribute in the Registration Service
Attribute column, type the name that should appear on the User registration
form. This is the attribute name that the user sees.
■Read-only - Select to prevent the user from updating the attribute value. The
attribute value will display grayed-out on the form and the user will be
blocked from making updates.
■Mandatory - Select to make the attribute a required item on the user
registration form.
■Application User Attribute - Choose the attribute that corresponds to the
attribute in the Registration Service Attribute column.
7. Click Next to configure the Service Provider Interface.
The Service Provider Interface page displays.
8. Choose the DefaultServiceProviderInterface from the drop down menu.
For information about the Service Provider Interface, see Section 50.4, "Defining
Service Provider Interfaces."
9. Click Next to configure the Social Identity Provider.
The Social Identity Provider page displays. Use this section to select one or more
Social Identity Providers, and to map local application user attributes to Social
Identity Provider attributes. For example, to use an e-mail address as the unique
local user identifier when Google is the Social Identity Provider:
a. Select Google in the Social Identity Provider column.
A two-column table opens.
b. Create the mapping as follows:
a. Choose uid in the first row of the Application User Attribute column.
b. Choose e-mail in the Social Identity Provider User Attributes column.
10. Click Finish to create the Application Profile.
50.5.2 Editing or Deleting an Application Profile
To edit or delete an Application Profile, select the Profile in the panel and click Edit or
Delete on the panel's tool bar. See Section 50.5.1, "Creating an Application Profile" for
attribute descriptions.
50.6 Integrating Social Identity With Mobile Applications
You can configure Mobile and Social Services to allow applications on mobile devices
to authenticate using Social Identity. Any application that needs to use Social Identity
must have a corresponding Application Profile in Social Identity. If you want a mobile
application to use Social Identity, the application needs to have a profile under Social
Identity and under Mobile and Social Services.
Note: Do not select the Read-only option for First Name and Last
Name if Yahoo is the Social Identity Provider. Yahoo does not return
values for these attributes. Selecting the Read-only option will cause
user registration to fail and an exception error to display.
Linking Social Identity Provider Accounts
Configuring Social Identity 50-17
1. Under Social Identity, open the Create Application Profile wizard.
2. Populate the Application Profile attributes with values applicable to the mobile
application being protected and click Next.
See Section 50.5.1, "Creating an Application Profile" for attribute definitions.
3. Select the Service Provider Interface and click Next.
See Section 50.4, "Defining Service Provider Interfaces."
4. Select the Social Identity Provider and click Next.
See Section 50.2, "Understanding Social Identity Configuration."
5. View the Application Profile summary and click Finish to create the Application
Profile.
6. Under Mobile and Social Services, open the Create Service Domain wizard.
If modifying an existing Service Domain, open it for editing. See Section 49.4,
"Defining Service Profiles" for information.
7. Complete the form as follows.
■For Type, select Mobile Application.
■For Authentication Scheme, select Social Identity Authentication.
See Section 49.7, "Defining Service Domains" for information.
8. In the Application Profile Selection section, add the Mobile and Social Services
Application Profile that represents the mobile application being protected and
choose if it will participate in mobile SSO as an agent, a client or not at all.
Select the appropriate Application Profile by browsing existing Profiles or entering
a name. The Application Profile must already be created. (To create Mobile and
Social Services Application Profiles, see Section 49.6, "Defining Application
Profiles"; for Social Identity Application Profiles, see Section 50.5, "Defining
Application Profiles.")
9. Click Next to select (or create) a Service Profile.
See Section 49.4, "Defining Service Profiles."
10. Click Next to select the Service Protection.
For example, use InternetIdentityAuthentication as the authentication service to
protect the User Profile Services.
11. Click Next to view the Create Service Domain summary.
12. Click Finish to create the Service Domain.
50.7 Linking Social Identity Provider Accounts
Social Identity Account Linking allows users to link several Internet identities together
with an existing or new local user account. The following sections contain information
about how to enable and use this feature.
Note: See "Integrating Social Identity With a Mobile Application" in
the "Developing Applications Using the Social Identity Client SDK"
chapter of the Developer's Guide for Oracle Access Management for more
information.
Linking Social Identity Provider Accounts
50-18 Administrator's Guide for Oracle Access Management
■Section 50.7.1, "Using Social Identity Provider Account Linking"
■Section 50.7.2, "Configuring Social Identity Provider Account Linking"
50.7.1 Using Social Identity Provider Account Linking
The following sequence documents the steps in the Account Linking Flow.
1. The user lands at the Mobile and Social Login Page.
2. The user is prompted to log in locally or with an Identity Provider.
3. The user selects Identity Provider Login (for example, Google) and enters
password credentials.
Once authenticated (and if determined that the user is already registered with a
local account), the user is automatically logged in as the local user and then
presented with a Linked Accounts page that has the option to link the Identity
Provider to this local account.
By clicking the link next to Google, the user will link the local account to the
Google Identity Provider account. The user may choose to link and unlink
additional Identity Providers from this page. Figure 50–1 illustrates this scenario.
Figure 50–1 Social Identity Account Linking
Additional scenarios include:
■If the user logs into an Identity Provider account without having a local account
and selects the Register option after Identity Provider authentication, an enterprise
ID will be created and the Identity Provider account will be automatically
associated with this enterprise ID. In other words, the user logs in with the
Identity Provider Login ID and Mobile and Social creates a local account with the
same user name as the Identity Provider Login ID. The user is then redirected to
the linked accounts page associated with the newly created local account. From
this page, the user may choose to link or unlink Identity Provider accounts or
return back to the application.
User Clicks Login
Return to user
1
9
Internet Identity
(Google, Yahoo, etc.)
User logs in using
Enterprise ID
IDP account
successfully linked
IDP account is
linked to Enterprise
account
Mobile Services
(REST)
6
7
Internet Identity
Services (RP)
2
3
Third- Party
Application
Authenticated
user, requests
account linking
via IDP
Account linking
response
complete
8
User
authenticated
by IDP
5
4
User is
redirected to IDP
for authentication
Linking Social Identity Provider Accounts
Configuring Social Identity 50-19
■If the user logs in using the local account only, in the app the user has to choose
the linked accounts page displaying Identity Providers. From this page, the user
may choose to link (or unlink) Identity Provider accounts or return back to the
app. When the accounts are linked, Social Identity will detect that the user is
linked to a local account even when the user logs in using Identity Provider
credentials.
50.7.2 Configuring Social Identity Provider Account Linking
The properties documented in Table 50–8 need to be configured to use Account
Linking. They are set in the Application Profile Properties table.
The following should also be taken into account when enabling Account Linking.
■Ensure the proxy setting is correct. This setting can be found by navigating the
Oracle Access Management Console: System Configuration > Mobile & Social >
Mobile & Social Settings.
■Images for Identity Provider icons or logos can only be specified using WLST. If
the image path starts with
http
, the image is retrieved from the location using the
img
tag. Otherwise, it uses the internal references that come with Social Identity.
■Ensure that the
username
attribute and the account linking attribute are different.
If they are the same then it can cause inconsistent behavior. For example, you can
set the
username
attribute to
uid
and the linking attribute to
mail
.
■Set the Shared Secret for the application. Set the Auth Scheme on the
authentication policy to point to OICScheme and ensure that the settings are
Note: The linked accounts page can be provided by the relying party
(by way of Social Identity) or a third-party application that hosts the
options for linking accounts. In either case, the following items will
need to be provided:
■An API call (for example,
AccountLinkingHelper.getProviders
()
) listing the various Identity Providers that can be linked. This
will include linkage status and IDs.
■An RP-specific account linking page (for example,
linkedAccounts.jsp
) that will display the various Identity
Providers that can be linked. This will include linkage status and
IDs.
Table 50–8 Account Linking Properties
Property Details
app.acct.link.enabled
This configuration property is set to true to enable Account
Linking.
app.acct.link.attr
Specify the OAM entity attribute name that corresponds to the
LDAP attribute where the multi-valued account linking
information is to be stored. Use the OAM entity attribute name
defined in the IDS Profile. To look up this name in the OAM
console, choose Configuration > User Identity Stores > IDS
Profiles. Select the identity profile and click edit, then click
Entity Attributes. The Entity Attributes page lists both the entity
attribute names defined by OAM, and the corresponding LDAP
physical attributes. Use the OAM name listed in the first
column. Note: This value is case-sensitive.
Linking Social Identity Provider Accounts
50-20 Administrator's Guide for Oracle Access Management
correct. For example, the
MatchLDAPAttribute
should match the
username
attribute set in the relying party Application Profile, typically
uid
.
51
Configuring Social Identity System Settings 51-1
51
Configuring Social Identity System Settings
[33]
This chapter discusses system configuration tasks for the Oracle Access Management
Social Identity. It contains the following sections.
■Accessing the Social Identity Settings Interface
■Logging and Auditing
■Deploying Mobile and Social With Oracle Access Manager
■Configuring Social Identity After Running Test-to-Production Scripts
■Configuring Social Identity for High Availability (HA)
■Enabling the REST Client to Specify the Tenant Name
51.1 Accessing the Social Identity Settings Interface
Use the Social Identity Settings page in the Oracle Access Management Console to
configure system level settings.
Follow this procedure to access the Manage Social Identity page.
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. Select Social Identity from the View menu in the Settings section.
51.1.1 Understanding the Social Identity Settings Page
This section describes the form fields on the Social Identity Settings page.
Configuration Settings for Social Identity
Configure the following Social Identity settings if a proxy server is in place between
the Social Identity server and an Identity Provider.
■Proxy URL - Choose the protocol to use to connect to the proxy server (HTTP or
HTTPS), then type the proxy server host name and port number.
■Proxy Authentication - Type the user name and password required to authenticate
with the proxy server.
Note: You can perform many Social Identity configuration tasks
from the command line using the WebLogic Scripting Tool (WLST).
For more information, see the Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
Logging and Auditing
51-2 Administrator's Guide for Oracle Access Management
■SAE Token Validity Period - Type the number of seconds that the system should
wait before expiring the Secured Attribute Exchange token. SAE is the default
scheme used to secure communication between the Social Identity server and any
application integrating directly with Social Identity.
51.2 Logging and Auditing
For information about Fusion Middleware logging, see the "Monitoring Oracle Fusion
Middleware" chapter in the Oracle Fusion Middleware Administrator's Guide.
For information about Fusion Middleware auditing, see the "Configuring and
Managing Auditing" chapter in the Oracle Fusion Middleware Application Security Guide.
51.3 Deploying Mobile and Social With Oracle Access Manager
Mobile and Social can be configured for use with either Oracle Access Manager 10g or
11gR1 PS1. For this to work, however, Oracle Access Manager and Mobile and Social
need to be installed on different servers in different domains. Mobile and Social and
Oracle Access Manager then need to be configured to work together. The following
procedure documents how to do this using Oracle Access Manager 11gR1 PS1. Before
you Begin - Install Social Identity on Host 1 and Oracle Access Manager 11gR1 PS1 on
Host 2.
1. Log on to the Oracle Access Management Console on Host 2 and create a Webgate
profile for Social Identity using the default settings.
2. In Social Identity, create an Authentication Service Provider for Oracle Access
Manager 11.1.1.5.
See Section 49.3.1.3, "Creating an Authentication Service Provider," for
instructions.
Set the Attributes as described in the following table.
3. In Social Identity, create a Service Profile for the Authentication Service Provider
that you created in the previous step.
See Section 49.4, "Defining Service Profiles," for instructions.
4. In Social Identity, create a Service Domain.
See Section 49.7.1, "Creating a Service Domain," for instructions.
Table 51–1 Attribute Settings for an Oracle Access Manager 11gR1 PS1 Authentication
Service Provider
Name Value
OAM_VERSION OAM_10G
DEBUG_VALUE 0
TRANSPORT_SECURITY OPEN
OAM_SERVER_1 host:port
OAM_SERVER_1_MAX_CONN 4
OAM_SERVER_2 host:port
OAM_SERVER_2_MAX_CONN 4
AuthNURL wl_authen://Authen/Basic
Deploying Mobile and Social With Oracle Access Manager
Configuring Social Identity System Settings 51-3
5. Merge the
cwallet.sso
file on Host 2 with the
cwallet.sso
file on Host 1 as
follows:
a. Copy
cwallet.sso
from Host 2 to Host 1.
b. On Host 1 type
# mkdir /tmp/oam /tmp/oic
# cp <host>/cwallet.sso /tmp/oam
# cp config/fmwconfig/cwallet.sso /tmp/oic
c. Create file
merge-creds.xml
:
<?xml version="1.0" encoding="UTF-8" standalone='yes'?>
<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_
1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/oracleas/schema/11/jps-config-1
1_1.xsd"
schema-major-version="11" schema-minor-version="1">
<serviceProviders>
<serviceProvider
class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvide
r"
name="credstoressp" type="CREDENTIAL_STORE">
<description>File-based credential provider</description>
</serviceProvider>
</serviceProviders>
<serviceInstances>
<!-- Source file-based credential store instance -->
<serviceInstance location="/tmp/oam" provider="credstoressp"
name="credential.file.source">
</serviceInstance>
<!-- Destination file-based credential store instance -->
<serviceInstance location="/tmp/oic" provider="credstoressp"
name="credential.file.destination">
</serviceInstance>
</serviceInstances>
<jpsContexts>
<jpsContext name="FileSourceContext">
<serviceInstanceRef ref="credential.file.source"/>
</jpsContext>
<jpsContext name="FileDestinationContext">
<serviceInstanceRef ref="credential.file.destination"/>
</jpsContext>
</jpsContexts>
</jpsConfig>
d. Set the path variable to include
$MW_HOME/oracle_common/bin:$MW_
HOME/oracle_common/common/bin
e. Execute the command to merge the
cwallet.sso
files:
# wlst.sh
wlst:/> migrateSecurityStore(type="credStore",
configFile="/tmp/mergecreds.xml",src="FileSourceContext",dst="FileDestinati
onContext")
f. Copy the merged file to
config/fmwconfig
:
# cp /tmp/oic/cwallet.sso /scratch/kerwin/wls10/user_projects/domain/base_
domain/cfnfig/fmwconfig
Configuring a Webgate to Support Social Identity
51-4 Administrator's Guide for Oracle Access Management
g. Restart the OAM Server on Host 1.
51.4 Configuring a Webgate to Support Social Identity
This section describes how to configure a Webgate for use with the OAuth Service. The
Webgate serves as a proxy so that client authorization and token endpoint requests
access the Webgate instead of accessing the Oracle Access Management server directly.
These steps are for WebLogic environments only.
1. Install the Oracle HTTP Server 11g Webgate for OAM using the instructions in
Installing Webgates for Oracle Access Manager.
2. Configure the Webgate by defining the following resource and creating an
authentication policy and authorization policy.
a. Open the Oracle Access Management console.
b. Under Access Manager, click Application Domains.
c. Find the target domain and open it for editing.
d. Select the Resources tab.
e. Create the following resource. If you are using the existing IAMSuiteAgent
Host Identifier, the resource is already present and can be searched on using
the Resource URL field.
/ms_oauth/oauth2/ui/**
Click to select the resource, then click the Edit button.
f. Under the Protection heading, choose the following options from the menus
and click Apply:
Protection Level - Protected
Authentication Policy - Protected HigherLevel Policy
Authorization Policy - Protected Resource Policy
These settings allow the Webgate to perform user authentication and user
authorization.
g. Add the following resources and set the Protection Level to Excluded:
/ms_oauth/oauth2/endpoints/**
/ms_oauth/oauth2/oammsui/**
/ms_oauth/style/**
/ms_oauth/img/**
/oam/**
The Webgate does not protect Excluded resources and allows them to be
accessed.
3. Add the following lines to the
mod_wl_ohs.conf
file and restart the Webgate. For
WebLogicPort
, be sure to add the managed port details for your environment.
# the following directive proxies all the OAuth requests
<IfModule weblogic_module>
WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /ms_oauth/*
</IfModule>
Configuring a Webgate to Support Social Identity
Configuring Social Identity System Settings 51-5
# the following directive proxies all the OAM managed server requests.
<IfModule weblogic_module>
WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /oam/*
</IfModule>
4. Update the Access Manager Load Balancing settings as follows:
a. In the Oracle Access Management console, click Configuration at the top of
the window.
b. Select Access Manager from the View menu in the Settings section.
c. In the Load Balancing section, change the OAM Server Host and the OAM
Server Port settings to the Webgate's host and port settings.
d. Click Apply.
5. Complete the following steps.
a. Open
$ORACLE_HOME/ORACLE_IDM1/oam/server/apps/
and locate the
oam-server.ear
file. For example:
cd /scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps
b. Back up the
.ear
file:
cp oam-server.ear oam-server.ear.original
c. Create a temporary directory and go to that directory:
mkdir tmp-ear
cd tmp-ear/
d. Extract the
oam-server.ear
file into the
tmp-ear
directory:
jar -xvf ../oam-server.ear
e. Create another temporary directory inside
tmp-ear
and go to that directory:
mkdir tmp-ms-war
cd tmp-ms-war
You should be in this directory:
/scratch/test/Oracle/Middleware/Oracle_
IDM1/oam/server/apps/tmp-ear/tmp-ms-war
f. Extract the
ms_oauth.war
into the
tmp-ms-war
directory:
jar -xvf ../ms_oauth.war
g. Open the
WEB-INF/web.xml
file for editing and update it by adding comment
tags around the security-constraint as follows:
<!-- BEGIN: Comment the following security constraint if either the OAM
Webgate is front-ending OAM in a WebSphere setup or if the WebLogic server
Domain Agent is not used.
<security-constraint>
<web-resource-collection>
<web-resource-name>OAuthSecuredResources</web-resource-name>
Configuring Social Identity After Running Test-to-Production Scripts
51-6 Administrator's Guide for Oracle Access Management
<url-pattern>/oauth2/ui/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>valid-users</role-name>
</auth-constraint>
</security-constraint>
END of security constraint needing to be commented -->
h. Recreate the
.war
file in the
tmp-ms-war
directory:
jar cvf ms_oauth.war
i. Copy the updated
.war
file to the parent directory, then remove the
tmp-ms-war
directory located in
tmp-ear/
:
cp /scratch/test/Oracle/Middleware/Oracle_
IDM1/oam/server/apps/tmp-ear/tmp-ms-war/ms_oauth.war
/scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/tmp-ear
rm -rf /scratch/test/Oracle/Middleware/Oracle_
IDM1/oam/server/apps/tmp-ear/tmp-ms-war
j. Create the
oam-server.ear
archive in the
tmp-ear
directory:
jar cvf oam-server.ear .
k. Copy the
tmp-ear/oam_server.ear
archive file to the parent directory:
cp /scratch/test/Oracle/Middleware/Oracle_
IDM1/oam/server/apps/tmp-ear/oam-server.ear
/scratch/test/Oracle/Middleware/Oracle_IDM1/oam/server/apps/oam-server.ear
l. Restart the WebSphere server.
The Webgate will now reverse-proxy OAuth URLs as well as OAM managed
server URLs. All authorization and token endpoint requests are now accessed
using the Webgate host and port values instead of the actual OAM host and port
values.
51.5 Configuring Social Identity After Running Test-to-Production Scripts
When moving Social Identity from a test environment to a production environment,
complete the following configuration steps on each production machine after running
the Test-to-Production scripts.
1. In the Oracle Access Management Console, click Application Security.
2. Click Authentication Schemes in the Access Manager section.
3. Find the
OICScheme
scheme and open it for editing.
4. Update the Challenge Redirect URL value to point to the production machine
(not the test machine) and click Apply.
For example:
https://
production_machine
:
port
/oic_rp/login.jsp
5. Run the following WLST command to update the Social Identity credential store
framework (CSF) entry to point from the test machine to the production machine.
createCred(map="OIC_MAP", key=" https://<production machine host>:<production
machine port>/oam/server/dap/cred_submit ", user="="<description>", password="
DCC5332B4069BAB4E016C390432627ED", desc="<description>");
Enabling the REST Client to Specify the Tenant Name
Configuring Social Identity System Settings 51-7
For
password
, use the value from the
RPPartner
entry,
TapCipherKey
attribute in
oam-config.xml
, located in the domain home
/config/fmwconfig
directory on the
production machine.
6. In the Oracle Access Management Console, do the following:
a. Click Mobile Security at the top of the window.
b. Click Mobile and Social Services.
c. In the Application Profiles section, select OAMApplicaton and click Edit. (If
using an application profile name other than OAMApplication, edit that
instead.)
d. Update the Registration URL field host name and port to point to the
production machine.
Click Apply.
51.6 Configuring Social Identity for High Availability (HA)
For information about configuring Social Identity High Availability, see "Configuring
High Availability for Social Identity" in the Fusion Middleware High Availability Guide for
Oracle Identity and Access Management.
51.7 Enabling the REST Client to Specify the Tenant Name
Follow these steps to enable the REST client to specify the tenant name. Refer to
"Specifying the Tenant Name in the Header" in the Developer's Guide for Oracle Access
Management for more information.
1. Navigate to the following directory:
~/OAM-Domain-dir/bin
2. In a text editor, add the following line to the
./startManagedWebLogic.sh
file:
MT_OPTION="-Doracle.multitenant.headername=MY-MT-NAME"
JAVA_OPTIONS="${MY_OPTIONS} ${JAVA_OPTIONS}" export JAVA_OPTIONS
3. Save the file.
Note: If you do not specify the JVM option, the server will expect the
client to use the default header name,
X-ID-TENANT-NAME
.
Enabling the REST Client to Specify the Tenant Name
51-8 Administrator's Guide for Oracle Access Management
Part XII
Par t XII
Managing the Oracle Access Management
OAuth Service
The Oracle Access Management OAuth Service allows organizations to implement the
open standard OAuth 2.0 Web authorization protocol in an Access Manager
environment. OAuth enables a client to access Access Manager protected resources
that belong to another user (that is, the resource owner).
Part IX contains the following chapters:
■Chapter 52, "Understanding OAuth Services"
■Chapter 53, "Configuring OAuth Services"
52
Understanding OAuth Services 52-1
52
Understanding OAuth Services
[34]
OAuth provides a method to exchange identity credentials for an access token. This
token, in return, can be used for granting access of private resources in a user's account
on one service provider site to a second, consumer site without having to divulge the
identity credentials to the consumer site. Oracle Access Management implements the
OAuth Core 2.0 specifications to offer OAuth Services.
This chapter describes the purpose and capabilities of the Oracle Access Management
OAuth Services. It includes the following topics.
■Using Oracle Access Management OAuth Services
■Understanding OAuth Services Authorization for Web Clients
■Understanding OAuth Services Authorization for Mobile Clients
■Understanding the OAuth Services Components
■Understanding OAuth Services Tokens
■Understanding the Authorization and Authentication Endpoints
■Enforcing Access Control
■Understanding Mobile OAuth Services Server-Side Single Sign-on
■Understanding OAuth Services Plug-ins
52.1 Using Oracle Access Management OAuth Services
OAuth is an open standard authorization protocol that provides authentication and
access control between a Client (including mobile apps and Web services) and a
Resource Owner (or Service Provider) on the Web. Oracle Access Management OAuth
Services is based on this standard and designed:
■To address enterprise-level extranet use cases.
■To provide secure mobile access to APIs.
■To leverage built-in Oracle Access Management features (including authentication
schemes, strong authentication, fraud detection, session management and
federated authentication).
■To secure confidential clients with a high level of security.
Oracle Access Management OAuth Services are available for Web clients or for mobile
clients. OAuth Services for Web clients implement the standard OAuth 2.0 use cases.
In this case, the clients rely on a Client ID/Client Password (or secret) to secure itself.
For an example, see
http://tools.ietf.org/html/rfc6749#page-4
.
Understanding OAuth Services Authorization for Web Clients
52-2 Administrator's Guide for Oracle Access Management
Mobile OAuth Services is an extension on top of the standard OAuth specification in
which the identity of the mobile client is secured through application registration, and
a credential specific to the mobile client is included with a request for access. As
mobile clients store passwords on mobile devices, they can not be confidential like
Web clients so the identity of the mobile client is established through device/app
registration before accessing REST or Web services using the OAuth Services Access
Token. Thus, the key difference between the standard Web and mobile OAuth Services
use cases is that the mobile client is secure before it can request an Access Token
(through device/app registration) whereas a standard OAuth Web client uses a
credential like password or an assertion to self identify. Section 53.1, "Enabling OAuth
Services" contains details on how OAuth Services and Mobile OAuth Services are
enabled and configured separately. See the following sections for details on how
OAuth Services works.
■Understanding OAuth Services Authorization for Web Clients
■Understanding OAuth Services Authorization for Mobile Clients
52.2 Understanding OAuth Services Authorization for Web Clients
In the most common OAuth scenario, the Client accessing the protected resource is
issued a different set of credentials than those of the user. (In this case, the user does
not disclose their credentials to the client.) Oracle Access Management OAuth Services
acts as the intermediary Authorization Server, interacting directly with the Client, the
service hosting the user's protected resource (Resource Owner) and the server on
which the resource is located (Resource Server). It issues access tokens to a Client that
has (already) successfully authenticated with the Resource Server - in effect,
authorizing the client to access private resources or activities on the server. A single
Authorization Server instance can issue access tokens accepted by multiple resource
servers.
The following sections describe web-based scenarios in which OAuth Services works.
■Understanding 3-Legged Authorization
■Understanding 2-Legged Authorization
The scenarios introduce the concept of OAuth Services endpoints. For detailed
information on these endpoints, see Understanding the Authorization and
Authentication Endpoints. The scenarios also use terms documented in Understanding
the OAuth Services Components including the following:
■The Resource Owner refers to the user requesting access to a protected resource.
■The Client is the mobile app or Web service through which the Resource Owner is
requesting access to a protected resource.
■OAuth Services refers to the Authorization Server, Oracle Access Management.
■The Resource Server is the machine on which the protected resource is stored. It
can be any website or Web service where restricted resources are located; for
example, a photo sharing site, a blogging platform and an online bank service
control access to private resources and activities. The Resource Server is deployed
in a different location from Oracle Access Management and the Client. The
Resource Server needs to be capable of accepting and responding to protected
Note: OAuth does not impose special requirements on the
interaction between a Resource Server and an Authorization Server.
Understanding OAuth Services Authorization for Web Clients
Understanding OAuth Services 52-3
resource requests using access tokens. The Resource Server must also validate the
access token with OAuth Services as described in Enforcing Access Control.
52.2.1 Understanding 3-Legged Authorization
In 3-legged authorization, the Resource Owner grants access to an OAuth-enabled
Client to request access to resources stored on an OAuth protected Resource Server.
Oracle Access Management OAuth Services validates the Resource Owner's identity
and presents the owner with a consent form in a Web browser when approval is
required. The third leg in this authorization scheme is the step in which the user grants
or denies the client access. The following text has more details and Figure 52–1
illustrates the process.
1. The Resource Owner (user) undertakes an action in the user-agent (a browser, for
example) that requires the Client web service (or app) to access protected
resources belonging to the user on a different site.
2. The Client initiates the OAuth flow by invoking the OAuth Services authorization
endpoint to get a request token. The Client sends its identifier, the requested
scope, and a redirection URI to which the Authorization Server will direct the
user-agent once access is granted or denied.
3. OAuth Services redirects the user-agent to request the Resource Owner's password
credentials.
4. Access Manager displays a login page requesting a user name and password from
the Resource Owner. OAuth Services supports all authentication schemes
provided by Access Manager.
5. The Resource Owner enters a user name and password.
6. Access Manager validates the credentials, returns a request token and redirects the
user-agent to OAuth Services.
7. OAuth Services determines that the Resource Server requires the user's consent
before the authorization code can be sent to the Client.
8. OAuth Services displays the user consent form.
Web-based clients require the consent form to be protected by a WebGate.For
details, see Section 53.5, "Configuring a WebGate to Protect OAuth Services."
9. The user approves the request.
10. OAuth Services returns an authorization code to the Client using the redirection
URI.
11. The Client sends the authorization code in a POST request (including the
redirection URI used to obtain the authorization code for verification) to the token
endpoint and requests an OAuth access token. When making the request, the
Client authenticates with OAuth Services.
Note: A WebGate proxy is required to use 3-legged authorization
with an external LDAP directory server. See Section 53.5, "Configuring
a WebGate to Protect OAuth Services" for details.
Note: The Authorization Code grant type is required for 3-legged
authorization. See Section 52.4.3, "Understanding Clients" for details.
Understanding OAuth Services Authorization for Web Clients
52-4 Administrator's Guide for Oracle Access Management
12. If the client type requires client credentials, the OAuth Services authenticates the
client credentials, validates the authorization code, and ensures that the
redirection URI received matches the URI previously used to return the
authorization code. OAuth Services also validates the requested scope based on
the Resource Server's configuration and the user's consent details.
13. OAuth Services returns an access token to the Client.
A refresh token may also be returned with the access token if the client sends a
refresh token request. For more information, see Section 52.5, "Understanding
OAuth Services Tokens."
14. The Client presents the access token to the Resource Server.
15. The Resource Server validates the access token by sending a request to the OAuth
Services token endpoint and waits for a success or failure response.
16. OAuth Services validates and sends the token success or failure response back to
the Resource Server.
17. If the token is deemed valid, the Resource Server returns the requested resource to
the Client.
Figure 52–1 OAuth 3-Legged Flow Diagram
52.2.2 Understanding 2-Legged Authorization
In 2-legged authorization, the OAuth Client is pre-approved to access resources; thus,
the user consent form step (described in Understanding 3-Legged Authorization) is
not required. In this scenario, Access Manager returns a request token to the Client
which the client sends to OAuth Services to request an access token. Because the
request token is pre-authorized, OAuth Services token service returns an access token
User
Agent
OAM User
Login
Token
Service
Authorization
Service
Resource
Server
Client
Application
1. Access Client App
2. Authorization request
3. Redirect to OAM user login
8. Show user consent page
10. Return authorization code client app
11. Access token request
14. Access the resource with access token
17. Return resource details to client
15. Validate access
token
16. Access token
validation response
13. Return access token after validation
9. User gives consent
6. OAM redirect to authorization after valid login
7. User
needs
to give
consent
4. OAM user login UI
5. Enter user credentials
12. Verify client and
user consent
Understanding OAuth Services Authorization for Mobile Clients
Understanding OAuth Services 52-5
to the Client without displaying the consent form. This arrangement fits a
service-to-service model, especially when the requesting service (Client) and the
Resource Server are in a close partnership and Resource Owner approval is either
assumed or not required.
52.3 Understanding OAuth Services Authorization for Mobile Clients
The Mobile OAuth Services authorization scenario supports mobile apps that run in a
browser as well as device-native apps that do not use a browser or just use the browser
during user authentication. This scenario provides enhanced security support (in
addition to the baseline security measures defined in the OAuth 2.0 specification)
including:
■Client apps must be registered with OAuth Services in the Identity Domain that
your organization uses to manage Mobile OAuth Services clients.
■Mobile applications must register with Oracle Access Management prior to using
OAuth Services and each registration is specific to one app on the device. After the
application registration, the mobile app will have a client token. It uses this token
as the security credential for making Access Token requests. In comparison, the
OAuth web client uses either a credential-like password or an assertion to identify
itself.
■This scenario supports user consent management. If consent management is
enabled, the client app prompts the user to accept or decline the app's request to
register with Access Manager.
■Except for access tokens (and user tokens if server-side SSO is disabled), the server
does not send security material, such as OAAM device and session handles to the
client on the mobile device, but stores it in the Server-Side Device Store. Access
tokens are both sent to the client and stored in the Server-Side Device Store to
provide for validation and life cycle management.
■The OAM server component can restrict token delivery to a specific app installed
on a specific device by sending part of a token through HTTPS, and sending the
other part through push notification using either the Apple Push Notification
Service (APNS) or Google Cloud Messaging (GCM). Figure 52–2 illustrates this.
Note: The Client Credentials grant type or the Resource Owner
Credentials grant type are required for 2-legged authorization. See
Section 53.3.3, "Configuring Clients" for more information.
Note: This consent is controlled with the "Require User Consent for
Client Registration" attribute under the Service Profiles. If set, the user
will be asked to confirm app registration; if off, the user will not be
asked. See Section 53.3.2, "Configuring Service Profiles."
Understanding OAuth Services Authorization for Mobile Clients
52-6 Administrator's Guide for Oracle Access Management
Figure 52–2 Using a Split Request to get a Client Verification Code
The following scenario describes the additional interactions that Oracle Access
Management undertakes when authenticating with a mobile client. The process is
illustrated in Figure 52–3.
1. The Resource Owner opens the Client mobile app.
An Oracle Access Management administrator has already registered this Client
app as a Mobile OAuth Services Client.
2. The Mobile Client sends the client ID and the device token to OAuth Services and
requests a client verification code.
3. OAuth Services returns half of the client verification code over HTTPS or HTTP.
See Figure 52–2. This behavior can be configured in the Mobile Service Settings
section of the OAuth Services Profile configuration page.
■If the security level is set to Advanced, all codes and tokens are returned using
both HTTP and push notification.
■If the security level is set to Standard mode, all codes and tokens are sent over
HTTP only.
The rest of this scenario (beginning with step 4) contains details for when the
security level is set to Advanced.
4. The Mobile client requests the second half of the client verification code from the
OAuth Services push endpoint.
The push endpoint forwards the request to the APNS or the GCM service
depending on the mobile device’s operating system.
5. The APNS or GCM service sends the second half of the client verification code to
the Client app.
6. The Mobile client requests an authorization code from OAuth Services by sending
the client verification code and the device token.
7. OAuth Services redirects the request to Access Manager.
8. Access Manager sends a login page to the user-agent so that the user can log in.
9. The Resource Owner (user) enters a user ID and password.
10. Access Manager validates the login and redirects to OAuth Services.
User Token
Service
APNS / GCM
Service
Push ServiceMobile Client
App
1. Launch app
Typical communication pattern involving APNS
2. Acquire
pre-Authorization code
4. Request second part of pre-authorization code
5. Receive second part of pre-authorization
3. Return first part of
pre-authorization code
Understanding OAuth Services Authorization for Mobile Clients
Understanding OAuth Services 52-7
11. OAuth Services is configured to obtain the user's approval to register the device.
(It will not ask for the user's consent to register if Require User Consent for Client
Registration is disabled on the OAuth Services Profile Configuration page.)
12. The consent page is sent to the Resource Owner.
13. The Resource Owner provides (or denies) consent.
14. OAuth Services checks the Oracle Adaptive Access Manager (OAAM) plug-in to
determine if additional authentication steps are required.
15. The plug-in determines that an additional challenge question is required.
16. The OAAM challenge question is sent to the Resource Owner.
17. The Resource Owner provides the challenge answer which is forwarded to the
OAAM plug-in.
18. The OAAM plug-in validates the challenge answer.
19. OAuth Services uses the mobile redirect URI to return half of the authorization
code that the mobile app will need to request a client token.
20. The Mobile OAuth Services client requests the second half of the authorization
code from OAuth Services push endpoint.
The push endpoint forwards the request to the APNS or GCM service.
21. The mobile client app receives the second half of the authorization code from the
APNS or GCM service.
The mobile client app assembles the authorization code in preparation for
requesting a client token.
22. After validating the authorization code, the Mobile OAuth client uses the code to
request the first half of the client token from the OAuth Services token endpoint.
23. The token endpoint returns the first half of the client token to the mobile client.
24. The mobile client requests the second half of the client token from the OAuth
Services push endpoint.
25. The APNS or GCM service sends the second half of the client token to the mobile
client app.
The mobile client assembles the client token as well as a refresh token. The client
can use the refresh token to request a new client token.
26. The mobile client prepares to request an access token by completing the following
steps:
■The Client requests and receives a client verification code from OAuth
Services.
■The Client requests and receives the first part of the authorization code from
OAuth Services.
■The resource owner does not need to log in if the user session is still valid.
■User consent may be required based on the Resource Server scope to which
the Client is requesting access.
■The OAAM plug-in does not repeat its challenge.
■The client requests the second part of the authorization code.
27. The APNS or GCM service returns the second half of the authorization code for
the access token.
Understanding OAuth Services Authorization for Mobile Clients
52-8 Administrator's Guide for Oracle Access Management
The Client assembles the authorization code in preparation for the access token
request.
28. The mobile client requests an access token by sending the client token and the
access token authorization code.
29. The token endpoint sends the access token to the client. This behavior depends on
whether the Security Level setting in the Mobile Service Settings section of the
OAuth Services Profile configuration page is set to Advanced or Standard.
30. The Mobile OAuth Services client requests access to the protected resources by
sending the access token to the Resource Server.
31. The Resource Server validates the access token with the OAuth Services token
service. The Resource Server can also validate the token locally. If the certificates
are configured correctly, JWT token signing is verified at the Resource Server.
32. The OAuth Services token service sends a response to the Resource Server.
33. The Resource Server sends the requested resources to the mobile client.
Understanding OAuth Services Authorization for Mobile Clients
Understanding OAuth Services 52-9
Figure 52–3 The Complete Mobile App Authorization Request Flow
User Token
Service
APNS / GCM
Service
User Agent Authorization
Service
Adaptive
Access Plug-in
Resource
Server
OAM User
Login
Push ServiceMobile Client
App
1. Launch app
Authorization code assembled
in preparation for the client token
request.
Authorization code assembled
in preparation for the access
token request.
Client token assembled along
with a refresh token.
Client token assembled along
with a refresh token.
Access token received.
Requested resources received.
Step 26: The client prepares to request an access token by completing the following steps: * The client requests and receives a pre-authorization code
from the OAuth server (as shown in steps 2-5). The client requests and receives the first part of the authorization code from the OAuth server (as shown
in step 6, steps 10-13, and step 19). * The client requests the second part of the authorization code (as shown in steps 20-21).
9. Enter user ID and password
12. Show user consent page
13. User gives consent
Steps 22-25: Client gets a client token by including the authorization code in a split request to the Token Service and the APNS/GCM Service.
Steps 2-5: Get a pre-authorization code by sending a split request to the Token Service and the APNS/GCM Service.
17. User provides challenge answer
16. Show user challenge question
6. Authorization request with pre-authorization code
20. Request the second part of the authorization
code (in preparation for requesting a client token)
28. Acquire AT with client
token + authorization
code
21. Client receives the second part of the authorization code
27. Client receives the second part of the authorization code
7. Redirect to
OAM user login
14. Check with plug-in
before returning to
authorization code
8. OAM user login UI
10. OAM redirect to authorization after valid login
19. Return first part of authorization code through mobile redirect URL
11. User needs
to give consent
18. Plug-in validates the
challenge answer
15. Plug-in may
decide to challenge
30. Request resources with AT
33. Resource response
31. Validate access token
32. Token validation response
29. Return to complete
access token (AT)
Understanding the OAuth Services Components
52-10 Administrator's Guide for Oracle Access Management
52.4 Understanding the OAuth Services Components
The following sections contain information about the Identity Domains configuration
options. Information in the following sections applies to both Identity Federation and
Mobile Security OAuth Services except for the Jailbreak Detection Policy which is
specific to Mobile Security OAuth Services. See Chapter 53, "Configuring OAuth
Services" for details on configuring these components.
■Understanding Identity Domains
■Understanding Service Profiles
■Understanding Clients
■Understanding Service Providers
■Understanding Resource Servers
■Understanding Plug-Ins
■Understanding Server Settings
■Understanding Jailbreak Detection Policy
■Understanding Token Life Cycle Management
52.4.1 Understanding Identity Domains
Identity Domains are entities that contain all artifacts required to provide standard
OAuth Services or Mobile OAuth Services. Each Identity Domain is an independent
entity. One of the primary use cases of the Identity Domain is for multi tenants
deployments. Each Identity Domain will correspond to a tenant. This can apply to
different departments in an organization if there is a need for independence. This will
also be useful for cloud deployments where each Identity Domain can correspond to a
separate tenant or entity. The following artifacts are just some of the components
configured within an OAuth Services Identity Domain.
■One or more Service Profiles
■One or more Clients
■A Service Provider
■One or more Resource Servers
■Plug-ins
■Server Settings
■Token Life Cycle Management (search for and revoke tokens across an Identity
Domain)
For information on configuring Identity Domains, see Section 53.3.1, "Configuring
Identity Domains."
52.4.2 Understanding Service Profiles
A Service Profile defines the following settings.
■The clients with whom OAuth Services can interact
■The Custom and System Resource Servers that OAuth Services protects and to
which it provides access
■Refresh token settings, token expiration settings, and the option to enable the
token life-cycle management
Understanding the OAuth Services Components
Understanding OAuth Services 52-11
■The User Profile Service and Consent Management Service profiles
■The enabled security profile plug-ins
■The mobile service settings, including security settings for the supported mobile
platform(s)
■The root URL for the OAuth Services endpoints
If necessary, you can create multiple Service Profiles. Different Service Profiles may be
needed if different clients or resources need to be grouped, or different token settings
are required, or there are different service endpoints with different configuration
settings. Being able to create multiple Service Profiles gives flexibility to configuration
options although in most cases it may not be needed. For information on configuring
Service Profiles, see Section 53.3.2, "Configuring Service Profiles."
52.4.3 Understanding Clients
The Client initiates the OAuth protocol by invoking the OAuth Services. Client profiles
must be created using the OAuth Services interface (in the Oracle Access Management
Console) before the protocol can be initiated. At a minimum, client profiles include the
application name, a client ID, and one or more URIs to which OAuth Services will
redirect the user-agent once access is granted or denied. An OAuth Services Client can
be defined as Web, Public or Mobile.
■Web clients are assigned with a client ID and secret. These clients can interact with
the OAuth Services server by sending the client ID and secret as part of an
authorization header. It is up to each individual client to determine how the secret
issued to them is securely stored.
■Public clients are assigned with a client ID but no secret. Typically these profiles
pertain to browser based applications like Javascript or can be mobile based apps.
■Mobile clients are assigned with a client ID and the secret is dynamically
generated as part of a mobile client’s registration flow with OAuth Services. (The
registration flow is proprietary and was developed by extending the OAuth
specification.)
The client ID and secret are explained in the following bullet points.
■The Client ID is a unique string that represents the registration information and is
required for each client. You can create a unique client ID or have OAuth Services
generate one. OAuth Services compares the defined Client ID with the value the
client sends over HTTPS or HTTP as part of an authorization request. If the values
do not match, the request is rejected. Client IDs are Base64 encoded when they are
sent as authorization header.
■The Client secret is the client password. You can create a unique client secret or
have OAuth Services generate one. Web clients are required to have a Client ID
and a Client secret. Mobile clients and Public clients, on the other hand, do not
have a client secret and are given only a Client ID.
To request an access token, the client obtains authorization from the resource owner.
The authorization is expressed in the form of an authorization grant, which the client
uses to request the access token.The OAuth 2.0 specification provides authorization
grant types for different security use cases. OAuth Services has implemented some of
these grant types. Web, Public and Mobile Clients can access the various OAuth
Services grant types that are appropriate to them. For example, the Client Verification
Code grant type is only relevant to mobile clients. The following grant types are
supported by OAuth Services.
Understanding the OAuth Services Components
52-12 Administrator's Guide for Oracle Access Management
■Authorization Code - The Resource Owner logs in using Oracle Access
Management. The token endpoint exchanges the authorization code along with
client credentials for an access token. The Authorization Code grant type is
required for 3-legged flows.
■Resource Owner Credentials - The Resource Owner provides the client with a user
name and password. This is only suitable for highly trusted client applications
because the client could abuse the password, or the password could
unintentionally be disclosed to an attacker. Per the OAuth 2.0 specification, the
authorization server and client should minimize use of this grant type and utilize
other grant types whenever possible. The Resource Owner Credentials grant type
is required for 2-legged authorization scenarios.
■Client Credentials – The client requests an access token using only its client
credentials (or another supported means of authentication). This is suitable if the
client is requesting access to protected resources under its control, or those of
another resource owner when previously arranged with the authorization server.
The Client Credentials grant type is required for 2-legged authorization scenarios.
■Refresh Token - Select this option to return a refresh token together with an access
token in the token response. See Section 52.5, "Understanding OAuth Services
Tokens" for more information.
■JWT Bearer - Allows a JWT assertion to be used to request an OAuth Services
access token.
■SAML 2 Bearer - Allows a SAML2 assertion to be used to request an OAuth
Services access token.
■OAM Credentials - Used to request OAM tokens, such as a master token, an access
token, or an OAuth Services access token.
■Client Verification Code - Used by Mobile OAuth Services clients to request a
pre-verification code which subsequently gets used in mobile client flows.
Privileges and Allowed Scopes can also be configured on a client by client basis.
OAuth Services allows for the configuration of scopes to bypass the need for user
consent. Thus, you can configure Privileges to define which clients are allowed which
grant types. If applicable, the Client will then obtain an authorization grant that can be
exchanged with OAuth Services for an access token. For information on configuring
Clients, see Section 53.3.3, "Configuring Clients."
52.4.4 Understanding Service Providers
The Service Provider settings are used to manage the connection between OAuth
Services and Access Manager, the back-end authorization Service Provider that
supports OAuth Services. The OAuthServiceProvider is the default Service Provider
for the DefaultDomain Identity Domain although a Custom Service Provider can be
created. In this release, OAuth Services provides support for both OAM authentication
(most authentication modules can be invoked, usually user/credential based plugins)
and IDS authentication. Any features not provided through OAM or IDS
authentication will require a custom service provider. Each Identity Domain can only
have one Service Provider.
Note: (For general information about the OAuth specification grant
types, see
http://tools.ietf.org/html/rfc6749#section-1.3
.
Understanding the OAuth Services Components
Understanding OAuth Services 52-13
For information on configuring Service Providers, see Section 53.3.4, "Configuring the
Service Provider."
52.4.5 Understanding Resource Servers
Resource Servers settings are independently configured in a profile for each remote
resource server that contains applications or services to be protected by OAuth
Services. The Resource Server profile does not define the resource server specific
settings like the endpoint or security protection - only OAuth Services related
configurations.
Part of the Resource Server configuration involves defining scope. Scope determines
the range of access the Client will have to the protected resource. Based on the scope
setting, Oracle Access Management restricts access and informs the Client of the scope
in the access token issued. Thus, an OAuth Services access token with proper scope
needs to be obtained in order for a Client application to access a Resource Server.
The client provides a scope string in it’s request to OAuth Services. The scope can be a
URL or a string literal. After successful authentication and authorization, OAuth
Services includes the scope in the Access Token. For example, if an OAuth client
requests access to a resource for a specific end user, OAuth Services would create an
Access Token with the scope defined as
UserProfile.me
and the client could access
the User Profile Resource Server with the
/me
endpoint. (See Table 52–1.) In turn, the
User Profile Resource Server will decide whether the client can access the resource
with acquired access token or not. The following is true in regards to scope.
■A Resource Server can have one or more scope(s) associated with it.
■Multiple Resource Servers can be created if there is a need, for example, to have
different token settings or to modify the default security protection (like not
allowing revocation of consent). Each will have it's own set of scope definitions.
This is not a common scenario
■The client sends the scope parameter as part of an authorization request. If any
part of the scope parameter value is invalid, OAuth Services sends the client
application an
invalid_scope
error response. If the scope parameter value is
valid, it gets embedded as part of the authorization code and access tokens.
OAuth Services provides two out-of-the-box services modeled as Resource Servers
and protected with an Access Token. For information on the User Profile Services and
Consent Management Services Resource Servers, see the following sections.
■Understanding User Profile Services
■Understanding Consent Management Services
For configuration information, see Section 53.3.5, "Configuring Custom Resource
Servers," Section 53.3.6, "Configuring User Profile Services," and Section 53.3.7,
"Configuring Consent Management Services."
Note: Currently, authentication modules that have multi step
orchestration in OAM can not be invoked; this refers to 2-legged
OAuth Services scenarios. For 3-legged scenarios, there is no
limitation on invoking OAM authentication modules because
authentication is done through a browser flow.
Understanding the OAuth Services Components
52-14 Administrator's Guide for Oracle Access Management
52.4.5.1 Understanding User Profile Services
The default UserProfile User Profile Services configuration is a Resource Server
created during Oracle Access Management OAuth Services installation. This
configuration allows your organization to use OAuth 2.0 to interact with a back-end
LDAP directory server and perform the REST operations documented in Table 52–1 on
Person, Group, and Relationship entities. See the Oracle Fusion Middleware Developer's
Guide for Oracle Access Management for more details on using REST to interact with the
User Profile Services.
User Profile Services receives and responds to HTTPS requests using the
service-specific endpoints for Person, Group, and Relationship entities. Each service
endpoint can be individually disabled if it is not needed. If there are users across
multiple user repositories, you can create multiple instances of User Profile Services;
for example, if a company uses different repositories for different organizations this
would be useful. Creating multiple user profile services may not be common though.
See Section 48.2.5, "Introducing User Profile Services" for more information. For
information on configuring User Profile Services, see Section 53.3.6, "Configuring User
Profile Services." The following sections contain details on specific User Profile
Services configurations.
■Using Proxy Authentication
■Securing User Profile Services Activity
■Understanding the Entity Relationship
52.4.5.1.1 Using Proxy Authentication Proxy authentication allows a user to control the
security of middle tier applications by preserving client identities and privileges
through all tiers, and auditing actions taken on behalf of clients. For example, this
feature allows the identity of a user using a web application (also known as a "proxy")
to be passed through the application to the database server. Oracle Unified Directory
(OUD) and Active Directory (AD) are few directory servers that support proxy
authentication. Proxy authentication delivers the following security benefits.
Table 52–1 Default User Profile Services Endpoint Operations
Resource Endpoint (URI) HTTP(S) Methods Use Details
http://host:port/ms_oauth/
resources/userprofile/me
GET allows read
PUT allows update
The OAuth client can request
read and update privileges for
the specified user’s profile.
http://host:port/ms_oauth/
resources/userprofile/users
GET allows read, search
POST allows create
PUT allows update
DELETE allows delete
The OAuth client can request
create, read, search, update, and
delete privileges for any user
profile.
http://host:port/ms_oauth/
resources/userprofile/groups
GET allows read, search
POST allows create
PUT allows update
DELETE allows delete
The OAuth client can request
create, read, search, update, and
delete privileges for any group
profile.
http://host:port/ms_oauth/
resources/userprofile/secretkey
GET allows read
POST allows create
DELETE allows delete
Used by Oracle Mobile
Authenticator to read, create or
delete secret key for given user.
The secret key is used by OMA
to generate a one time pin.
Understanding the OAuth Services Components
Understanding OAuth Services 52-15
■A limited trust model, by controlling the users on whose behalf middle tiers can
connect, and the roles the middle tiers can assume for the user.
■Accountability, by preserving the identity of the real user through to the database,
and enabling auditing of actions taken on behalf of the real user.
■Flexibility, by supporting environments in which users are known to the database,
and in which users are merely "application users" of which the database has no
awareness.
Oracle Access Management provides the ability to add proxy authentication features
on top of directory servers that do not support it. The Access Control option is simply
Proxy Authentication support for directory servers that do not have built in support
for proxy authentication.
Proxy Authentication and Access Control were previously available in Mobile Services
and now this support is available in OAuth Services. Without Proxy Authentication or
Access Control enabled, communication with directory servers is done using the
administrator user account; in this case, the administrator can perform any operations
on any user. By enabling this feature, the logged in user can only perform operations
for which privilege has been granted.
52.4.5.1.2 Securing User Profile Services Activity Security considerations are very
important when implementing User Profile Services. For example, a user with write
access to UserProfile.me can change their own UID or mail address causing a serious
breach. Because of this it is possible to limit the scope of all URI to read only and you
should be careful about granting write access to any scope. You can also configure read
and write access independently on a per-attribute basis.
Security protection is defined within the Scopes table of the configured User Profile
Service. Adding a URI allows you to select whether the service endpoint is enabled,
whether read or write access is allowed, whether the URI is protected by an access
token, and whether user consent is required.
The Oracle Access Management Console also allows fine-grained configuration of the
attributes that can be modified. You can also add custom attributes or remove default
attributes. Table 52–2 documents the out-of-the box configurable attributes for each
scope setting.
Table 52–2 User Profile Resource Server - Scope Settings
Scope
HTTP(S)
Method
Resource
URI Attributes
UserProfile.me
GET
PUT
/me uid, mail, description,
commonname, firstname, lastname
UserProfile.users
GET
POST
PUT
DELETE
/users uid, mail, description,
commonname, firstname, lastname
UserProfile.groups
GET
POST
PUT
DELETE
/groups name, description
Understanding the OAuth Services Components
52-16 Administrator's Guide for Oracle Access Management
52.4.5.1.3 Understanding the Entity Relationship An entity relationship is an association
between two entities such as Users and Groups. The entity types can be the same or
different. For example, the memberOf entity is a relationship between a user and a
group while the manager entity is a relationship between two users. Client
applications can create, read or delete relationships using the User Profile Services
relationship endpoint. The following REST operations illustrate how to create a
memberOf relationship. In these examples, the relationship endpoint is memberOf, the
source entity URI is user-uri and the destination-entity URI is group-uri.
Create User "John"
curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_
oauth/resources/userprofile/users -d '{"uid":"John"Anderson","commonname":"John
Anderson","firstname":"John"}'
Create Group "Group1"
curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_
oauth/resources/userprofile/groups -d '{"description":"group1
testing","commonname":"group1"}'
Create memberOf relationship
curl -H "Content-Type: application/json" --request POST http://localhost:port/ms_
oauth/resources/userprofile/users/memberOf -d '{"group-uri":"\/idaas_
rest\/rest\/userprofile\/group\/group1", "user-uri":"\/idaas_
rest\/rest\/userprofile\/people\/John"}'
52.4.5.2 Understanding Consent Management Services
The default Consent Management Services configuration is labeled
ConsentManagement and handles consent storage, retrieval, revocation, and consent
validation operations. If you select the Require User Consent option Oracle Access
Management displays to the user a consent form so that access to the requested
resource can be approved or denied by the user. The Require User Consent option can
be enabled on a scope by scope basis. For example, you can require user consent for a
scope request that allows "write" access but not "read" access. Consent data is stored in
the Oracle Access Management database. For information on configuring Consent
Management Services, see Section 53.3.7, "Configuring Consent Management
Services."
UserProfile.secretkey.ma
nagement
GET
POST
DELETE
/secretkey
There are no attributes needed.
Note: The Clients configuration page has a Bypass User Consent
option. If this option is selected, the Client setting overrides the
Resource Server setting. For information on configuring Clients, see
Section 53.3.3, "Configuring Clients."
Table 52–2 (Cont.) User Profile Resource Server - Scope Settings
Scope
HTTP(S)
Method
Resource
URI Attributes
Understanding the OAuth Services Components
Understanding OAuth Services 52-17
Any consent operation requires an access token of the Client Credentials grant type (as
discussed in Understanding Clients) and the desired Consent Management scope. A
user (through the client) requests access to a resource protected by OAuth Services.
The request contains an access token, the client identifier and the user identifier.
OAuth Services retrieves the configured scopes and, if allowed, grants consent by
adding the scope to the access token. The access token is added to the authorization
header in the HTTP request which is used to retrieve, grant or revoke consent using
the endpoints provided by the Consent Management Service. For details on using
REST interfaces to interact with Consent Management Services, see Oracle Fusion
Middleware Developer's Guide for Oracle Access Management.
52.4.6 Understanding Plug-Ins
Plug-ins enhance security by consulting additional logic for trust and risk analysis.
(Such additional logic may deny certain risky operations.) Plug-ins apply the logic
during authentication operations, including client application registration for mobile
apps. The following plug-in types are available for use with OAuth Services and
Mobile OAuth Services.
■The Custom Token Attributes Plug-in defines security policy around the token
service provider.
■The Authorization and Consent Service Plug-in defines security policy around
interactions where authorization and user consent are granted. This plug-in type
can influence claims in a generated token as well.
■The Client Plug-in defines a security policy for Clients in an Identity Domain.
■The Resource Server Profile Plug-in defines a security policy for Resource Servers in
an Identity Domain.
The following plug-in types are available for use with Mobile OAuth Services only:
■The Mobile Security Manager Plug-in is for use with Oracle Mobile Security Suite
(OMSS). The Mobile Security Manager (MSM) component (part of OMSS) collects
a rich set of mobile device data. This plug-in gathers that information and also
invokes the MSM compliance policy, which checks the compliance status of the
device. Finally, the plug-in sends the device information and the compliance status
to the Adaptive Access Plug-in. For information about configuring the Mobile
Security Manager plug-in, see Section 53.3.8.2, "Understanding the Plug-in
Configuration Page."
■The Adaptive Access Plug-in is for use with Oracle Adaptive Access Manager
(OAAM). It runs fraud detection and risk analysis policy checks that further
validates that the user connection is authentic and can be trusted. The Adaptive
Access Plug-in can utilize mobile device attribute values collected by the Mobile
Security Manager Plug-in, or, if Oracle Mobile Security Suite is not available, the
Adaptive Access plug-in can use mobile device attribute values that the Mobile
OAuth Services obtains during mobile app requests. If the Mobile Security
Manager Plug-in is active, it runs first and passes device data to the Adaptive
Access Plug-in, which runs second.
For more information, see Section 52.9, "Understanding OAuth Services Plug-ins."
For each plug-in type only one instance can be active at a time at the service profile
level. For example, you can create and save different instances of the Client Plug-in at
the Identity Domain level, but at the Service Profile level you can only assign one
Note: Multiple Consent Management Services are not necessary.
Understanding OAuth Services Tokens
52-18 Administrator's Guide for Oracle Access Management
Client Plug-in instance at a time. Optional plug-ins can be configured to provide
additional security. For information on configuring plug-ins, see Section 53.3.8,
"Configuring Plug-Ins."
52.4.7 Understanding Server Settings
The Server Settings page is for configuring general server settings for the Identity
Domain under which it is accessed. For information on configuring Server Settings,
see Section 53.3.9, "Configuring Server Settings."
52.4.8 Understanding Jailbreak Detection Policy
A preconfigured Jailbreaking Detection Policy for iOS devices can search for files that
indicate a device is jail broken and, if found, deny that device access to OAuth
Services. This setting tab is displayed and for use with Mobile OAuth Services only.
For information on configuring the Jailbreak Detection Policy, see Section 53.3.10,
"Configuring the Jailbreak Detection Policy."
52.4.9 Understanding Token Life Cycle Management
Use this screen to search for and revoke tokens that have been issued. You can search
for tokens using criteria such as user ID, client ID/name, client IP address, service
profile, assertion token category, and token creation/expiration time. For information
on configuring Token Life Cycle Management, see Section 53.3.11, "Configuring Token
Life Cycle Management."
52.5 Understanding OAuth Services Tokens
OAuth Services generates a Client Token, a User Token and an Access Token. The
Client Token is generated by OAuth Services when using the Client Credentials grant
type without any scope for confidential clients, or for mobile clients. The User Token is
generated by OAuth Services using the User Credentials grant type without any scope.
The Access Token is generated with supported grant types using scope parameters.
See Understanding Clients for details on grant types.
The Refresh Token is also generated by OAuth Services. It is issued when an offline
scope is presented in the Access Token request and usually has a higher expiration
time than the Access Token. A Refresh token can be used to get an Access Token. The
following sections contain additional details.
■Understanding OAuth Services Access Tokens
■Understanding OAuth Services Refresh Tokens
■Understanding Mobile OAuth Services Client Tokens
Note: A user and client can provide credentials in the form of a JWT
token or an assertion for verification and generation of one of the
three tokens. It is possible to use a Client Token or a User Token
generated by OAuth Services as a Client Assertion or a User Assertion
respectively but that is not common.
Understanding OAuth Services Tokens
Understanding OAuth Services 52-19
52.5.1 Understanding OAuth Services Access Tokens
If OAuth Services determines that a user must consent to the request for access to a
protected resource, a consent form is displayed. After the user consents, OAuth
Services returns an authorization code to the Client service provider. The Client then
sends the authorization code to the Token Endpoint and requests an OAuth Services
Access Token. (When making the request, the Client authenticates with OAuth
Services.) If received, the Access Token allows access to the protected resources. See
Understanding the Authorization and Authentication Endpoints for details on the
Token Endpoint.
Oracle Access Management can embed custom attributes in Access Tokens. Custom
attributes are configured as part of the Service Profile or the Custom Resource Server.
They are defined as static or dynamic.
■Static Attributes - Attribute name and value pairs where the value is fixed at the
time that you define the attribute. For example,
name1=value1
.
■Dynamic Attributes - User-profile specific attributes. You must also configure the
User Store setting on the Service Profile Configuration page. This setting defines
the source of the User Profile attributes. The User Profile Service (and/or the
underlying IDS interface) may be used to retrieve attribute names and values.
Because dynamic attributes are user related, the user consent page (if configured)
shows that the configured attributes are being shared with clients and resources.
Section 53.3.2, "Configuring Service Profiles" and Section 53.3.2, "Configuring Service
Profiles" contain more information. Keep the following guidelines in mind when
configuring custom attributes:
■Do not use the same name for a static and dynamic attribute.
■Avoid using the same name when adding custom attributes to the service profile
configuration and the scope configuration. If you define the same attribute name
in both locations, the scope-based attribute value takes precedence.
Custom attributes appear as claims in access tokens. JWT-based access tokens contain
standard JWT claims along with OAuth Services specific ones. For example:
■Standard
"exp":1357596398000,
"iat":1357589198000,
"aud":"oam_server1",
"iss":"OAuthServiceProfile",
"prn":null,
"jti":"340c8324-e49f-43cb-ba95-837eb419e068",
■OAuth Services Specific
"oracle.oauth.user_origin_id":"john101",
"oracle.oauth.user_origin_id_type":"LDAP_UID",
"oracle:idm:claims:client:macaddress":"1C:AB:A7:A5:F0:DC",
"oracle.oauth.scope":"brokerage",
"oracle.oauth.client_origin_id":"oauthssoapp1id",
"oracle.oauth.grant_
type":"oracle-idm:/oauth/grant-type/resource-access-token/jwt"
These claims are available as part of the access token generated by OAuth Services.
Because the custom attributes appear as claims in a JWT-based access token, the
following naming restrictions apply:
■Avoid JWT standard claim names.
Understanding the Authorization and Authentication Endpoints
52-20 Administrator's Guide for Oracle Access Management
■Avoid names with an "Oracle" prefix (as shown above)
52.5.2 Understanding OAuth Services Refresh Tokens
OAuth Services can be configured to allow the Client to use a refresh token to obtain
additional access tokens with identical or narrower scope. The refresh token is used
when the access token is no longer valid. The purpose of a refresh token is to improve
security. Access tokens are short-lived, so if stolen, they are only useful for a limited
period. Refresh tokens are longer-lived, but are less frequently sent to the server, thus
reducing the likelihood that they will be stolen.
Any scope can request and use a refresh token, however, the refresh token is typically
used when the user is offline. When configuring a Resource Server, the administrator
can designate one scope to be the offline scope. If an access token request includes the
scope designated as the offline scope, the server will include the refresh token with the
access token. If the offline scope field is not configured, the server will not issue a
refresh token. See Section 53.3.5.3, "Understanding the Custom Resource Servers
Configuration Page" for details.
The client must be configured to use the refresh token. See Section 53.3.2.3,
"Understanding the Service Profile Configuration Page" and Section 53.3.3.3,
"Understanding the Web Clients Configuration Page" for information about refresh
token settings.
52.5.3 Understanding Mobile OAuth Services Client Tokens
Mobile applications must register with Oracle Access Management prior to using
OAuth Services and each registration is specific to one app on the device. After the
application registration, the mobile app will have a Client Token. It uses this token as
the security credential for making Access Token requests. See Understanding Mobile
OAuth Services Server-Side Single Sign-on for details.
52.6 Understanding the Authorization and Authentication Endpoints
OAuth Services has four authentication endpoints that receive and respond to HTTPS
requests: the authorization endpoint, the token endpoint, the push endpoint, and the user
consent revocation endpoint. Each endpoint is a URL that clients use to make requests.
■Authorization Endpoint – The client uses the Authorization Endpoint to get
authorization from the resource owner to access the requested resources. The
client application initiates the Authorization Endpoint request by sending its
identifier, a requested scope defining the resource to which it wants access, and a
redirection URI to which OAuth Services will direct the web browser once access
is granted or denied. This endpoint accepts the HTTPS request. The URI for this
endpoint always ends in authorize. For example:
http(s)://<host>:<port>/ms_
oauth/oauth2/endpoints/<yourOauthServiceName>/authorize
■Token Endpoint – The client application interacts with the Token Endpoint to
exchange an authorization code grant for an access token. It is also used for Client
Credentials grant type and resource owner credentials grant type to get an access
token. The client uses a Refresh token to obtain a new access token. The URI for
this endpoint always ends in token. For example:
http(s)://<host>:<port>/ms_
oauth/oauth2/endpoints/<yourOauthServiceName>/token
Understanding Mobile OAuth Services Server-Side Single Sign-on
Understanding OAuth Services 52-21
■Push Endpoint – Mobile OAuth Services client apps interact with the push
endpoint to obtain (depending on configuration) part of the authorization codes,
and/or part of the client tokens, access tokens, and refresh tokens that are sent
through either the Apple Push Notification Service (APNS) or the Google Cloud
Messaging (GCM) service. It can also be used for Mobile Client Verification code,
Authorization Code and Client Tokens. For example, the end point for requesting
data from APNS is:
http(s)://<host>:<port>/ms_oauth/oauth2/endpoints/oauthservice/push
■User Consent Revocation Endpoint - Resource owners (end-users), who
authenticate and authorize client applications using the browser-based
authorization endpoint flow, use this endpoint to revoke their consent to client
applications. For example:
http(s)://<host>:<port>/ms_
oauth/oauth2/ui/<yourOauthServiceName>/showrevokeconsent
When configuring clients with authorization code grant in the OAuth server, you also
need to provide at least one client redirect URI where the server can return
authorization credentials to the client.
■Client Redirect URIs – The OAuth Services server returns authorization
credentials to the client using the URI specified in the request provided that it
exactly matches a URI configured in the client profile.
52.7 Enforcing Access Control
Typically, an OAuth Services client application makes REST calls to services deployed
on remote servers. These calls, carrying an access token, need to be validated before
the call can go through. Enforcing access control is accomplished by sending a
previously obtained access token to a resource server defined in OAuth Services.
Exceptions to this are the native User Profile and Consent Management Services that
are enforced by OAuth Services.
The options for validation within the Oracle stack are Oracle API Gateway (OAG) and
Oracle Web Services Manager. (An OAG filter validates the Oracle Access
Management OAuth Services token before allowing access to the resource.) Custom
code can also be written to provide access control.
52.8 Understanding Mobile OAuth Services Server-Side Single Sign-on
The server-side single sign-on (SSO) feature allows multiple mobile apps on a device
to share a single user session that resides on the OAM server and not with the client.
This feature saves JWT and OAM user tokens in the Server-Side Device Store, and
maintains the user session in the browser with cookies. Thus, the server session is not
tied to the client. Session time-out values are configurable at the Service Profile level
for the client token, user token, and access token. The access token time-out value can
also be overridden at the Resource Server level.
Keeping sensitive session info on the server (and not on the device) reduces the risk of
the tokens being copied if the device or client app is compromised. For 2-legged flows,
if server-side single sign-on is turned off (it is on by default), the user token is not
stored on the server but sent to the client on the mobile device. You can enable and
Note: WebGates do not support validating access tokens.
Understanding Mobile OAuth Services Server-Side Single Sign-on
52-22 Administrator's Guide for Oracle Access Management
disable this feature using the Mobile OAuth Services Service Profile configuration
page. For 3-legged flows, server-side single sign-on is always automatically enabled.
■Understanding the Server-Side Single Sign-On Credential Collection Options
■Understanding Server-Side SSO For Mobile OAuth Services 3-Legged Flows
■Understanding Server-Side SSO For Mobile OAuth Services 2-Legged Flows
52.8.1 Understanding the Server-Side Single Sign-On Credential Collection Options
Developers in your organization can implement single sign-on in a client app by using
an external browser, an embedded browser, or by using a native app registered with
Mobile and Social Services as an SSO proxy. This section briefly discusses the different
approaches.
■Using the External Browser Approach
■Using the Embedded Browser Approach
■Using the Native App Proxy Approach
52.8.1.1 Using the External Browser Approach
In this approach the mobile app switches to an external browser, which executes the
logic for user authentication and user consent management. A shared browser cookie
maintains the user session and can be used to provide SSO across multiple apps. The
external browser uses a typical Web SSO mechanism that supports OAM user
authentication, JWT user authentication, third-party user authentication, and social
authentication (using the Social Identity service). One drawback to using an external
browser is the screen “flickering” that occurs when the application context switches
between the browser and the application.
52.8.1.2 Using the Embedded Browser Approach
In this approach the mobile app uses its own embedded browser. Because the browser
cookie cannot be shared across multiple apps, OAM and third-party user
authentication cannot be used. Instead, Mobile OAuth Services uses a JWT user
session token stored in the Server-Side Device Store. When additional apps are
launched, SSO is established using device identification together with the shared JWT
user session token. The embedded browser approach eliminates the screen “flickering”
that occurs when the application context switches between the application and the
external browser (as discussed in Using the External Browser Approach).
52.8.1.3 Using the Native App Proxy Approach
In this approach, if a native app is already installed on the device, it can facilitate SSO
by serving as a proxy between the browser-based app and the Mobile OAuth Services
SSO Servlet on the OAM server. As needed, the Servlet registers the device and app
with OAM and obtains the tokens required to authenticate the app in the browser so
that it can access the OAM-protected resource. To use this approach, native apps must
use Mobile and Social Services to authenticate with Access Manager. This approach
can be used for 2-legged flows.
52.8.2 Understanding Server-Side SSO For Mobile OAuth Services 3-Legged Flows
Server-side SSO is always enabled for Mobile OAuth Services 3-legged scenarios. The
Mobile OAuth Services server executes the logic for user authentication and user
consent management, collects the user credentials, and provides the required SSO
functionality. Users log in once and gain access to all systems without being prompted
Understanding Mobile OAuth Services Server-Side Single Sign-on
Understanding OAuth Services 52-23
to log in again. For JWT, third-party, and social authentication, the OAM server stores
the user token in the Device Store, whereas OAM authentication stores the OAM_ID
(representing an OAM session) in the Device Store. When the user token or OAM_ID
expires, the user is prompted to log in again.
When implementing mobile 3-legged scenarios, enable the Authorization Code grant
type by going to the Mobile OAuth Services Clients configuration page in the Oracle
Access Management Console. Apps should implement the mobile 3-legged flows
documented in the Oracle Fusion Middleware Developer's Guide for Oracle Access
Management.
Apps that use a Mobile OAuth Services 3-legged scenario should collect credentials
using a mobile browser (as discussed in Understanding the Server-Side Single Sign-On
Credential Collection Options). To specify an authentication type using the Oracle
Access Management Console, open the Mobile OAuth Services Service Profile
configuration page and under Mobile Service Settings, choose an option for Consent
Service Protection. The following sections describe these options.
OAM Authentication or Third-Party Access Management
If using OAM authentication or Third-Party Access Management, Access Manager (or
a third-party access management product) is responsible for user authentication. Any
OAM authentication method that supports login through the browser is an option.
Because Access Manager supports SSO using an OAM_ID cookie, this flow must use
an external browser (as discussed in Using the External Browser Approach). Following
authentication, the user token is stored in the Server-Side Device Store.
Oracle Access Management supports session synchronization so that 2-legged flows
can get OAM tokens later. For example, the first app registers with the server using the
3-legged flow. Next, a second app completes the 2-legged registration using the
existing session established by the first app. Thus a 3-legged flow session can register
additional apps using a 2-legged flow by using the same session created during the
first app registration.
JWT Authentication
JWT authentication is an authentication mechanism provided by Mobile and Social for
mobile applications. In this case, Mobile and Social hosts the user interface for user
login. It accepts a user name and password for authentication, using the configured
user store for user authentication. The user store can be configured in Mobile and
Social or in Oracle Access Management. It is configured using the User Authenticator
under User Store in OAuth Services profile.
As discussed previously, JWT user authentication is the only authentication type that
supports single sign-on using an embedded browser. (If the ability to use multiple
apps on the same mobile device is not a requirement, then either OAM authentication
or third-party authentication is sufficient.) JWT authentication can also be used with
external browsers, but the application will need to switch from the app to the browser
and back again when Mobile and Social checks the user token in the Device Store for
single sign-on.
Social Authentication
Social authentication allows app users to authenticate using social identity providers
such as Facebook and Twitter. This type of authentication requires the Oracle Access
Management Social Identity service (part of Mobile and Social). If using social
authentication, the Oracle Access Management server redirects the user to the social
identity provider for authentication. For single sign-on, an external browser is
Understanding Mobile OAuth Services Server-Side Single Sign-on
52-24 Administrator's Guide for Oracle Access Management
required. Following authentication, the user token is stored in the Server-Side Device
Store. Social Authentication is supported for 3-legged flows only.
52.8.3 Understanding Server-Side SSO For Mobile OAuth Services 2-Legged Flows
Apps that use Mobile OAuth Services 2-legged scenarios should collect user
credentials using the native iOS or Android user interface although you are limited to
username/password-based OAM authentication or IDS (directory server). By
switching to an external browser, you can use the usual supported authentication
schemes, including OAM user authentication, third-party authentication, and JWT
user authentication.
Unlike with mobile 3-legged scenarios, you can choose to disable the server-side single
sign-on feature with mobile 2-legged scenarios. To disable it, open the Mobile OAuth
Services Service Profile Configuration page and clear the Enable Server-Side Single
Sign-On option. (Server-Side SSO can also be set using WLST.)
■If Server-Side SSO is enabled, the server collects user credentials on behalf of the
client and provides SSO. Additional apps (that is, apps that share the same device
profile) have to register with the server the first time they are launched. You can
require the user to authenticate every time an app is registered, or you can allow
the registration to happen automatically in the background without involving the
user. Configure the
msAlwaysShowLogin
attribute on the Service Profile page to
select the desired behavior.
■If the
msAlwaysShowLogin
Service Profile attribute is set to true, the user has to
enter a user name and password in the native app to register the app and get a
client token.
■If the attribute is set to false, the server automatically registers apps using the
server-side user token.
Once registered, subsequent access requests from apps on the device typically
result in the server providing a client token and allowing access. (In some cases the
user may not get access right away—for example, if Oracle Adaptive Access
Manager rules are active.)
■If Server-Side SSO is disabled, the client collects the user credentials and must also
provide SSO. On a first access attempt the user enters a user name and password
in the native app to register the device. The server returns a user token that the
device stores locally. Subsequent access requests from apps on the device must use
the stored user token to register the apps and gain access.
For mobile 2-legged scenarios, enable the Resource Owner grant type by going to the
Mobile OAuth Services Clients configuration page in the Mobile Oracle Access
Management Console. Apps should implement the mobile 2-legged flows documented
in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management. The
following sections give an overview of SSO options.
■Using the OAuth Mobile SSO Servlet Authentication
■Using SSO Between Native Apps and an External Browser
52.8.3.1 Using the OAuth Mobile SSO Servlet Authentication
If a user using a mobile browser (external or embedded) needs to access a protected
Web resource, and there is a native app that uses Mobile and Social Services to
authenticate with OAM already installed on the device, the native app can register the
device on behalf of the Web app and gain access to the resource without requiring the
user to sign on. This single sign-on approach utilizes the OAuth Mobile SSO Servlet
Understanding OAuth Services Plug-ins
Understanding OAuth Services 52-25
that was added to the OAM server in release 11.1.2.3. For configuration steps, see
Section 53.7, "Configuring Mobile OAuth for SSO Servlet Authentication."
52.8.3.2 Using SSO Between Native Apps and an External Browser
Another alternative utilizing a native app and an app running in an external browser
is to implement 2-legged flows in the native app using the OAuth Services REST API.
(Server-side SSO can be enabled or disabled.) The native app registers the device and
user, and exchanges an OAM token to get an OAM_ID cookie (which is the OAM
master token). The native app can then launch the external browser and inject the
OAM_ID cookie so that users accessing WebGate-protected resources with an external
browser will not be prompted to log in every time. For information about
implementing the 2-legged flows, see the Oracle Fusion Middleware Developer's Guide for
Oracle Access Management.
52.9 Understanding OAuth Services Plug-ins
Oracle Adaptive Access Manager (OAAM) is an optional product that can screen
Mobile OAuth Services transactions using a provided security plug-in. Together,
OAAM and the plug-in provide mobile-client fraud detection, knowledge-based
authentication (for two-factor authentication after user name and password
authentication), and one time password functionality. If the Oracle Mobile Security
Suite is deployed, the Mobile Security Manager plug-in gathers additional mobile
device data for OAAM to screen.
To use OAAM with Mobile OAuth Services, the Adaptive Access security plug-in
must be installed. This plug-in can add value during app registration when client
tokens or user tokens are being validated or refreshed, and during token exchange.
OAAM rules and policies are defined in Oracle Adaptive Access Manager. The
following is a brief description of the OAAM and Adaptive Access Plug-in features.
■The Adaptive Access Plug-in enhances security by screening mobile app
registration requests for both 2-legged and 3-legged flows. The plug-in runs fraud
detection and risk analysis policy checks.
■Knowledge-based authentication (KBA) and one time password authentication
(OTA) can also be integrated into the mobile app registration process. The OAuth
Service REST API flows include sample challenge requests and responses that a
developer will need to implement in your app(s).
■Following registration, the Adaptive Access Plug-in screens user tokens for
security violations instead of simply checking if the user token is valid. The result
of this screening is either allowed or denied.
Using the Mobile Security Manager Plug-in Together With the Adaptive Access
Plug-in
The Mobile Security Manager Plug-in is for use with Oracle Mobile Security Suite
(OMSS). The Mobile Security Manager (MSM) component (part of OMSS) collects a
rich set of mobile device data and passes it to the Adaptive Access Plug-in for use by
OAAM. If Oracle Mobile Security Suite is not available, the Adaptive Access plug-in
uses mobile device attribute values that the Mobile OAuth Services server obtains
during mobile app requests.
Understanding OAuth Services Plug-ins
52-26 Administrator's Guide for Oracle Access Management
If the Mobile Security Manager Plug-in is active, it runs first and sends its data to the
Adaptive Access Plug-in, which runs second. The Adaptive Access Plug-in checks the
results of the MSM compliance policy that reports the compliance status of the device.
If the compliance policy response is negative, the Adaptive Access Plug-in denies the
mobile app request; If the response is positive, the Adaptive Access Plug-in passes the
device data to Oracle Adaptive Access Manager for stronger authentication checks and
risk evaluation. The Mobile Security Manager plug-in gets device info and checks the
MSM compliance policy in the following cases:
■During the app registration flow following user authentication.
■As part of the client token and user token validation process.
For more information:
■See "Understanding OAuth Services Authorization for Mobile Clients" for a
detailed look at when in the Mobile OAuth Services flow OAAM interacts with
mobile apps.
■See Section 52.4.6, "Understanding Plug-Ins" for summary information about the
various OAuth Services plug-ins.
■See Section 53.3.8, "Configuring Plug-Ins" for information about configuring the
adaptive-access plug-in.
Note: The Mobile Security Manager plug-in requires special
configuration before it can be used. See Section 53.8, "Configuring the
Mobile Security Manager Plug-in" for details.
53
Configuring OAuth Services 53-1
53
Configuring OAuth Services
[35]
Oracle Access Management provides a graphical user interface for configuring OAuth
Services. The configuration options are available within the Identity Federation or
Mobile Services interfaces depending on the licensing procured.
This chapter describes how to use the Oracle Access Management Console to enable
OAuth Services and configure the OAuth Services components.
■Enabling OAuth Services
■Configuring OAuth Services Components in an Identity Domain
■Configuring OAuth Services Settings
■Configuring OAuth Services for Third-Party JWT Bearer Assertions
■Configuring a WebGate to Protect OAuth Services
■Configuring OAM Session Synchronization
■Configuring Mobile OAuth for SSO Servlet Authentication
■Configuring the Mobile Security Manager Plug-in
53.1 Enabling OAuth Services
Oracle Access Management OAuth Services has to be explicitly enabled in order to use
it. A license for Oracle Access Management Identity Federation (if using web clients
only) or Mobile and Social (if using web and mobile clients) is required to enable it.
Once correct licensing is procured, enable Identity Federation or Mobile and Social by
clicking Available Services in the Configuration Launch Pad of the Oracle Access
Management Console. These section links contain more details.
■Section 2.4, "Understanding the Oracle Access Management Console"
■Section 3.2, "Enabling or Disabling Available Services"
■Section 37.8, "Enabling Identity Federation"
■Section 48.1.3, "Enabling Mobile and Social"
Note: OAuth Services can be configured from the command line
using WLST. For more information about the Mobile and Social WLST
commands, see the Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.
Configuring OAuth Services Components in an Identity Domain
53-2 Administrator's Guide for Oracle Access Management
53.2 Configuring OAuth Services Components in an Identity Domain
In order to use Oracle Access Management OAuth Services, you will need to configure
an Identity Domain. OAuth Services ships with a default Identity Domain named
DefaultDomain. You can create additional domains as needed. Each OAuth Services
Identity Domain has a universally unique identifier (UUID) that specifically identifies
it on the Internet.
Access to the Identity Domain configuration page is dependent on whether you have
enabled Identity Federation OAuth Services or Mobile and Social OAuth Services.
Figure 53–1 contains two screenshots: the top displays the Mobile OAuth Identity
Domains and the bottom displays the Federation (web only) OAuth Identity Domains.
Note that both contain the DefaultDomain. To access the appropriate page, do the
following.
■Click Mobile Security at the top of the Oracle Access Management Console and
then click Mobile OAuth Services.
■Click Federation at the top of the Oracle Access Management Console and then
click OAuth Services.
Figure 53–1 Mobile (top) and Federation (bottom) Identity Domain Screens
Figure 53–2 is a screenshot of the Identity Federation OAuth Services DefaultDomain
configuration page. To access this page, click DefaultDomain (or any custom domain
that might have been created) from the Identity Federation Identity Domain
configuration page. (If OAuth Services is accessed by clicking a Mobile Security
configured domain, a third OAuth Mobile Clients table is also displayed on the Clients
tab of the selected domain.)
Configuring OAuth Services Settings
Configuring OAuth Services 53-3
Figure 53–2 Identity Federation DefaultDomain Configuration Page
When accessing the Identity Domain configuration page through Mobile Security, the
Jailbreak Detection Policy tab is included with those previously listed for Identity
Federation. Figure 53–3 is a screenshot of the Mobile Security OAuth Services
DefaultDomain configuration page with the Jailbreak Detection Policy page displayed.
To access this page, click DefaultDomain (or any custom domain that might’ve been
created) from the Mobile Security Identity Domain configuration page.
Figure 53–3 Mobile Security DefaultDomain Configuration Page
The Identity Domains pages list all configured OAuth Services Identity Domains.
When the list is displayed, you can create a new Identity Domain by clicking Create
Using Single Step or Create Using Wizard Flow. Click a domain name to modify an
already configured profile.
53.3 Configuring OAuth Services Settings
OAuth Services has many components that must be configured before the
authorization protocol can be used. Descriptions of the OAuth Services components
and how they work together can be found in Section 52.4, "Understanding the OAuth
Services Components." This section includes information on configuring the OAuth
Configuring OAuth Services Settings
53-4 Administrator's Guide for Oracle Access Management
Services components using the Oracle Access Management Console only. It contains
the following topics:
■Configuring Identity Domains
■Configuring Service Profiles
■Configuring Clients
■Configuring the Service Provider
■Configuring Custom Resource Servers
■Configuring User Profile Services
■Configuring Consent Management Services
■Configuring Plug-Ins
■Configuring Server Settings
■Configuring the Jailbreak Detection Policy
■Configuring Token Life Cycle Management
53.3.1 Configuring Identity Domains
See Section 53.2, "Configuring OAuth Services Components in an Identity Domain" for
introductory information about Identity Domains. The following section describes
how to use the user interface to configure an Identity Domain. It includes the
following topics:
■Creating an Identity Domain
■Editing or Deleting an OAuth Identity Domain
■Understanding the Identity Domain Configuration Page - Summary Tab
■Understanding the Create Identity Domain Wizard Flow
53.3.1.1 Creating an Identity Domain
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain."
2. Choose one of the following:
■To quickly create an Identity Domain with only basic information, click Create
using single step (leftmost + button in the toolbar).
The Identity Domain Configuration page opens.
Complete the form and click Create to save your changes. You will need to
provide additional configuration detail later.
■To create an Identity Domain and configure essential Service Profile settings,
click Create using wizard flow (rightmost + button in the toolbar).
The Create OAuth Identity Domain wizard flow page opens.
Click Back and Next to move backwards and forward through the wizard
flow. Click Finish to save your changes.
53.3.1.2 Editing or Deleting an OAuth Identity Domain
1. Open the Identity Domains page as described in Section 53.2, "Configuring OAuth
Services Components in an Identity Domain."
Configuring OAuth Services Settings
Configuring OAuth Services 53-5
■To view or edit an Identity Domain, click its name in the table.
■To delete an Identity Domain, select it by clicking the column to the left of the
domain name and then click the delete button in the command bar.
53.3.1.3 Understanding the Identity Domain Configuration Page - Summary Tab
This section describes the form fields on the Identity Domain Configuration Summary
tab when viewing an existing identity domain or creating a new one.
Identity Domain - The name of the identity domain. If creating or editing an identity
domain, type a unique name without spaces.
Description - (Optional) A short description to help you or another administrator
identify this identity domain in the future.
Identity Domain UUID - The identification code that uniquely identifies this identity
domain on the Internet. Click Generate to populate this field with a universal unique
identifier code.
Allow Multiple Resource Servers - Select this option if the identity domain supports
more than one resource server.
The fields listed below appear on the Create Identity Domain page.
Service Profile
(Service Profile) Name - The name of the identity domain's service profile. Each
identity domain requires at least one service profile. See Section 52.4.2,
"Understanding Service Profiles" for more information.
(Service Profile) Endpoint - The URL where the OAuth authorization service for this
identity domain responds to authorization requests.
User Profile Service
(User Profile Service) Name - The name of the identity domain's user profile service.
A user profile service is created automatically for each identity domain. See
Section 52.4.5, "Understanding Resource Servers" for more information.
(User Profile Service) Endpoint - The URL where the User Profile Service receives and
responds to create, read, update, and delete requests.
Consent Management Service
(Consent Management Service) Name - The name of the identity domain's consent
management service. Each identity domain must have a consent management service,
which stores and retrieves consent records, and performs consent validation and
consent revocation operations. See Section 52.4.6, "Understanding Plug-Ins" for more
information.
(Consent Management Service) Endpoint - The URL where the Consent Management
Service receives and responds to client and resource owner service requests.
Note: Selecting multiple resources requires that scopes are prefixed
with the Resource Server name. For example, if you add PhotoService
as a Resource Server, the scopes must be prefixed with PhotoService.
This is done automatically while adding scopes in the Resource
Server. The prefix can be changed to something different but unique.
Configuring OAuth Services Settings
53-6 Administrator's Guide for Oracle Access Management
53.3.1.4 Understanding the Create Identity Domain Wizard Flow
For help understanding the form fields on the Create OAuth Identity Domain wizard
flow pages, refer to the following sections.
■Information - For help, see Section 53.3.1.3, "Understanding the Identity Domain
Configuration Page - Summary Tab."
■Service Profile - For help, see Section 53.3.2.3, "Understanding the Service Profile
Configuration Page."
■Mobile Service - For help, see "Mobile Service Settings" in Section 53.3.2.3.
■Tokens - For help, see "Tokens (Token Settings)" in Section 53.3.2.3.
■Summary - Review your settings and click Finish to create the identity domain.
53.3.2 Configuring Service Profiles
See Section 52.4.2, "Understanding Service Profiles" for introductory information about
Service Profiles. The following section describes how to use the user interface to
configure a Service Profile. It includes the following topics:
■Creating a Service Profile
■Editing or Deleting a Service Profile
■Understanding the Service Profile Configuration Page
53.3.2.1 Creating a Service Profile
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it.
2. Select the Service Profiles tab.
3. Click Create to complete the wizard.
53.3.2.2 Editing or Deleting a Service Profile
1. Open the Identity Domains page as described in Section 53.2, "Configuring OAuth
Services Components in an Identity Domain" and click an identity domain to open
it for editing.
2. Click the Service Profiles tab.
3. Do the following:
■To edit a service profile, click its name in the table.
■To delete a service profile, select it by clicking the box to the left of the name
and then click the delete button in the command bar.
53.3.2.3 Understanding the Service Profile Configuration Page
Identity Domain - The name of the identity domain to which this service profile
applies. (Read-only)
Name - The name of this service profile.
Description - (Optional) A short description to help you or another administrator
identify this service profile in the future.
Service Enabled - Select to activate the service profile, or clear the option box to
inactivate it.
Configuring OAuth Services Settings
Configuring OAuth Services 53-7
Service Provider - The name of the OAuth Service Provider that corresponds with this
OAuth Service Profile.
Service Endpoint - The URL where the OAuth authorization service responds to
authorization requests.
User Store
User Authenticator - For user authentication, choose OAM to use the Oracle Access
Management token provider, or choose IDS to use the Identity Directory Service token
provider. Only choose IDS authentication if the OAM token is not used at all (for
example, if only the JWT token is used). If both OAM and JWT tokens are used, choose
OAM authentication to avoid duplicated authentication attempts sent by both IDS and
OAM.
Identity Store Name - The name of the identity store when IDS is configured as the
user authenticator.
User Profile Service
(User Profile Service) Name - The name of the identity domain's user profile service.
A user profile service is created automatically for each identity domain. See
Section 52.4.5.1, "Understanding User Profile Services" for more information.
(User Profile Service) Endpoint - The URL where the User Profile Service receives and
responds to create, read, update, and delete requests.
Consent Management Service
(Consent Management Service) Name - The name of the identity domain's consent
management service. Each identity domain must have a consent management service,
which stores and retrieves consent records, and performs consent validation and
consent revocation operations. See Section 52.4.5.2, "Understanding Consent
Management Services" for more information.
(Consent Management Service) Endpoint - The URL where the Consent Management
Service receives and responds to client and resource owner service requests.
Plug-Ins
Choose available plug-ins from the menus in the following categories. See
Section 52.4.6, "Understanding Plug-Ins" for more information.
Adaptive Access - Runs Oracle Adaptive Access Manager (OAAM) fraud detection
and risk analysis policy checks, enhancing authenticity and the trust level of a user.
Mobile Security Manager - Gathers mobile device data from the Mobile Security
Manager (MSM) component (part of Oracle Mobile Security Suite) and sends it, as well
as the MSM compliance status, to the Adaptive Access Plug-in for stronger
authentication checks and risk evaluation.
Custom Token Attributes - Defines security policy around the token service provider.
See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
information.
Client - Delegates the following to an external security module: confidential client
authentication, client authorization, and client profile reading.
Resource Server Profile - Delegates the following to an external security module:
confidential resource server authentication, resource server authorization, and
resource server profile reading.
Configuring OAuth Services Settings
53-8 Administrator's Guide for Oracle Access Management
Authorization & Consent Service - Defines security policy around interactions where
authorization and user consent are granted. This plug-in can influence claims in a
generated token as well.
Attributes
Add or delete service profile attributes and their values to further configure the OAuth
service profile.
For JWT token generation and validation, configure the following parameters:
■
jwt.cert.alias
■
jwt.trusted.issuer.size
■
jwt.trusted.issuer.1
■
jwt.trusted.issuer.2
Note: For details, see Section 53.4, "Configuring OAuth Services for
Third-Party JWT Bearer Assertions."
Table 53–1 OAuth Service Profile Configuration Attributes
Name Value Notes
jwt.cert.alias
Private key alias name for the signing
certificate in the keystore. The default
alias will be used if this attribute is not
specified.
jwt.CryptoScheme RS512
The cryptographic algorithm used to sign
the contents of the JWT token. The default
value is
RS512
. (RSA encryption using
SHA-512 hash algorithm.)
jwt.issuer www.oracle.example.
com
This issuer of the tokens (that is, the
iss
claim value in the JWT token generated
by OAuth Services). The default value,
www.example.oracle.com
,needs to be
changed in the deployment.
jwt.trusted.issuer.size
2 The number of trusted issuers. The value
can be any number of trusted issuers. For
example, if the number is 2, the following
matching params need to be specified.
jwt.trusted.issuer.1
The alias name for the public key of the
first trusted issuer in the key store. See
jwt.trusted.issuer.size
for details.
jwt.trusted.issuer.2
The alias name for the public key of the
second trusted issuer in the key store. See
jwt.trusted.issuer.size
for details.
createdByDefault true
If set to true, the current OAuth Services
profile is created automatically as part of
domain creation. Otherwise, it's created
manually.
Configuring OAuth Services Settings
Configuring OAuth Services 53-9
Mobile Service Settings
Supported Platforms - Choose iOS, Android, and/or Others:
■iOS - The authorization server accepts requests from iOS clients if selected.
■Android - The authorization server accepts requests from Android clients if
selected.
■Others - The authorization server accepts requests from clients other than iOS or
Android if selected.
iOS Security Level - Choose Advanced or Standard:
■Advanced - All client registrations and token acquisitions are done using both
push notification and HTTP(S).
clientPWDValidation false
If set to true, a client ID and secret
(password) can be used as credentials to
interact with OAuth Services for token
validation and termination requests.
If set to false, only a JWT/SAML client
assertion can be used as client credentials
to interact with OAuth Services for token
validation and termination requests.
tokenTenantClaimName
user.tenant.name
The tenant claim name in the tokens
issued by OAuth Services. By default this
is set using the identity domain name.
oauthServerSelfClientId
Value to be specified By default this is set with the value of the
jwt.issuer attribute
. This attribute
gets used when OAuth Services generates
a client assertion for itself when
interacting with other services such as
service-to-service interactions.
oauthServerSelfCTValidi
tyInSec
Value in seconds to be
specified
The default value is
300sec
. This attribute
is related to
oauthServerSelfClientId
(that is, the OAuth Services own client
assertion validity period).
msAlwaysShowLogin true/false
This attribute applies to mobile clients
using the JWT SSO authentication
mechanism. It is used with 2-legged flows
only. (For 3-legged flows, the browser
manages the session.)
true - The user must authenticate for each
app registration. (Mobile apps are not
registered using the server-side JWT user
token.) OAuth Services shows a login
page for the user to submit credentials.
false - Mobile apps are registered using
the server-side JWT user token.
By default
true
.. If this attribute is not
defined in the service profile, the server
does not allow mobile apps to use the
server-side user token to register without
a user name and password. For more
information see Section 52.8.3,
"Understanding Server-Side SSO For
Mobile OAuth Services 2-Legged Flows."
Table 53–1 (Cont.) OAuth Service Profile Configuration Attributes
Name Value Notes
Configuring OAuth Services Settings
53-10 Administrator's Guide for Oracle Access Management
■Standard - All client registrations and token acquisitions are done using HTTP(S)
Android Security Level - Choose Advanced or Standard:
■Advanced - All client registrations and token acquisitions are done using both
push notification and HTTP(S).
■Standard - All client registrations and token acquisitions are done using HTTP(S)
Android Sender ID - Enter the GCM sender ID that is required for Android push
notification.
Android API Key - Enter the API key required for Android push notification.
Consent Service Protection - Authorization requests are routed to the consent service,
which requires the user to log in and give consent. Select OAM or Third-Party Access
Management, JWT Authentication, or Social Authentication.
■OAM or Third-Party Access Management - Use either Oracle Access
Management or a third-party option for consent page protection.
■JWT Authentication - Use the OAuth server itself for consent page protection. If
using the OAuth server for consent page protection, the authentication flow is
determined by the User Store setting.
■Social Authentication - Use the Social Identity service for consent page
protection.
Require User Consent for Client Registration - Select this option to require the user to
give authorization before registering each Mobile OAuth application installation
instance on a mobile device.
Enable Server-Side Single Sign-On - Determines if the server will provide single
sign-on among multiple apps on the same device or if it is the client responsibility.
Single sign-on is either achieved by storing a JWT user token or an OAM user token in
the Server-Side Device Store, or by returning the user token to the client to manage.
Server-side SSO applies to 2-legged Mobile OAuth flows only. If this option is selected,
after registering the first app the server stores the user token and does not return it to
the mobile device. If this option is not selected, the tokens are sent to the mobile device
and are not stored in the Server Device Store. For more information, see Section 52.8,
"Understanding Mobile OAuth Services Server-Side Single Sign-on."
Preferred Hardware IDs - Use the list to prioritize the hardware ID attributes that
should be used to uniquely identify mobile devices. The first available hardware ID
from the list will be used.
Mobile Client Attributes - Add or delete mobile client attributes and their values as
needed if the server requires additional attributes.
Configuration Settings
Clients
Allow access to all clients - Select if all clients in the identity domain should use this
service profile. Clear this option to select which clients will be able to access the service
profile.
Client Table - Add to the table the clients that should be able to access the service
profile. Click Browse Clients, then select the clients to add to the table. To assign a
client to a different service profile, click the box to the left of the client name and click
Remove.
Configuring OAuth Services Settings
Configuring OAuth Services 53-11
Tokens (Token Settings)
Use this tab to configure token settings, as well as settings for custom attribute that
OAuth Services should embed in access tokens.
Tokens
■Token Name - The name of the token.
■Expires - The length of time in minutes after which the token is no longer valid.
■Refresh Token Enabled - Select this option to allow a refresh token to be used. A
refresh token cannot be used with a client verification code or an authorization
code. See Section 52.5, "Understanding OAuth Services Tokens" for more
information.
■Refresh Token Expires - The length of time in minutes after which the refresh
token is no longer valid.
■Life Cycle Enabled - Select this option if OAuth Services should cache a token and
save it in the database until the token expires.
Custom Attributes
Use this section to define custom attributes that OAuth Services embeds in the access
tokens. See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
information about custom attributes.
■Static Attributes - Attribute name and value pairs where the value is fixed at the
time that you define the attribute. For example,
name1=value1
.
■Dynamic Attributes - User-profile specific attributes.
Resource Servers (Custom Resource Servers)
Use this tab to choose which custom resource servers clients should have access to. A
custom resource server is any resource server that is not the User Profile and Consent
Management resource servers that are included with OAuth Services.
Allow clients access to all resource servers - Select to allow clients to access all
resource servers configured in the identity domain. Clear this option to select which
resource servers clients will be able to access.
Available Servers / Selected Servers - Use the arrows to move the resource servers
that clients should be able to access from the Available Servers box to the Selected
Servers box. (This option is only available if the Allow clients access to all resource
servers option is not selected.)
System Resource Servers
Use this tab to configure if clients should have access to the user profile service and/or
consent management service.
User Profile Services -Use the arrows to move the user profile server that clients
should be able to access from the Available Servers box to the Selected Servers box.
Services listed in the Selected Servers box are active services.
Consent Management Services - Use the arrows to move the consent management
server that clients should be able to access from the Available Servers box to the
Selected Servers box. Services listed in the Selected Servers box are active services.
Configuring OAuth Services Settings
53-12 Administrator's Guide for Oracle Access Management
Trusted Issuers
Use this tab to add certificate issuers who can be used to validate tokens. Click Add to
add a record to the table; select a row and click Remove to delete a record from the
table.
Certificate Alias -The alias name.
Trusted Issuer - The name of the trusted certificate issuer.
Certificate Thumb Print - x5t - The base64url encoded digest of the DER encoding of
the X.509 certificate corresponding to the key used to digitally sign certificates.
Key identifier - kid - The key ID value that indicates which key is used to secure
certificates.
53.3.3 Configuring Clients
See Section 52.4.3, "Understanding Clients" for introductory information about OAuth
Services Clients. The following section describes how to use the user interface to
configure a Web client and a mobile client. It includes the following topics:
■Creating a Client
■Editing or Deleting a Client
■Understanding the Web Clients Configuration Page
■Understanding the Mobile Clients Configuration Page
53.3.3.1 Creating a Client
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it.
2. Select the Clients tab.
3. Click Create and a Create Client tab will open as follows.
■To create an OAuth Services Web (non-mobile) client, click the Create button
located directly under the OAuth Web Clients heading.
See Understanding the Web Clients Configuration Page.
■To create an OAuth Services Public client, click the Create button located
directly under the OAuth Public Clients heading.
See Understanding the Public Clients Configuration Page.
■To create an OAuth Services mobile client, click the Create button located
directly under the OAuth Mobile Clients heading.
See Understanding the Mobile Clients Configuration Page.
4. Enter the appropriate values in the form displayed under the Create Client tab.
53.3.3.2 Editing or Deleting a Client
1. Open the Identity Domains page as described in Section 53.2, "Configuring OAuth
Services Components in an Identity Domain" and click an identity domain to open
it for editing.
2. Click the Clients tab.
3. Do the following:
Configuring OAuth Services Settings
Configuring OAuth Services 53-13
■To edit a client configuration, click its name on the page.
The client configuration page opens in a new tab.
■To delete a client, select it by clicking the box to the left of the name and then
click the delete button in the command bar.
53.3.3.3 Understanding the Web Clients Configuration Page
This section describes the form fields on the Web Client Configuration page when
viewing an existing Web client or creating a new one. The Mobile OAuth Client
Configuration page is described in the next section.
Identity Domain - The name of the identity domain in which this OAuth Web client is
registered. (Read-only)
Name - The name of this OAuth client.
Description - (Optional) A short description to help you or another administrator
identify this OAuth Web client in the future.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with resource servers and the resource
owner. See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
information about custom attributes.
Client ID - The unique ID that the authorization server created for this client during
registration. (Read-only).
Client Secret - A secret value known to the OAuth authorization service and the
client. The authorization service checks the client secret and the client ID when it
receives token endpoint requests from the client.
HTTP Redirect URIs - The client URIs that the OAuth server is allowed to redirect the
user-agent to once access is granted or denied.
Privileges
Bypass User Consent - If selected, the client will not ask for the user's explicit
authorization to access the user's protected resources. If this option is selected, this
setting overrides the resource server setting. Clear this option if the client should be
subject to the resource server setting.
Allow Access to all Scopes - If selected, the client can obtain an access token
regardless of scope limitations for any resource server in the identity domain. Clear
this option if the client should be subject to scope limitations.
Allowed Scopes - Lists the range of access the client has to the requested resources. To
grant additional access, click Add to add a row to the table, then choose from the
drop-down menu the scope to be added. To restrict access, select the scope that you
want to remove by clicking the table row, then click Delete to remove the highlighted
row. Click OK at the prompt to confirm that you want to remove the selected scope.
Grant Types - The OAuth 2.0 specification provides several authorization grant types
for different security use-cases. Before obtaining an access token, the client must obtain
an authorization grant that it can exchange with the OAuth service for an access token.
Client privileges determine which clients are allowed which grant types. The
following grant types are supported in OAuth Services:
■Authorization Code - This grant type is required for 3-legged flows. The resource
owner logs in using the authorization server. The token endpoint exchanges the
authorization code along with client credentials for an access token.
Configuring OAuth Services Settings
53-14 Administrator's Guide for Oracle Access Management
■Resource Owner Credentials - This grant type is used for 2-legged flows. The
resource owner provides the client with his or her user name and password. This
is only suitable for highly trusted client applications because the client could abuse
the password, or the password could unintentionally be disclosed to an attacker.
Per the OAuth 2.0 specification, the authorization server and client should
minimize use of this grant type and utilize other grant types whenever possible.
■Client Credentials - This grant type is used for 2-legged flows. The client requests
an access token using only its client credentials (or another supported means of
authentication). This is suitable if the client is requesting access to protected
resources under its control, or those of another resource owner when previously
arranged with the authorization server.
In addition to the grant types defined in the OAuth 2.0 standard, the following options
are also available:
■Refresh Token - Select this option to return a refresh token together with an access
token in the token response. See Section 52.5, "Understanding OAuth Services
Tokens" for more information.
■JWT Bearer - Allows a JWT assertion to be used to request an OAuth access token.
■SAML 2 Bearer - Allows a SAML2 assertion to be used to request an OAuth access
token.
■OAM Credentials - Used to request OAM tokens, such as a master token, an
access token, or an OAuth access token.
Attributes
Add or delete custom attributes that the authorization server returns to the client
along with the scope settings.
Avoid using the same name when adding custom attributes to the service profile
configuration and the scope configuration. If you define the same attribute name in
both locations, the scope-based attribute value takes precedence.
53.3.3.4 Understanding the Public Clients Configuration Page
This section describes the form fields on the Web Client Configuration page when
viewing an existing Web client or creating a new one. The Mobile OAuth Client
Configuration page is described in the next section.
Identity Domain - The name of the identity domain in which this OAuth Web client is
registered. (Read-only)
Name - The name of this OAuth client.
Description - (Optional) A short description to help you or another administrator
identify this OAuth Web client in the future.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with resource servers and the resource
owner. See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
Table 53–2 Web Client Attributes Names and Values
Name Value Notes
jwt.audience
Space separated values. Used when the OAuth server
generates a client assertion and a
user assertion. The
aud
claim for
those JWT tokens contain the
defined values in this token.
Configuring OAuth Services Settings
Configuring OAuth Services 53-15
information about custom attributes.
Client ID - The unique ID that the authorization server created for this client during
registration. (Read-only).
HTTP Redirect URIs - The client URIs that the OAuth server is allowed to redirect the
user-agent to once access is granted or denied.
Privileges
Bypass User Consent - If selected, the client will not ask for the user's explicit
authorization to access the user's protected resources. If this option is selected, this
setting overrides the resource server setting. Clear this option if the client should be
subject to the resource server setting.
Allow Access to all Scopes - If selected, the client can obtain an access token
regardless of scope limitations for any resource server in the identity domain. Clear
this option if the client should be subject to scope limitations.
Allowed Scopes - Lists the range of access the client has to the requested resources. To
grant additional access, click Add to add a row to the table, then choose from the
drop-down menu the scope to be added. To restrict access, select the scope that you
want to remove by clicking the table row, then click Delete to remove the highlighted
row. Click OK at the prompt to confirm that you want to remove the selected scope.
Grant Types - The OAuth 2.0 specification provides several authorization grant types
for different security use-cases. Before obtaining an access token, the client must obtain
an authorization grant that it can exchange with the OAuth service for an access token.
Client privileges determine which clients are allowed which grant types. The
following grant types are supported in OAuth Services:
■Authorization Code - This grant type is required for 3-legged flows. The resource
owner logs in using the authorization server. The token endpoint exchanges the
authorization code along with client credentials for an access token.
■Implicit - This grant type is used for 2-legged flows. The resource owner provides
the client with his or her user name and password. This is only suitable for highly
trusted client applications because the client could abuse the password, or the
password could unintentionally be disclosed to an attacker. Per the OAuth 2.0
specification, the authorization server and client should minimize use of this grant
type and utilize other grant types whenever possible.
Attributes
Add or delete custom attributes that the authorization server returns to the client
along with the scope settings.
Avoid using the same name when adding custom attributes to the service profile
configuration and the scope configuration. If you define the same attribute name in
both locations, the scope-based attribute value takes precedence.
53.3.3.5 Understanding the Mobile Clients Configuration Page
This section describes the form fields on the Mobile Client Configuration page when
viewing an existing Mobile client or creating a new one. The OAuth Web Client
Configuration page is described in the previous section.
Identity Domain - The name of the identity domain in which this OAuth mobile client
is registered. (Read-only)
Name - The name of this OAuth client.
Configuring OAuth Services Settings
53-16 Administrator's Guide for Oracle Access Management
Description - (Optional) A short description to help you or another administrator
identify this OAuth mobile client in the future.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with resource servers and the resource
owner. See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
information about custom attributes.
Client ID - The unique ID that the authorization server created for this client during
registration. (Read-only).
Jailbreaking Detection - Select to enable jail breaking detection for mobile devices. See
Section 52.4.8, "Understanding Jailbreak Detection Policy" for more information.
Mobile Redirect URIs - The client URIs that the OAuth server is allowed to redirect
the user-agent to once access is granted or denied.
Privileges
Bypass User Consent - If selected, the client will not ask for the user's explicit
authorization to access the user's protected resources. If this option is selected, this
setting overrides the resource server setting. Clear this option if the client should be
subject to the resource server setting.
Allow Access to all Scopes - If selected, the client can obtain an access token
regardless of scope limitations for any resource server in the identity domain. Clear
this option if the client should be subject to scope limitations.
Allowed Scopes - Lists the range of access the client has to the requested resources. To
grant additional access, click Add to add a row to the table, then choose from the
drop-down menu the scope to be added. To restrict access, select the scope that you
want to remove by clicking the table row, then click Delete to remove the highlighted
row. Click OK at the prompt to confirm that you want to remove the selected scope.
Grant Types - The OAuth 2.0 specification provides several authorization grant types
for different security use-cases. Before obtaining an access token, the client must obtain
an authorization grant that it can exchange with OAuth Services for an access token.
Client privileges determine which clients are allowed which grant types. The
following grant types are supported in OAuth Services:
■Authorization Code - This grant type is required for 3-legged flows. The resource
owner logs in using the authorization server. The token endpoint exchanges the
authorization code along with client credentials for an access token.
■Resource Owner Credentials - This grant type is used for 2-legged flows. The
resource owner provides the client with his or her user name and password. This
is only suitable for highly trusted client applications because the client could abuse
the password, or the password could unintentionally be disclosed to an attacker.
Per the OAuth 2.0 specification, the authorization server and client should
minimize use of this grant type and utilize other grant types whenever possible.
■Client Credentials - This grant type is used for 2-legged flows. The client requests
an access token using only its client credentials (or another supported means of
authentication). This is suitable if the client is requesting access to protected
resources under its control, or those of another resource owner when previously
arranged with the authorization server.
■Refresh Token - Select this option to return a refresh token together with an access
token in the token response. See Section 52.5, "Understanding OAuth Services
Tokens" for more information.
■JWT Bearer - Allows a JWT assertion to be used to request an OAuth access token.
Configuring OAuth Services Settings
Configuring OAuth Services 53-17
■SAML 2 Bearer - Allows a SAML2 assertion to be used to request an OAuth access
token.
■OAM Credentials - Used to request OAM tokens, such as a master token, an
access token, or an OAuth access token.
■Client Verification Code - Used by mobile clients to request a pre-verification
code from OAuth server, which subsequently gets used mobile client flows.
Apple Push Notification
Applies to iOS devices only. The OAuth authorization server can restrict token
delivery to a specific app installed on a specific mobile device by sending part of the
client registration handle through HTTPS, and sending the other part through push
notification using the Apple Push Notification Service (APNS). Use the following
fields to configure how the OAuth server connects to APNS for this specific client app.
Connection Settings - Select Enabled to send a portion of security codes and tokens to
the mobile client app using APNS. (The portions not sent using APNS are sent using
HTTPS.) Clear this option if you do not want to use APNS for this mobile client app.
Minimum Connection Pool Size - Specifies the minimum number of connections in
the connection pool.
Maximum Connection Pool Size - Specifies the maximum number of connections in
the connection pool.
Keep Alive - The Apple Push Notification keep alive value in seconds.
Certificate for APNS Communication Setup - Choose Development to use the Apple
development environment for initial development and testing of the application;
choose Production to use Apple's production environment.
SSL/TLS Certificate for Development - Click Browse to navigate to the development
SSL/TLS certificate issued by Apple for the Apple Push Notification Service.
Development Certificate Password - Type the development password for the Apple
Push Notification certificate.
SSL/TLS Certificate for Production - Click Browse to navigate to the production
SSL/TLS certificate issued by Apple for the Apple Push Notification Service.
Production Certificate Password - Type the production password for the Apple Push
Notification certificate.
Google Application Settings
Applies to Android devices only. The OAuth authorization server can restrict token
delivery to a specific app installed on a specific mobile device by sending part of the
client registration handle through HTTPS, and sending the other part through push
notification using Google Cloud Messaging (GCM) for Android. Use the following
fields to configure how the OAuth server connects to the GCM service for this specific
client app.
Restricted Package Name - The Google restricted package name.
Mobile Service Settings
Override the default settings - By enabling Override the default settings in a Mobile
Client profile, an administrator can set the security level and enable server-side single
sign on at the client level. When set, these client settings over ride same settings at the
OAuth Services Service Profile mobile configuration setting. This can be used if a
Configuring OAuth Services Settings
53-18 Administrator's Guide for Oracle Access Management
particular client in an identity domain needs a behavior that is different from what is
defined in the OAuth Services Service Profile.
Configuration Settings
Device Claim Attributes - Specifies the device attributes that the system should collect
for device fingerprinting. If empty, the system collects every attribute in the SDK.
Mobile Custom Attributes - Specifies key-value pairs that should be sent to mobile
applications using app profiles. (Mobile applications request app profiles that contain
server-side settings, including endpoints, jail break detection policies, and security
level details.
Attributes
Add or delete custom attributes that the authorization server returns to the client
along with the scope settings.
Avoid using the same name when adding custom attributes to the service profile
configuration and the scope configuration. If you define the same attribute name in
both locations, the scope-based attribute value takes precedence.
53.3.4 Configuring the Service Provider
See Section 52.4.4, "Understanding Service Providers" for introductory information
about Service Providers. The following section describes how to use the user interface
to configure a Service Provider. It includes the following topics:
■Editing or Deleting the Service Provider
■Understanding the Service Provider Configuration Page
53.3.4.1 Editing or Deleting the Service Provider
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it for editing.
2. Select the Service Providers tab.
3. Do the following:
■To edit a service provider, click its name in the table.
■To delete a service provider, select it by clicking the box to the left of the name
and then click the delete button in the command bar.
53.3.4.2 Understanding the Service Provider Configuration Page
This section describes the form fields on the Service Provider Configuration page.
Identity Domain - The name of the identity domain with which this Service Provider
is registered. (Read-only)
Name - The name of this service provider.
Description - (Optional) A short description to help you or another administrator
identify this service provider.
Service Provider Java Class - The Java class that implements this service provider.
Note: Only one Service Provider can be configured at a time.
Configuring OAuth Services Settings
Configuring OAuth Services 53-19
Attributes
Use the attribute settings in Table 53–3 to configure the Service Provider connection
with Access Manager.
Table 53–3 OAuth Service Provider Attributes for Access Manager
Name Value Notes
oam.OAM_VERSION OAM_11G
Either
OAM_11G
or
OAM_10G
, depending on
the Oracle Access Manager version in
use.
oam.Webgate_ID accessgate-oic
oam.ENCRYPTED_PASSWORD
oam.DEBUG_VALUE 0
oam.TRANSPORT_SECURITY OPEN
Specify the method for encrypting
messages between this AccessGate and
the Access Servers. The encryption
methods need to match. Valid values
include:
■
OPEN
■
SIMPLE
■
CERT
To update these settings, see
Section 49.9.1.1, "Configuring Mobile and
Social Services to Work With Access
Manager in Simple and Certificate
Mode."
oam.OAM_SERVER_1 localhost:5575
Specify the host name and port number
of the primary Oracle Access
Management server.
oam.OAM_SERVER_1_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_1. The default value is 4.
oam.OAM_SERVER_2 oam_server_2:5575
Specify the host name and port number
of the secondary Oracle Access
Management server.
oam.OAM_SERVER_2_MAX_CONN 4
Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_2. The default value is 4.
oam.AuthNURLForUID wl_
authen://sample_
ldap_no_pwd_
protected_res
Configuring OAuth Services Settings
53-20 Administrator's Guide for Oracle Access Management
53.3.5 Configuring Custom Resource Servers
See Section 52.4.5, "Understanding Resource Servers" for introductory information
about Resource Servers. The following section describes how to use the user interface
to configure a Resource Server. It includes the following topics:
■Creating a Custom Resource Server
■Editing or Deleting a Resource Server
■Understanding the Custom Resource Servers Configuration Page
OAuth Services provides two out-of-the-box services modeled as Resource Servers
and protected with an Access Token. For configuration information on the User Profile
Services and Consent Management Services Resource Servers, see Configuring User
Profile Services and Configuring Consent Management Services respectively.
53.3.5.1 Creating a Custom Resource Server
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it.
2. Select the Resource Servers tab.
3. To define a new resource server for use with OAuth Services, click the Create
button in the Custom Resource Servers section.
The Custom Resource Server Configuration page opens.
53.3.5.2 Editing or Deleting a Resource Server
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it for editing.
2. Click the Resource Servers tab.
3. To open a configured custom Resource Server for editing, click its name in the
Custom Resource Servers table.
The Custom Resource Server Configuration page opens.
oam.OAM_LOCAL_MODE true
Specifies if Mobile and Social should use
"local mode" or "remote mode" to
communicate with the OAM server. If the
attribute value is set to false, Mobile and
Social communicates with OAM over
TCP/IP. If set to true (or if this attribute
is undefined), Mobile and Social uses a
direct connection to communicate with
OAM.
Prior to version 11.1.2.3, Mobile and
Social only communicated with OAM
using TCP/IP (that is, remote mode).
Now communication defaults to local,
which is faster.
To configure Mobile and Social to
communicate with OAM 10g, set the
OAM_LOCAL_MODE
attribute to false.
Table 53–3 (Cont.) OAuth Service Provider Attributes for Access Manager
Name Value Notes
Configuring OAuth Services Settings
Configuring OAuth Services 53-21
53.3.5.3 Understanding the Custom Resource Servers Configuration Page
Identity Domain - The name of the identity domain to which this resource server
applies. (Read-only)
Name - The name of this resource server (or resource service).
Description - (Optional) A short description to help you or another administrator
identify this resource server in the future.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with clients and the resource owner. See
Section 52.5.1, "Understanding OAuth Services Access Tokens" for more information
about custom attributes.
Authorization & Consent Service Plug-in - From the menu, choose an authorization
plug-in for the resource server. This plug-in type defines security policy around
interactions where authorization and user consent are granted. It can influence claims
in a generated token as well. See Section 52.4.6, "Understanding Plug-Ins" for plug-in
descriptions.
Audience Claim - Identifies the audiences for which the OAuth token is intended.
Each principal intended to process the OAuth token must identify itself with a value in
Audience Claim.
Resource Server ID - The unique ID created for this resource server during
registration. (Once the resource server configuration is saved, this field cannot be
changed.)
Scopes
Click Add to add a new row to the scopes table. Click to select a row, then click Delete
to remove it.
Name - Type a scope definition. Use dot notation, for example:
photo.read
Description - Type a short note that describes the scope.
Require User Consent - Select to require the authorization server to display a user
consent form so that the user can approve (or deny) the access request.
Offline Scope - Allows client applications to request a refresh token that can be used
to obtain an access token even when the user is offline or not present. Client
applications use the refresh token to get a new access token to access resources. See
Section 52.5, "Understanding OAuth Services Tokens" for more information.
Token Settings
Override the default settings - Select this option if the token settings defined on the
resource server configuration page should override the default token settings defined
on the OAuth Services profile page.
Token Name - The name of the token.
Expires - The length of time in minutes after which the token is no longer valid.
Refresh Token Expires - The length of time in minutes after which the refresh token is
no longer valid.
Custom Attributes
Use this section to define custom attributes that OAuth Services embeds in the access
tokens. See Section 52.5.1, "Understanding OAuth Services Access Tokens" for more
information about custom attributes.
Configuring OAuth Services Settings
53-22 Administrator's Guide for Oracle Access Management
■Static Attributes - Attribute name and value pairs where the value is fixed at the
time that you define the attribute. For example,
name1=value1
.
■Dynamic Attributes - User-profile specific attributes.
53.3.6 Configuring User Profile Services
See Section 52.4.5.1, "Understanding User Profile Services" for introductory
information about the User Profile Services. The following section describes how to
use the console to configure an instance for the User Profile Services.
■Creating a New User Profile Service
■Editing the User Profile Service
■Understanding the User Profile Services Configuration Page
53.3.6.1 Creating a New User Profile Service
1. Open the Identity Domains page as described in Section 53.2, "Configuring OAuth
Services Components in an Identity Domain" and click the identity domain to
open it.
2. Click the Resource Servers tab.
3. Click the Create button in the User Profile Services section.
The User Profile Services Configuration page opens.
53.3.6.2 Editing the User Profile Service
1. Open the Identity Domains page as described in Section 53.2, "Configuring OAuth
Services Components in an Identity Domain" and click the identity domain to
open it for editing.
2. Click the Resource Servers tab.
3. In the User Profile Services section, click the service name to edit it.
The User Profile Services Configuration page opens.
53.3.6.3 Understanding the User Profile Services Configuration Page
Use this page to configure the User Profile Service. This service supports OAuth 2.0
authorization and allows clients to interact with a back-end directory server and
perform User Profile REST operations on Person, Group, and Relationship entities.
Identity Domain - The name of the identity domain to which this service profile
applies. (Read-only)
Name - The name of this service profile.
Description - (Optional) A short description to help you or another administrator
identify this service profile in the future.
Service Enabled - Select to enable the service, or clear the option box to disable it.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with clients. If enabled, the user consent form
notifies the user that user-profile-specific details will be shared with the client. See
Section 52.5.1, "Understanding OAuth Services Access Tokens" for more information
about custom attributes.
Configuring OAuth Services Settings
Configuring OAuth Services 53-23
Audience Claim - Identifies the audiences that the OAuth token is intended for. Each
principal intended to process the OAuth token must identify itself with a value in
audience claim.
Resource Server ID - The unique ID that OAuth Services created for this User Profile
resource server. (Read-only)
Service Endpoint - The URI where the service receives and responds to create, read,
update, and delete user profile service requests. Create a unique uniform resource
identifier (URI) address for this service; for example,
localhost:5575
Authorization & Consent Service Plug-in - From the menu, choose an authorization
plug-in for the service. This plug-in type defines security policy around interactions
where authorization and user consent are granted. It can influence claims in a
generated token as well. See Section 52.4.6, "Understanding Plug-Ins" for plug-in
descriptions.
Protected by OAuth Service Profile - From the menu, choose the OAuth service
profile that protects the user profile service.
Identity Store Name - The name of the identity store that contains the user records.
Scopes
Security Protection
Configure individual permission settings for person, relationship, and group entities.
Click Add to add a record to the table; select a row and click Delete to remove the
record. The service uses the following default entity names:
URI - The URI segment for which the scope is defined.
■/me - Designates operations that apply to the user logged in to the client
■/users - Designates operations that apply to other users
■/groups - Designates operations that apply to groups
■/secretkey - Designates operations that apply to secret key management
Service Enabled - Select to enable the service for this scope.
Allow Read - Select to allow read operations for this scope.
Allow Write - Select to allow write operations for this scope.
Unprotected - Select this option if you do not want to limit access, or clear this option
to limit access by scope.
OAuth Scope - Type a scope definition. Use dot notation, for example:
UserProfile.me.write
Description - Type a short note that describes the scope.
Require User Consent - Select to require the authorization server to display a user
consent form so that the user can approve (or deny) the access request.
Identity Attributes of the Selected Scope - Click an entity row in the Security
Protection table to view the Attribute table for that entity. Click Add to add a record to
the table; select a row and click Delete to remove the record.
Offline Scope - Allows client applications to request a refresh token that can be used
to obtain an access token even when the user is offline or not present. Client
applications use the refresh token to get a new access token to access resources. See
Section 52.5, "Understanding OAuth Services Tokens" for more information.
Configuring OAuth Services Settings
53-24 Administrator's Guide for Oracle Access Management
Token Settings
Override the default settings - Select this option if the token settings defined on the
resource server configuration page should override the default token settings defined
on the OAuth Services profile page.
Token Name - The name of the token.
Expires - The length of time in minutes after which the token is no longer valid.
Refresh Token Expires - The length of time in minutes after which the refresh token is
no longer valid.
Proxy Authentication
Select Proxy Authentication to allow the identity of a user using a web application
(also known as a "proxy") to be passed through the application to the database server.
Oracle Unified Directory (OUD) and Active Directory (AD) support proxy
authentication. The Access Control option is simply to provide Proxy Authentication
support for directory servers that do not have it built in. See Section 52.4.5.1.1, "Using
Proxy Authentication" for more details.
Attributes
Use this section to define user-profile specific (dynamic) attributes.
Resource URIs
Use this section to enable or disable the /me, /users, /groups, /secretkey services, and
define the service endpoint URIs and provider implementation class paths for these
services.
Service Endpoint - The URI where the service receives and responds to service
requests. Create a unique uniform resource identifier (URI) address for this service; for
example,
localhost:5575
Entities
Use the fields in this section to configure entity relationships.
■Name - The name of the defined entity relationship.
■Identity Directory Service Relation - Choose the directory service relationship
that is to be accessed by the relationship End Point segment.
■End Point - Type an entity relationship URI segment that will be used to access a
corresponding data column in the Identity Directory service. For example, if
memberOf
is the End Point URI, then:
http://<host>:<port>/.../idX/memberOf
would be the URI to access related entities of an entity with ID
idX
.
■Source Entity URI - The URI (or URL) of the source entity.
■Destination Entity URI - The URI (or URL) of the destination entity.
Table 53–4 User Profile Service Attributes
Name Value
accessControl false
adminGroup cn=Administrators,ou=groups,ou=myrealm,dc=base_domain
selfEdit true
Configuring OAuth Services Settings
Configuring OAuth Services 53-25
■Scope for Requesting Recursion - Use Scope attribute values with the scope
query parameter to retrieve a nested level of attributes in a relationship search. To
access related entities recursively, type the value to be used. The default
configuration uses two scope attribute values:
toTop
and
all
. If the Scope for
Requesting Recursion value is the attribute value
all
, then the following REST
URI example is used to make the request:
http://host:port/.../idX/reports?scope=all
In this example, the URI returns the entities related to the entity with ID
idX
, as
well as all further related entities.
Attributes
Use this section to define user-profile entity specific (dynamic) attributes.
53.3.7 Configuring Consent Management Services
See Section 52.4.5.2, "Understanding Consent Management Services" for introductory
information about the Consent Management Services. The following section describes
how to use the user interface to configure the Consent Management Services.
■Creating a New Consent Management Service
■Editing an Existing Consent Management Service
■Understanding the Consent Management Services Configuration
53.3.7.1 Creating a New Consent Management Service
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it.
2. Click the Resource Servers tab.
3. Click the Create button in the Consent Management Services section.
The Consent Management Service Configuration page opens.
53.3.7.2 Editing an Existing Consent Management Service
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it for editing.
2. Click the Resource Servers tab.
3. In the Consent Management Services section, click the service name to edit it.
The Consent Management Service Configuration page opens.
53.3.7.3 Understanding the Consent Management Services Configuration
The Consent Management Services handle consent storage, retrieval, revocation, and
consent validation operations.
Identity Domain - The name of the identity domain to which this consent
management service applies. (Read-only)
Name - The name of this consent management service.
Description - (Optional) A short description to help you or another administrator
identify this service in the future.
Configuring OAuth Services Settings
53-26 Administrator's Guide for Oracle Access Management
Service Enabled - Select to enable the service, or clear the option box to disable it.
Allow Token Attributes Retrieval - Select this option to allow custom attributes (both
attribute names and values) to be shared with clients, resource servers, and the
resource owner.
Audience Claim - Identifies the audiences that the OAuth token is intended for. Each
principal intended to process the OAuth token must identify itself with a value in
audience claim.
Resource Server ID- The unique ID that the authorization server created for this
resource server during registration. (Read-only)
Service Endpoint - The URL where the Consent Management Service receives and
responds to client and resource owner service requests.
Authorization & Consent Service Plug-in - From the menu, choose an authorization
plug-in for the service. This plug-in type defines security policy around interactions
where authorization and user consent are granted. It can influence claims in a
generated token as well. See Section 52.4.6, "Understanding Plug-Ins" for plug-in
descriptions.
Protected by OAuth Service Profile - From the menu, choose the OAuth service
profile that protects the consent management service.
Scopes
Security Protection
Configure individual permission settings. Click Add to add a record to the table; select
a row and click Delete to remove the record. The service uses the following default
entity names:
URI - The URI segment for which the scope is defined.
■/retrieve
■/grant
■/revoke
Allow Read - Select to allow read operations for this scope.
Allow Write - Select to allow write operations for this scope.
Unprotected - Select this option if you do not want to limit access, or clear this option
to limit access by scope.
OAuth Scope - Type a scope definition. Use dot notation, for example:
UserProfile.me.write
Description - Type a short note that describes the scope.
Require User Consent - Select to require the authorization server to display a user
consent form so that the user can approve (or deny) the access request.
Offline Scope - Allows client applications to request a refresh token that can be used
to obtain an access token even when the user is offline or not present. Client
applications use the refresh token to get a new access token to access resources. See
Section 52.5, "Understanding OAuth Services Tokens" for more information.
Token Settings
Override the default settings - Select this option if the token settings defined on the
resource server configuration page should override the default token settings defined
on the OAuth service profile page.
Configuring OAuth Services Settings
Configuring OAuth Services 53-27
Token Name - The name of the token.
Expires - The length of time in minutes after which the token is no longer valid.
Refresh Token Expires - The length of time in minutes after which the refresh token is
no longer valid.
Attributes
Use this section to define custom attributes
Resources URIs
Use this section to enable or disable the retrieve, grant, and revoke services. You can
also define the service endpoint URIs and provider implementation class paths for
these services.
Service Endpoint - The URI where the service receives and responds to requests.
Create a unique URI address for this service.
Service Enabled - Select to enable the service, or clear the option box to disable it.
Attributes
Use this section to define consent management entity-specific (dynamic) attributes.
53.3.8 Configuring Plug-Ins
Use this page to configure security plug-ins. See Section 52.4.6, "Understanding
Plug-Ins" for plug-in descriptions.
53.3.8.1 Creating a new Plug-in
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it.
2. Click the Plug-ins tab.
3. Click the Create button in one of the plug-in category sections.
The Plug-in Configuration page opens.
53.3.8.2 Understanding the Plug-in Configuration Page
Use this page to add a plug-in to an Identity Domain or edit an existing plug-in
configuration. Only some of the fields listed below will apply to the plug-in you are
configuring.
Identity Domain - The name of the identity domain where the plug-in is located.
Name - The name of the plug-in.
Description - (Optional) A short description to help you or another administrator
identify this plug-in in the future.
Implementation Class - Choose the class from the menu that implements the plug-in
interface. Applies to the Mobile Client Plug-in Configuration page, the Mobile
Resource Server Plug-in Configuration page, and the Mobile Authorization & Consent
Service Plug-in Configuration page. See the Oracle Fusion Middleware Developer's Guide
for Oracle Access Management for details.
Configuring OAuth Services Settings
53-28 Administrator's Guide for Oracle Access Management
Interface Class - Lists the interface class for this plug-in. Applies to the Mobile Client
Plug-in Configuration page, the Mobile Resource Server Plug-in Configuration page,
and the Mobile Authorization & Consent Service Plug-in Configuration page.
Security Handler Class - Choose the Java class that defines the Security Handler
Plug-in. Applies to the Mobile Adaptive Access Plug-in Configuration page and the
Mobile Custom Token Attributes Plug-in Configuration page.
Mobile Security Manager Plug-in Class - Choose the Java class that defines the
Mobile Security Manager Plug-in. Applies to the Mobile Security Manager Plug-in
Configuration page only.
MSM Device Inventory Attributes Precedence - When enabled, if both the Mobile
Security Manager (MSM) component and the Mobile OAuth server supply a value for
the same device attribute, the value supplied by the Mobile Security Manager is used.
If the attribute value from the MSM component is not available, the value from the
Mobile OAuth server is used instead.
MSM Attributes - Lists the attributes that the Mobile Security Manager plug-in
harvests from mobile devices. The first column lists the mobile device attributes that
the Mobile Security Manager component collects. The second column lists the mobile
device attributes that the Mobile OAuth server collects during mobile app requests. If
the same device attribute is available from both the MSM component and the server,
both are listed in the same row. (For example, the MSM attribute "imei" appears in
column one, and the matching server attribute "oracle:idm:claims:client:imei" appears
in column two of the same row.) For a list of the device attributes that the Mobile
OAuth server collects during app requests, open the OAuth Mobile Client
Configuration page and locate the Device Claim Attributes list in the Configuration
Settings section. To add additional attributes, click Add to add a row at the bottom of
the table, and enter the attribute name. (Enter attributes sourced from Mobile Security
Manager in the first column, and attributes from the Mobile OAuth server in the
second column. Enter attributes one per row unless the attributes are equivalent and
should be mapped to one another.)
Attributes - Use this section to define custom plug-in attributes.
53.3.9 Configuring Server Settings
Use the Server Settings Configuration page to configure general server settings for the
identity domain named.
Identity Domain - The name of the identity domain to which the settings on this
configuration page apply. (Read-only)
HTTP Proxy Settings
Configure the following settings if a proxy server is in place between the OAuth Token
Service (the Push Service) and the Apple Push Notification Service (APNS) or Google
Cloud Messaging (GCM) service.
Proxy URL - Choose the protocol to use to connect to the proxy server (HTTP or
HTTPS), then type the proxy server host name and port number.
Proxy Authentication - Type the user name and password required to authenticate
with the proxy server.
Note: See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a WebGate.
Configuring OAuth Services Settings
Configuring OAuth Services 53-29
Apple Push Notification
Configure the default values that should be used for this identity domain. Use the
OAuth Mobile Client Configuration page to customize these settings on an app by app
basis.
Minimum Connection Pool Size - Specifies the minimum number of connections in
the connection pool.
Maximum Connection Pool Size - Specifies the maximum number of connections in
the connection pool.
Keep Alive - The Apple Push Notification keep alive value in seconds.
Token Life Cycle Management
Maximum Search Results - Specify the maximum number of token entry search
results that should be returned on the Token Life Cycle Management page.
Attributes
Attributes - Use this section to define custom attributes.
53.3.10 Configuring the Jailbreak Detection Policy
See Section 52.4.8, "Understanding Jailbreak Detection Policy" for introductory
information about the jail breaking detection policy. The following section describes
how to use the user interface to configure the policy.
Jailbreak Detection - Select Enabled to turn the Jailbreaking Detection Policy on, or
clear this option to turn it off for all client application instances. If you enable the
Jailbreaking Detection Policy here, you can disable it on an application by application
basis. If you disable the Policy here, you cannot enable or disable the feature on an
application by application basis.
Policy Statements
Use the buttons in the menu to add, delete, and re-order policy statements.
Order - The sequential row number assigned to each row in the table.
Enabled - Select this option to activate the policy statement condition.
Minimum OS Version - The minimum iOS version to which the policy applies. If the
value is 1.0, the policy will apply to iOS devices running at least version 1.0 of iOS.
Maximum OS Version - The maximum iOS version to which the policy applies. If the
value is empty, a maximum iOS version number is not checked so the policy applies to
Table 53–5 OAuth Server Settings Attributes
Name Value Notes
wgAuthnUserHeader
OAM_REMOTE_USER
This attribute usage is optional. If an
OAM Webgate is front
ending/proxying requests to an
OAuth server, set this attribute. The
OAM Webgate sets the
OAM_REMOTE_
USER
header to identify the
authenticated user. If a deployment
uses another header name instead of
OAM_REMOTE_USER
, then this attribute
needs to be set with that header
name.
Configuring OAuth Services Settings
53-30 Administrator's Guide for Oracle Access Management
any iOS version higher than the value specified for Min OS Version. Once set you
cannot remove the value and leave this field empty.
Minimum Client SDK Version - The minimum Mobile and Social Client SDK version
number. For example, 11.1.2.0.0.
Maximum Client SDK Version - The maximum Mobile and Social Client SDK version
number. For example, 11.1.2.3.0.
Details - Additional details about the Jailbreak Detection Policy policy statement.
Hover the mouse over the info icon to view the details in a pop-up.
Policy Statement Conditions
Click to select a row in the table to view or edit its values in this section. See the
previous section (Policy Statements) for field descriptions.
Policy Statement Detection Logic
Policy Expiration Duration - Type the length of time in seconds that the SDK on the
mobile client device should wait before expiring the local copy of the policy and
retrieving a newer version.
Auto Check Period - Type the interval of time in minutes that the client device should
wait before executing the Jailbreaking Detection Policy statements again.
Detection Location - The iOS client device uses a logical-OR operator to evaluate
Policy statements. Add a Detection Location as follows:
■File Path - Type the absolute path to the file or directory on the device for which
the Detection Policy should search.
■Action - Select Exists which instructs the Detection Policy to evaluate whether it
can access a file path.
■Success - Select if the Policy should flag the device as jail broken if the specified
files or directories are found on the device. Use this option if the policy is checking
for unauthorized files or directories. Clear this option if the Policy should flag the
device as jail broken if the specified files or directories are not found. (Use this
option if checking for required files or directories.)
53.3.11 Configuring Token Life Cycle Management
Use this screen to search for and revoke tokens that have been issued. You can search
for tokens using criteria such as user ID, client ID/name, client IP address, service
profile, assertion token category, and token creation/expiration time. Enter your
criteria and click Search. The maximum number of token entry search results returned
is determined by the Maximum Search Results setting on the OAuth Server Settings
page.
Search Criteria
Identity Domain - The name of the identity domain that you are searching for tokens.
(Read only)
User - Specify an LDAP UID (
john.smith
) or an LDAP Fully Qualified DN
(
cn=jane.smith,dc=example,dc=com
) to search by.
Client - Specify a client ID to search for tokens by.
Client IP Address - Specify a client IP address (for example,
192.168.100.1
) to search
for tokens by
Configuring OAuth Services for Third-Party JWT Bearer Assertions
Configuring OAuth Services 53-31
Service Profile - Choose a profile from the menu, or leave this selection empty.
Assertion Token Category - Choose a category from the menu, or leave this selection
empty.
Token Issued - Search for tokens by the date and time that they were issued.
Token Expiring at - Search for tokens by the date and time that they expire.
Mobile Device Claim Attributes
IMEI - Specify the unique 15-digit IMEI (International Mobile Equipment Identity)
code to search by. The IMEI can be displayed on most mobile handsets by dialing
*#06#.
MAC Address - Specify the unique MAC (Media Access Control) address to search by.
Phone Number - Specify a phone number to search by.
53.4 Configuring OAuth Services for Third-Party JWT Bearer Assertions
OAuth Services accepts third-party (non-Oracle) JWT assertions. You must, however,
configure a trust relationship by adding the third-party’s certificate into the OAuth
Services Service Profile keystore. OAuth Services uses the keystore to verify the JWT
assertion’s digital signature. Create a separate keystore for each Service Profile that
needs its own signing certificate. This section covers the following topics:
■Understanding the Default Service Profile Keystore
■Creating a Non-Default Keystore for a Service Profile
■Configuring a Third-Party JWT Trust Issuer
53.4.1 Understanding the Default Service Profile Keystore
The role of the Service Profile is described in Section 52.4.2, "Understanding Service
Profiles" The default Service Profile (OAuthServiceProfile) created in the
DefaultDomain uses the Java Keystore (JKS) included with Oracle Access
Management. It consists of the following files.
You can use the following Java
keytool
command to list all of the private key and
certificate information in the default keystore (
default-keystore.jks
).
keytool -list -keystore default-keystore.jks
Table 53–6 Default OAuth JKS Keystore File and Settings File
File Path
JKS keystore file
$DOMAIN_HOME/config/fmwconfig/default-keystore.jks
Keystore settings file
$DOMAIN_HOME/config/fmwconfig/jps-config.xml
Note: Oracle Web Services Manager also uses the
default-keystore.jks
service. For details see Section 44.2.2, "About
the Oracle Web Services Manager Keystore (default-keystore.jks)."
Configuring OAuth Services for Third-Party JWT Bearer Assertions
53-32 Administrator's Guide for Oracle Access Management
Use the following procedure to find the keystore credential with Oracle Enterprise
Manager Fusion Middleware Control Console.
1. Login to the Oracle Enterprise Manager Fusion Middleware Control Console.
http://host_name.domain_name:port_number/em
2. Navigate through WebLogic Domain --> <domain name>.
<domain name> is the name of the domain in which the information is stored.
3. Click on the WeblogicDomain found in the right corner.
4. Select System MBean Browser ---> com.oracle.jps ---> Server:oam_server1 ---> JPS
Credential Store.
5. Navigate through JPS Credential Store Mbean --> Operations -->
getPortableCredentialMap.
6. Enter the p1 parameter as oracle.wsm.security.
7. Click Invoke.
8. Expand Data Element2.
The password value is displayed.
53.4.2 Creating a Non-Default Keystore for a Service Profile
The steps in this section describe how to:
■Create a separate keystore to store the third-party’s certificates
■Import the certificates into the keystore
■Configure the keystore
■Create a CSF Entry for the keystore service instance
■Add the keystore service to the appropriate Service Profile
Create the Keystore
Create a new Java Keystore (JKS) using the
keytool
utility that is distributed with the
Java JDK.
1. Go to
$JDK_HOME/jdk/bin
and open a prompt.
2. Using
keytool
, generate a key pair:
keytool -genkeypair -keyalg RSA -dname
dname
-alias aliasname
-keypass
key_password
-keystore
keystore
-storepass
keystore_password
-validity
days_valid
Where:
Note: When a new key is added to the OAM keystore, the OAM
server needs to be restarted since keystore changes are not
automatically refreshed.
Note: Any changes made during this procedure require a restart of
the OAM server.
Configuring OAuth Services for Third-Party JWT Bearer Assertions
Configuring OAuth Services 53-33
■
dname
is the X.500 Distinguished Name to be associated with
alias
, and is
used as the issuer and subject fields in the self-signed certificate. This can be
any string as long as it's in the correct format (for example,
cn=spaces,dc=example,dc=com
).
■
aliasname
is a short name that identifies the new keystore entry
■
key_password
is the password for the new public key
■
keystore
is the keystore name, (for example,
oauth-xyz-keystore.jks
)
■
keystore_password
is the keystore password
■
days_valid
is the number of days for which the certificate should be
considered valid (for example, 1064).
Example 53–1 Creating the Keystore
keytool -genkeypair -keyalg RSA -dname "cn=spaces,dc=example,dc=com"
-alias oauthkey -keypass password123 -keystore oauth-xyz-keystore.jks
-storepass passwordxyz -validity 1064
Load the Certificates Into the Keystore
Use the
keytool
utility to import the certificates into the keystore.
1. Using
keytool
, type the following command:
keytool -importcert -alias
aliasname
-file
certfile
-keystore
keystore
-storepass
keystore_passwor
d
Where:
■
aliasname
is a short name that identifies the keystore
■
certfile
is the file containing the certificates to load
■
keystore
is the keystore name, (for example,
oauth-xyz-keystore.jks
)
■
keystore_password
is the keystore password
Example 53–2 Loading the Certificates
keytool -importcert -alias oauthkey_123 -file samplekey.cer -keystore
oauth-xyz-keystore.jks -storepass passwordxyz
Add the Keystore Instance to jps-config.xml
Configure the keystore service and update the credential store so that OAM can read
the keystore and keys correctly. In the
jps-config.xml
keystore settings file, add the
following new keystore service instance in the
<serviceInstances>
element.
1. In a text editor, open the keystore settings file:
$DOMAIN_HOME/config/fmwconfig/jps-config.xml
2. Find the
<serviceInstances>
node for the keystore.provider
Provider
, and add
the following:
<serviceInstance name="<service-instance-name>" provider="keystore.provider"
location="<keystore-location>">
<property name="keystore.provider.type" value="db"/>
<property name="keystore.sig.csf.key" value="sign-csf-key"/>
<property name="keystore.enc.csf.key" value="enc-csf-key"/>
Configuring OAuth Services for Third-Party JWT Bearer Assertions
53-34 Administrator's Guide for Oracle Access Management
<property name="keystore.csf.map" value="oracle.oauth.security"/>
<property name="keystore.pass.csf.key" value="keystore-csf-key"/>
<property name="keystore.type" value="JKS"/>
<propertySetRef ref="props.db.1"/>
</serviceInstance>
Where:
■
service-instance-name
= Any
service-instance-name
■
keystore-location
= Path to the keystore file
Example 53–3 Update jps-config.xml
<serviceInstance name="oauth-xyz-keystore.db" provider="keystore.provider"
location="./oauth-xyz-keystore.jks">
<property name="keystore.provider.type" value="db"/>
<property name="keystore.sig.csf.key" value="sign-csf-key"/>
<property name="keystore.enc.csf.key" value="enc-csf-key"/>
<property name="keystore.csf.map" value="oracle.oauth.security"/>
<property name="keystore.pass.csf.key" value="keystore-csf-key"/>
<property name="keystore.type" value="JKS"/>
<propertySetRef ref="props.db.1"/>
</serviceInstance>
3. Find the
<jpsContexts>
node and add the new service instance into the default
context section. (Do not remove any pre-existing service instances.) The following
example shows the addition of a
<serviceInstanceRef>
element with a
ref
to the
oauth-xyz-keystore.db
service instance (defined in the previous step).
Example 53–4 Adding the new Service Instance
<jpsContexts default="default">
<jpsContext name="default">
<serviceInstanceRef ref="oauth-xyz-keystore.db"/>
... other serviceInstanceRef elements ...
</jpsContext>
Create a CSF Entry for the Keystore Service Instance
Use the following WLST commands to create the necessary Credential Store
Framework (CSF) entries. Restart the server when you are done.
createCred(map="oracle.wsm.security", key="sign_csf_key", user="alias_
name", password=keystore_password, desc="Description of the signing key
credential")
createCred(map="oracle.wsm.security", key="enc_csf_key", user="alias_
name", password=keystore_password, desc="Description of the encryption key
credential")
createCred(map="oracle.wsm.security", key="keystore_csf_key",
user="oauth", password=keystore_password
,
desc="Description of the keystore
credential")
Where:
■
sign_csf_key
= the password for the signing key
■
alias_name
= the alias name for the key
■
keystore_password
= the keystore password
Configuring OAuth Services for Third-Party JWT Bearer Assertions
Configuring OAuth Services 53-35
■
enc_csf_key
= the password for the encryption key
■
keystore_csf_key
= the password for the keystore
Example 53–5 Creating Credential Store Entries
createCred(map="oracle.wsm.security", key="oauth-sign-csf-key",
user="ms-oauth-key", password=passwordxyz, desc="Signing key credential")
createCred(map="oracle.wsm.security", key="oauth-enc-csf-key",
user="ms-oauth-key", password=passwordxyz, desc="Encryption key credential")
createCred(map="oracle.wsm.security", key="keystore_csf_key", user="oauth",
password=passwordxyz, desc="Keystore credential")
Add the Provider Service Name to the Service Profile
Apply the updated configuration to the Service Profile. See Section 53.3.2.1, "Creating a
Service Profile" if you have not yet created an OAuth Service Profile for the third-party
service.
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it for editing.
2. Click the Service Profiles tab.
3. Click the Service Profile name in the table.
4. Expand the Attributes section.
5. Add the keystore service information you configured in Example 53–4, "Adding
the new Service Instance" to the Attributes table using the
keystore.service
name. Refer to the following screen capture.
Configuring OAuth Services for Third-Party JWT Bearer Assertions
53-36 Administrator's Guide for Oracle Access Management
53.4.3 Configuring a Third-Party JWT Trust Issuer
This section describes how to configure OAuth Services to support specific JSON Web
Token (JWT) issuers. All Trusted Issuers must be defined so the OAM Server can
validate the token, the thumbprint (x5t) and the key identifier based on this
configuration. If there is a trusted entry already available with the same claim, header
values and alias name, that entry will be used.
1. Access the Identity Domains page as described in Section 53.2, "Configuring
OAuth Services Components in an Identity Domain" and click the identity domain
to open it for editing.
2. Click the Service Profiles tab.
3. Click the Service Profile name in the table.
In this example, OAuthServiceProfile.
4. Expand the Configuration Settings section and click the Trusted Issuers tab.
5. Configure the following and click Apply.
■The certificate alias
■The URL of the Trusted Issuer
■The key identifier (KID) of the certificate alias.
■The X.509 Certificate Thumbprint
Configuring a WebGate to Protect OAuth Services
Configuring OAuth Services 53-37
Figure 53–4 is a screenshot of the OAuth Services Service Profile Configuration Page
where Trusted Issuers are defined under the Configuration Settings heading. Three
Trusted Issuers are configured in it and the following is true of these configurations.
■If a request comes with an assertion in which the Trusted Issuer is
"www.example1.com", the kid header is "mykey" and there is no x5t header, the
runtime uses the certificate with the "trustpartner1" alias name.
■If a request comes with an assertion in which the Trusted Issuer is
"www.example2.com", the value of the x5t header is
"s7RzuzdlJrDyvMS9ntyvMS9ntZt" and there is no kid header, the runtime uses the
certificate with the "trustpartner2" alias name.
■If a request comes with an assertion in which the Trusted Issuer is
"www.example.corp.com", the value of the kid header is "corpkey" and the value
of the x5t header is "cYJ4pHYJrDYvMS9ntZts7Rzuzdl", the runtime uses the
certificate with the "trustpartner3" alias name.
Figure 53–4 OAuth Services Service Profile Configuration Page
53.5 Configuring a WebGate to Protect OAuth Services
This section describes how to configure a WebGate for use with OAuth Services. The
WebGate protects the OAuth Services consent page and serves as a proxy so that client
authorization and token endpoint requests access the WebGate rather than the Oracle
Access Management server directly. WebGates cannot be used to protect OAuth
Services Resource Servers. These steps are for WebLogic environments only.
1. Install the Oracle HTTP Server 11g Webgate for OAM using the instructions in
Installing Webgates for Oracle Access Manager.
Note: A WebGate proxy is required to use the 3-legged authorization
scenario with an external LDAP directory server.
Configuring a WebGate to Protect OAuth Services
53-38 Administrator's Guide for Oracle Access Management
2. Configure the WebGate by defining the following resource and creating an
authentication policy and authorization policy.
a. In the Oracle Access Management console, click Application Security at the
top of the window.
b. Under Access Manager, click Application Domains, then click Search to view
the Application Domains on the Search Application Domains page.
c. Click the target domain to open it for editing.
d. Select the Resources tab.
e. Create the following resource. If you are using the existing IAMSuiteAgent
Host Identifier, the resource is already present and can be searched on using
the Resource URL field.
/ms_oauth/oauth2/ui/**
Click to select the resource, then click the Edit button.
f. Under the Protection heading, choose the following options from the menus
and click Apply:
Protection Level - Protected
Authentication Policy - Protected HigherLevel Policy
Authorization Policy - Protected Resource Policy
These settings allow the Webgate to perform user authentication and user
authorization.
g. Add the following resources and set the Protection Level to Excluded:
/ms_oauth/oauth2/endpoints/**
/ms_oauth/oauth2/oammsui/**
/ms_oauth/style/**
/ms_oauth/img/**
/oam/**
The Webgate does not protect Excluded resources and allows them to be
accessed.
3. Add the following lines to the
mod_wl_ohs.conf
file and restart the Webgate. For
WebLogicPort
, be sure to add the managed port details for your environment.
# the following directive proxies all the OAuth requests
<IfModule weblogic_module>
WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /ms_oauth/*
</IfModule>
# the following directive proxies all the OAM managed server requests.
<IfModule weblogic_module>
WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /oam/*
</IfModule>
Configuring OAM Session Synchronization
Configuring OAuth Services 53-39
4. Update the Access Manager Load Balancing settings as follows:
a. In the Oracle Access Management console, click Configuration at the top of
the window.
b. Select Access Manager from the View menu in the Settings section.
c. In the Load Balancing section, change the OAM Server Host and the OAM
Server Port settings to the Webgate's host and port settings.
d. Click Apply.
53.6 Configuring OAM Session Synchronization
The OAM User session synchronization feature prevents multiple OAM sessions from
being created by a mobile user. The initial OAM session is created during the 3-legged
Mobile scenario when the authorization code is created (provided that the OAuth
consent UI pages are protected by OAM). This session is stored in the device keystore
and used for subsequent OAM token requests for as long as the session is valid.
A one-time Authorization Policy change in Oracle Access Management is required for
OAM session synchronization to work. The following steps configure OAM to send
Session ID values to OAuth Services. Once configured, OAM session synchronization
will always be used for mobile authorization requests when using OAM protection (as
opposed to Mobile and Social protection) for the authorization endpoint.
1. In the Oracle Access Management console, click Application Security at the top of
the window.
2. Under Access Manager, click Application Domains.
3. Under Search Application Domains, enter the name of the target WebGate
domain (or enter a partial name and wild card, *, or leave the field blank to
retrieve all domains). For example:
DesiredDomain
4. Click Search.
5. In the Search Results section, highlight the WebGate domain and click Edit.
6. Click the Authorization Policies tab.
7. In the policies table, click Protected Resource Policy to open it for editing.
8. Click the Responses tab.
9. Click Add.
10. Enter the following values in the Add Response dialog:
■Type - choose Header from the menu.
■Name - Enter any name, for example: mysession.
■Val u e - Enter:
${session.id}
Click Add.
Note: OAM Session Synchronization requires a WebGate protecting
the OAuth Services consent UI pages. See Section 53.5, "Configuring a
WebGate to Protect OAuth Services" for details.
Configuring Mobile OAuth for SSO Servlet Authentication
53-40 Administrator's Guide for Oracle Access Management
11. Click Apply.
53.7 Configuring Mobile OAuth for SSO Servlet Authentication
The Mobile OAuth SSO Servlet makes it possible to use a device-native app as a single
sign-on proxy app when a user signs on to an app running in a mobile browser
(external or embedded) in a 2-legged flow. In this arrangement, the native app
implements the login page and uses Mobile and Social Services to authenticate with
Oracle Access Management.
You can configure this authentication scheme to try multiple native apps on the device.
If the first app does not respond within a half second (500ms) the servlet redirects the
browser to the next app in the order that the apps are listed. If the servlet gets to the
end of the list and there is not an application installed with the specified client ID, the
servlet re-directs the user to the OAM login page. Similarly, if the request is received
from a desktop browser, the request is forwarded to the OAM login page. Following is
a description of the Mobile SSO Servlet authentication flow:
1. The user opens a URL in a mobile browser.
2. The web server hosting the application redirects the browser to OAM.
3. Access Manager redirects the browser to the native app on the device.
4. The browser launches the native app in response to the redirect.
5. The native app displays the user login page.
6. The user enters a user name and password.
7. The native app does a 2-legged device registration flow. It collects user credentials,
does device registration, and gets the client token. If server-side single sign-on is
enabled, the user token is stored on the server and is not returned to the client. If
server-side single sign-on is turned off, the user token is returned to the client.
8. The native app exchanges the client token and user token for the OAM master
token (OAM_ID). (If server-side single sign-on is enabled, the user token is
exchanged from the server-side keystore.)
9. The native app directs the browser to the Oracle Access Management Mobile and
Social server, which injects the OAM master token as a cookie.
10. The native app sends the mobile browser a URL redirect and OAM master token
as a cookie.
11. The mobile browser opens the original URL now that the access request includes
an OAM master token.
12. The web server sends the requested pages to the mobile browser.
The following sections contain the configuration steps.
■Configuring OAM and Your App to use the Mobile SSO Servlet
■Configuring the MobileSSOServlet Authentication Scheme
For information about Mobile OAuth SSO options, see Section 52.8, "Understanding
Mobile OAuth Services Server-Side Single Sign-on."
53.7.1 Configuring OAM and Your App to use the Mobile SSO Servlet
To use the Mobile OAuth Services single sign-on authentication scheme, complete the
following configuration tasks:
Configuring Mobile OAuth for SSO Servlet Authentication
Configuring OAuth Services 53-41
■In the Oracle Access Management console, protect the Web resource(s) with an
OAM WebGate. To learn how, see Chapter 15, "Registering and Managing OAM
11g Agents."
■In Access Manager, create a custom MobileSSOServlet authentication scheme on
the OAM server and configure it with a list of mobile application IDs. Then
configure the authentication scheme in OAM to protect the Web resource(s). To
learn how, see Section 53.7.2, "Configuring the MobileSSOServlet Authentication
Scheme."
■If necessary, register the native mobile app client with Mobile OAuth Services. To
register the native mobile app client with OAuth Services see Section 53.3.3,
"Configuring Clients."
■In Mobile OAuth Services, assign the Resource Owner grant type to the native
mobile app(s) that will be configured to serve as single sign-on proxies. This grant
type is required to be able to perform the 2-legged client registration.
To assign the client the Resource Owner grant type, use the OAuth Services
Mobile Clients configuration page. For more information, see Section 53.3.3.5,
"Understanding the Mobile Clients Configuration Page."
■To code the device-native app to authenticate with OAM using Mobile and Social
Services, refer to the following sections in the Oracle Fusion Middleware Developer's
Guide for Oracle Access Management:
–For iOS, see "Invoking Authentication Services With the iOS Client SDK."
–For Android, see "Invoking Authentication Services With the Android Client
SDK."
–For the REST API, see "Mobile and Social Services REST Reference:
Authentication and Authorization."
When coding the app(s), implement the
/authenticate
endpoint, which is
required to use this feature. This endpoint provides client registration, OAM token
exchange, and URL redirection to the MobileSSOServlet. The
/authenticate
endpoint should accept a resource URL (
resource_url
) and Return URL
(
http://<OAM-HOST>:<OAM-PORT>/ms_oauth/mobilesso
) as parameters.
Once the app completes registration and the OAM token exchange, it returns
control of the authentication process (along with the OAM_ID and resource_url)
using the value of the return_url that was sent to
/authenticate
endpoint.
Redirect the app back to the MobileSSOServlet using this URL:
/mobilesso?OAM_ID=1234&resource_url=http://<OAM-host>:7777/index.html
where:
–
OAM_ID
= the OAM master token value
–
resource_url
= URL of the resource
In this case, the redirect URL used to redirect the app back to the
MobileSSOServlet will be
http://<OAM-HOST>:<OAM-PORT>/ms_
oauth/mobilesso?OAM_ID=1234&resource_
url=http://<OAM-host>:7777/index.html
53.7.2 Configuring the MobileSSOServlet Authentication Scheme
Use these steps to configure a new authentication scheme (MobileSSOServlet
authentication scheme) in Access Manager to protect the Web resource(s).
Configuring Mobile OAuth for SSO Servlet Authentication
53-42 Administrator's Guide for Oracle Access Management
1. Log on to the Oracle Access Management Administration Console.
The Application Security Launch Pad opens.
2. Under Access Manager click Authentication Schemes, then click the Create
Authentication Scheme button.
The "Create Authentication Scheme" tab opens.
3. Create a new Authentication Scheme by completing the form as follows:
■Name: MobileSSO-OAuth
■Authentication Level: 2
■Challenge Method: FORM
■Challenge Redirect URL:
/oam/server/
■Authentication Module: LDAP
■Challenge URL:
/mobilesso
■Context Type: customWar
■Context Value:
/ms_oauth/
■Challenge Parameters:
applications=TestApp1,TestApp2
serviceEndPoint=oauthservice
4. In the Oracle Access Management Administration Console, do the following:
a. Create a new Authentication Policy in an Application Domain and assign it
the following Authentication Scheme:
Authentication Scheme: MobileSSO-OAuth
(MobileSSO-OAuth is the scheme that was created in step one.)
Configuring the Mobile Security Manager Plug-in
Configuring OAuth Services 53-43
b. Create an HTTP Resource, for example
/mobileoauthapp
, and protect the
resource using the created Authentication Scheme (MobileSSO-OAuth). This is
the URI that will be accessed from the mobile web browser (mobile Safari for
iOS) and protected by a WebGate.
53.8 Configuring the Mobile Security Manager Plug-in
The Mobile Security Manager Plug-in is an optional plug-in for use with Oracle Mobile
Security Suite (OMSS). If you will be using Oracle Mobile Security Suite, see
Section 52.9, "Understanding OAuth Services Plug-ins" to learn more about this
plug-in.
Before you use this plug-in, you must configure the MSM data source in Oracle Access
Management. Complete these steps to change the target of the
omsm_ds
JDBC data
source to
oam_server1
.
1. Log in to the WebLogic console:
http://host:port/console
2. Navigate to:
base_domain
> Services > Data Sources
3. In the Data Sources table, click
omsm_ds
.
4. Click the Targets tab.
5. Select
oam_server1
.
Configuring the Mobile Security Manager Plug-in
53-44 Administrator's Guide for Oracle Access Management
Part XIII
Part XIII
Managing Oracle Access Management
Oracle Access Portal
This part documents Oracle Access Portal. It contains the following chapters.
■Chapter 54, "Configuring the Access Portal Service"
54
Configuring the Access Portal Service 54-1
54
Configuring the Access Portal Service
[36]
The Access Portal Service is a hosted single sign-on proxy service that enables intranet
and extranet applications with Oracle's form-fill single sign-on technology. It also
provides the REST interfaces that implement the Web Logon Manager end-user web
application. Web Logon Manager, available as a standalone download from Oracle
Support, provides end-users with the ability to create, modify, and delete application
credentials as well as log on to provisioned applications through both desktop and
mobile browsers.
This chapter contains the following sections.
■Prerequisites for Deploying the Access Portal Service
■Overview of the Access Portal Service Deployment Process
■Deploying the Access Portal Service
■Enabling Form-Fill Single Sign-On for an Application
■Adding a Federated Partner Provider Application
■Adding an Oracle SSO Agent Application
■Creating an Application Configuration Package
■Managing Password Generation Policies
■Managing Credential Sharing Groups
■Managing Global Agent Settings
54.1 Prerequisites for Deploying the Access Portal Service
Before completing the steps in this section, you must have completed the following
prerequisites. Refer to the documentation for the respective supporting software for
instructions on configuring that software. The documentation is available on the
Oracle Support web site.
■Install and configure an Oracle database instance
■Install and configure a supported repository (refer to the Certification Matrix for a
list of supported repositories)
■Install and configure an instance of the WebLogic Administration server
■Install and configure an instance of Oracle Access Manager managed server
■Install the Oracle Enterprise Single Sign-On Administrative Console
■(Optional) If you're planning to use the Detached Credential Collector, install and
configure an instance of Oracle HTTP Server
Overview of the Access Portal Service Deployment Process
54-2 Administrator's Guide for Oracle Access Management
54.2 Overview of the Access Portal Service Deployment Process
The Access Portal Service provides form-fill single sign-on functionality to intranet
and extranet Web applications by acting as a proxy between the target application and
the user's browser.
Through the Oracle Traffic Director proxy, the Access Portal Service intercepts user
connections to the target application, fetches the application's logon or password
change page, and injects JavaScript code necessary to perform form-fill single sign-on
tasks (such as credential capture or injection), then delivers the modified page to the
user's browser.
The Access Portal Service utilizes the following components:
■Oracle Traffic Director - intercepts user connections to the target application and
provides path-proxy and DNS-proxy functionality, allowing for path and DNS
rewriting. Also hosts the WebGate plugin.
■WebGate plugin - a plugin that monitors whether the intercepted user
connections require authentication via Oracle Access Manager (based on the
assigned authentication policy) and redirects the user to the authentication page as
necessary. It enables single sign-on functionality (logon, password change, and
credential capture) in internal and external Web applications
■Oracle Access Manager - provides the authentication service to users as defined in
the authentication policy.
■An LDAP Directory - serves as a data repository for the Access Portal Service and
as the authentication back-end mechanism for Oracle Access Manager. For a list of
supported directories, see the Certification Matrix accessible via the Oracle
Support site.
■(Optional) Web Logon Manager - a reference client application that acts as a
launchpad for applications enabled with Oracle's single sign-on technologies.
Web Logon Manager supports Web applications enabled with the Access Portal
Service's form-fill single sign-on technology and is available for download on the
Oracle Technology Network web site. For more information, please contact Oracle
Support.
■Oracle Enterprise Single Sign-On Administrative Console - provides the means
to create and edit form-fill application policies (templates), password generation
policies, delegate credentials, and configure other Access Portal Service features
not accessible via the Oracle Access Manager Console.
■(Optional) Oracle HTTP Server - hosts the Detached Credential Collector Web
pages.
The following is a high-level overview of the deployment process:
1. Deploy the Java Cryptography Extension files on your Oracle Access Manager
server. These files enable unlimited strength jurisdiction policy encryption on
Oracle Access Manager.
2. Create the identity store configuration file. This file contains the connection
specifics for the directory that will host the Access Portal Service data repository.
3. Prepare and enable the Access Portal Service. You must use the IDM
Configuration Tool to extend the directory schema, create the necessary users and
groups, create the Webgate profile, create and assign an authentication scheme,
and create a data repository; then, you must enable the Access Portal Service.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-3
4. Set the Oracle Access Manager policy cache refresh interval. If you plan to use
the Enterprise Single Sign-On Administrative Console to create and modify Access
Portal Service application policies (templates), you must configure the Oracle
Access Manager policy cache refresh interval to ensure that Oracle Access
Manager periodically checks for updated policies in the Access Portal Service
repository.
5. (Optional) Install the Oracle Privileged Account Manager certificates. If you
plan to enable Oracle Privileged Account Manager-protected applications with the
Access Portal Service, you must install the Oracle Privileged Account Manager
certificates into the instance of Oracle Access Manager running the Access Portal
Service. (Only supported on WebLogic.)
6. Deploy the Oracle Traffic Director Administration Server instance. This instance
will provide the means to administrate Oracle Traffic Director proxy instance(s)
(such as configuring listeners, origin servers, and server pools).
7. Deploy the Webgate binaries and Oracle Access Manager secure trust artifacts.
You will run the Webgate installer to deploy the required plugin binaries into
Oracle Traffic Director and copy the Oracle Access Manager secure trust artifacts
into the deployed Webgate instance.
8. (Optional) Deploy the ESSOProvisioning plugin. This plugin enables
provisioning of LDAP credentials as application credentials for single sign-on and
the automatic updating of stored application credentials when the
directory-provided credentials change. This plugin is optional and is not required
by the Access Portal Service.
9. Create an Oracle Traffic Director configuration. An Oracle Traffic Director
configuration is a collection of elements that define the run-time behavior of an
Oracle Traffic Director instance. A configuration contains information about
various elements of an Oracle Traffic Director instance such as listeners, origin
servers, failover groups, and logs.
10. Protect the Oracle Traffic Directory instance with the Webgate plugin. To allow
the Webgate plugin to process user traffic and provide authentication and single
sign-on services, you must place them "in front of" your Oracle Traffic Director
instance. This is called "protecting" the instance with the selected plugins.
11. (Optional) Enable the Detached Credential Collector for the Webgate.
The Detached Credential Collector adds a layer of security by intercepting user
authentication requests normally sent directly to Oracle Access Manager,
collecting the user's credentials, and passing them to Oracle Access Manager.
This avoids the need for users to connect directly to your Oracle Access Manager
instance. The Detached Credential Collector pages run on an instance of Oracle
HTTP Server.
12. Enable target applications for form-fill single sign-on. Once the Access Portal
Service has been successfully deployed, you can begin enabling your target
applications with form-fill single sign-on functionality. This includes configuring
the necessary proxy rules in Oracle Traffic Director, and creating and publishing a
form-fill application policy in Oracle Access Manager.
54.3 Deploying the Access Portal Service
This section describes the steps necessary to configure the environment and deploy
Access Portal. It covers the following tasks.
■Deploying the Java Cryptography Extension Policy Files
Deploying the Access Portal Service
54-4 Administrator's Guide for Oracle Access Management
■Creating the Identity Store Configuration File
■Creating the Oracle Access Manager Configuration File
■Understanding the Access Portal Service Repository Objects
■Integrating with Oracle Privileged Account Manager
■Preparing and Enabling the Access Portal Service on an Oracle Repository
■Preparing and Enabling the Access Portal Service on Microsoft Active Directory
■(Active Directory Only) Deploying the OAMAgent Web Application
■Integrating with Oracle Privileged Account Manager
■Deploying the Oracle Traffic Director Administration Server
■Deploying the Webgate Binaries and Secure Trust Artifacts
■(Optional) Configuring the ESSOProvisioning Plugin
■Creating an Oracle Traffic Director Configuration
■Protecting the Oracle Traffic Director Instance with the Webgate Plugin
■(Optional) Enabling the Detached Credential Collector for the Target Webgate
54.3.1 Deploying the Java Cryptography Extension Policy Files
In order to enable unlimited strength jurisdiction policy encryption on your Oracle
Access Manager server, you must download the appropriate policy files and place
them into your server's Java Runtime Environment.
1. Download the latest policy files from one of the following locations, depending on
your Java Runtime Environment version:
■For Java 7:
http://www.oracle.com/technetwork/java/javase/downloads/
jce-7-download-432124.html
■For Java 6:
http://www.oracle.com/technetwork/java/javase/downloads/
jce-6-download-429243.html
■For IBM JDK on WebSphere:
http://www.ibm.com/developerworks/java/
jdk/security/60/
2. Decompress the downloaded archive and place the
US_export_policy.jar
and
local_policy.jar
in
$JDK_Home/jre/lib/security/
within the target Java
Runtime Environment (replace any existing files when prompted).
3. Reboot the Weblogic Administration Server and the Oracle Access Manager
Managed Server.
54.3.2 Creating the Identity Store Configuration File
Use the guidelines below to create the
idstore.props
file that will configure the
identity keystore for the Access Portal Service. You will pass this file to the IDM
Configuration Tool in Preparing and Enabling the Access Portal Service on an Oracle
Repository.
Oracle Unified Directory Example
# Common
IDSTORE_HOST: IDMHOST1.mycompany.com
IDSTORE_PORT: 1389
IDSTORE_ADMIN_PORT: 4444
Deploying the Access Portal Service
Configuring the Access Portal Service 54-5
IDSTORE_KEYSTORE_FILE: OUD_ORACLE_INSTANCE/OUD/config/admin-keystore
IDSTORE_KEYSTORE_PASSWORD: Password key
IDSTORE_BINDDN: cn=oudadmin
IDSTORE_GROUPSEARCHBASE: cn=Groups,dc=mycompany,dc=com
IDSTORE_SEARCHBASE: dc=mycompany,dc=com
IDSTORE_USERNAMEATTRIBUTE: cn
IDSTORE_LOGINATTRIBUTE: uid
IDSTORE_USERSEARCHBASE: cn=Users,dc=mycompany,dc=com
IDSTORE_NEW_SETUP: true
POLICYSTORE_SHARES_IDSTORE: true
# OAM
IDSTORE_OAMADMINUSER:oamadmin
IDSTORE_OAMSOFTWAREUSER:oamLDAP
OAM11G_IDSTORE_ROLE_SECURITY_ADMIN:OAMAdministrators
# OAM and OIM
IDSTORE_SYSTEMIDBASE: cn=systemids,dc=mycompany,dc=com
# OIM
IDSTORE_OIMADMINGROUP: OIMAdministrators
IDSTORE_OIMADMINUSER: oimLDAP
# WebLogic
IDSTORE_WLSADMINUSER : weblogic_idm
IDSTORE_WLSADMINGROUP : WLSAdmins
Oracle Internet Directory Example
# Common
IDSTORE_HOST: OIDHOST1.mycompany.com
IDSTORE_PORT: 3060
IDSTORE_BINDDN: cn=orcladmin
IDSTORE_GROUPSEARCHBASE: cn=Groups,dc=mycompany,dc=com
IDSTORE_SEARCHBASE: dc=mycompany,dc=com
IDSTORE_USERNAMEATTRIBUTE: cn
IDSTORE_LOGINATTRIBUTE: uid
IDSTORE_USERSEARCHBASE: cn=Users,dc=mycompany,dc=com
POLICYSTORE_SHARES_IDSTORE: true
IDSTORE_NEW_SETUP: true
# OAM
IDSTORE_OAMADMINUSER:oamadmin
IDSTORE_OAMSOFTWAREUSER:oamLDAP
OAM11G_IDSTORE_ROLE_SECURITY_ADMIN:OAMAdministrators
# OAM and OIM
IDSTORE_SYSTEMIDBASE: cn=systemids,dc=mycompany,dc=com
# OIM
IDSTORE_OIMADMINGROUP: OIMAdministrators
IDSTORE_OIMADMINUSER: oimLDAP
# WebLogic
IDSTORE_WLSADMINUSER : weblogic_idm
IDSTORE_WLSADMINGROUP : WLSAdmins
Microsoft Active Directory Example
# Common
IDSTORE_HOST: <AD-server-hostname>
IDSTORE_PORT: <AD-server-port>
IDSTORE_DIRECTORYTYPE: ad
IDSTORE_BINDDN: <domain>\Administrator
IDSTORE_PASSWD: <password>
IDSTORE_USERNAMEATTRIBUTE: cn
IDSTORE_LOGINATTRIBUTE: cn (or another login attribute)>
Deploying the Access Portal Service
54-6 Administrator's Guide for Oracle Access Management
IDSTORE_USERSEARCHBASE: CN=Users,DC=essodev,DC=idc,DC=local
IDSTORE_SEARCHBASE: DC=essodev,DC=idc,DC=local
IDSTORE_GROUPSEARCHBASE: CN=Users,DC=essodev,DC=idc,DC=local
IDSTORE_SYSTEMIDBASE: CN=Users,DC=essodev,DC=idc,DC=local
IDSTORE_OAMSOFTWAREUSER: oamSoftwareUser
IDSTORE_OAMADMINUSER: oamAdminUser
OAM11G_CREATE_IDSTORE: true
ESSO_IDSTORE_HOST : <AD-server-hostame>
ESSO_IDSTORE_PORT : <AD-server-port>
ESSO_IDSTORE_BINDDN : <domain>\Administrator
ESSO_IDSTORE_TYPE : ad
IS_ESSO_PRESENT : true
ESSO_IDSTORE_PASSWD : <password>
Where:
■
IDSTORE_HOST
and
IDSTORE_PORT
are, respectively, the host and port of your
Identity Store directory. Specify the back end directory here, rather than OVD. In
the case of OID and OUD, specify, respectively, one of the Oracle Internet
Directory or Oracle Unified Directory instances, for example:
OID:
OIDHOST1
and
3060
OUD:
IDMHOST1
and
1389
■
IDSTORE_ADMIN_PORT
(
LDAP_DIR_ADMIN_PORT
) is the administration port of your
Oracle Unified Directory instance. If you are not using Oracle Unified Directory,
you can leave out this parameter.
■
IDSTORE_KEYSTORE_FILE
is the location of the Oracle Unified Directory Keystore
file. It is used to enable communication with Oracle Unified Directory using the
Oracle Unified Directory administration port. It is called
admin-keystore
and is
located in
OUD_ORACLE_INSTANCE/OUD/config
. If you are not using Oracle Unified
Directory, you can leave out this parameter. This file must be located on the same
host that the
idmConfigTool
command is running on. The command uses this file
to authenticate itself with OUD.
■
IDSTORE_KEYSTORE_PASSWORD
is the encrypted password of the Oracle Unified
Directory keystore. This value can be found in the file
OUD_ORACLE_
INSTANCE/OUD/config/admin-keystore.pin
. If you are not using Oracle Unified
Directory, you can leave out this parameter.
■
IDSTORE_BINDDN
is an administrative user in the Identity Store Directory
■
IDSTORE_GROUPSEARCHBASE
is the location in the directory where Groups are
Stored.
■
IDSTORE_SEARCHBASE
is the location in the directory where Users and Groups are
stored.
■
IDSTORE_USERNAMEATTRIBUTE
is the name of the directory attribute containing the
user's name. Note that this is different from the login name.
■
IDSTORE_LOGINATTRIBUTE
is the LDAP attribute which contains the users Login
name.
■
IDSTORE_USERSEARCHBASE
is the location in the directory where Users are Stored.
■
IDSTORE_NEW_SETUP
is always set to true for Oracle Unified Directory. If you are
not using OUD, you do not need to specify this attribute.
■
POLICYSTORE_SHARES_IDSTORE
is set to
true
for IDM 11g.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-7
■
IDSTORE_OAMADMINUSER
is the name of the user you want to create as your Access
Manager Administrator.
■
IDSTORE_OAMSOFTWAREUSER
is a user that gets created in LDAP that is used when
Access Manager is running to connect to the LDAP server.
■
OAM11G_IDSTORE_ROLE_SECURITY_ADMIN
is the name of the group which is used to
allow access to the OAM console.
■
IDSTORE_SYSTEMIDBASE
is the location of a container in the directory where users
can be placed when you do not want them in the main user container. This
happens rarely but one example is the Oracle Identity Manager reconciliation user
which is also used for the bind DN user in Oracle Virtual Directory adapters.
■
IDSTORE_OIMADMINGROUP
Is the name of the group you want to create to hold your
Oracle Identity Manager administrative users.
■
IDSTORE_OIMADMINUSER
is the user that Oracle Identity Manager uses to connect to
the Identity store.
■
IDSTORE_WLSADMINUSER
: The username to be used for logging in to the web logic
domain once it is enabled by SSO.
■
IDSTORE_WLSADMINGROUP
: is the name of the group to which users who are allowed
to log in to the WebLogic system components, such as the WLS Console and EM,
belong.
Use OIM entries only if your topology includes Oracle Identity Manager. Use OAM
entries only if your topology includes Access Manager.
54.3.3 Creating the Oracle Access Manager Configuration File
Use the guidelines below to create the
config-oam.props
file that will configure your
Oracle Access Manager instance. You will pass this file to the IDM Configuration Tool
in Preparing and Enabling the Access Portal Service on an Oracle Repository.
Note that the Access Portal Service requires the Simple mode security posture.
To enable this posture, set the parameters below as follows:
OAM11G_OAM_SERVER_TRANSFER_MODE: simple
OAM_TRANSFER_MODE: simple
The file will have the following structure:
Create a properties file called
config_oam.props
with the following contents:
WLSHOST: ADMINVHN.mycompany.com
WLSPORT: 7001
WLSADMIN: weblogic
WLSPASSWD: Admin Password
IDSTORE_DIRECTORYTYPE: OUD
IDSTORE_HOST: IDSTORE.mycompany.com
IDSTORE_PORT: 389
IDSTORE_BINDDN: cn=oudadmin
IDSTORE_USERNAMEATTRIBUTE: cn
IDSTORE_LOGINATTRIBUTE: uid
OAM11G_SERVER_LOGIN_ATTRIBUTE: uid
IDSTORE_USERSEARCHBASE: cn=Users,dc=mycompany,dc=com
IDSTORE_SEARCHBASE: dc=mycompany,dc=com
IDSTORE_GROUPSEARCHBASE: cn=Groups,dc=mycompany,dc=com
IDSTORE_SYSTEMIDBASE: cn=systemids,dc=mycompany,dc=com
IDSTORE_OAMSOFTWAREUSER: oamLDAP
IDSTORE_OAMADMINUSER: oamadmin
Deploying the Access Portal Service
54-8 Administrator's Guide for Oracle Access Management
PRIMARY_OAM_SERVERS: IDMHOST1.mycompany.com:5575,IDMHOST2.mycompany.com:5575
WEBGATE_TYPE: ohsWebgate11g
ACCESS_GATE_ID: Webgate_IDM
OAM11G_OIM_WEBGATE_PASSWD: password to be assigned to WebGate
COOKIE_DOMAIN: .mycompany.com
OAM11G_WG_DENY_ON_NOT_PROTECTED: true
OAM11G_IDM_DOMAIN_OHS_HOST: SSO.mycompany.com
OAM11G_IDM_DOMAIN_OHS_PORT: 443
OAM11G_IDM_DOMAIN_OHS_PROTOCOL: https
OAM11G_SERVER_LBR_HOST: SSO.mycompany.com
OAM11G_SERVER_LBR_PORT: 443
OAM11G_SERVER_LBR_PROTOCOL: https
OAM11G_OAM_SERVER_TRANSFER_MODE: simple
OAM_TRANSFER_MODE: simple
OAM11G_IDM_DOMAIN_LOGOUT_URLS:
/console/jsp/common/logout.jsp,/em/targetauth/emaslogout.jsp
OAM11G_IDSTORE_ROLE_SECURITY_ADMIN: OAMAdministrators
OAM11G_SSO_ONLY_FLAG: false
COOKIE_EXPIRY_INTERVAL: 120
OAM11G_IMPERSONATION_FLAG: false
OAM11G_OIM_INTEGRATION_REQ: false
OAM11G_OIM_OHS_URL:https://SSO.mycompany.com:443
SPLIT_DOMAIN:true
Where:
■
WLSHOST
(
ADMINVHN
) is the host of your administration server. This is the virtual
name.
■
WLSPORT
is the port of your administration server.
■
WLSADMIN
is the WebLogic administrative user you use to log in to the WebLogic
console.
■
WLSPASSWD
is the WebLogic administrator password.
■
IDSTORE_DIRECTORYTYPE
is
OUD
,
OID
or
OVD
.
■
IDSTORE_HOST
and
IDSTORE_PORT
are the host and port of the Identity Store
directory when accessed through the load balancer.
■
IDSTORE_BINDDN
is an administrative user in the Identity Store directory.
■
IDSTORE_USERSEARCHBASE
is the location in the directory where Users are stored.
■
IDSTORE_GROUPSEARCHBASE
is the location in the directory where Groups are
stored.
■
IDSTORE_SEARCHBASE
is the location in the directory where Users and Groups are
stored.
■
IDSTORE_SYSTEMIDBASE
is the location of a container in the directory where the
user oamLDAP is stored.
■
IDSTORE_OAMSOFTWAREUSER
is the name of the user account to be used to interact
with LDAP.
■
IDSTORE_OAMADMINUSER
is the name of the user account that can access your OAM
Console.
■
PRIMARY_OAM_SERVERS
is a comma separated list of your OAM Servers and the
proxy ports they use, for example: IDMHOST1:OAM_PROXY_PORT
Deploying the Access Portal Service
Configuring the Access Portal Service 54-9
■
ACCESS_GATE_ID
is the name you want to assign to the WebGate.
■
OAM11G_OIM_WEBGATE_PASSWD
is the password to be assign to the WebGate.
■
OAM11G_IDM_DOMAIN_OHS_HOST
is the name of the load balancer which is in front of
the OHS's.
■
OAM11G_IDM_DOMAIN_OHS_PORT
is the port that the load balancer listens on (HTTP_
SSL_PORT).
■
OAM11G_IDM_DOMAIN_OHS_PROTOCOL
is the protocol to use when directing requests
at the load balancer.
■
OAM11G_WG_DENY_ON_NOT_PROTECTED
, when set to
false
, allows login pages to be
displayed. It should be set to
true
when using webgate11g.
■
OAM_TRANSFER_MODE
is the security model that the Oracle Access Manager Servers
function in. Valid values are
simple
and
open
. If you use the
simple
mode, you
must define a global passphrase.
■
OAM11G_OAM_SERVER_TRANSFER_MODE
is the security model that the OAM Servers
function in.
■
OAM11G_IDM_DOMAIN_LOGOUT_URLS
is set to the various logout URLs.
■
OAM11G_SSO_ONLY_FLAG
confgures Access Manager as authentication only mode or
normal mode, which supports authentication and authorization.
If
OAM11G_SSO_ONLY_FLAG
is
true
, the OAM Server operates in authentication only
mode, where all authorizations return true by default without any policy
validations. In this mode, the server does not have the overhead of authorization
handling. This is recommended for applications which do not depend on
authorization policies and need only the authentication feature of the OAM Server.
If the value is
false
, the server runs in default mode, where each authentication is
followed by one or more authorization requests to the OAM Server. WebGate
allows the access to the requested resources or not, based on the responses from
the OAM Server.
■
OAM11G_IMPERSONATION_FLAG
is set to
true
if you are configuring OAM
Impersonation.
■
OAM11G_SERVER_LBR_HOST
is the name of the load balancer fronting your site. This
and the following two parameters are used to construct your login URL.
■
OAM11G_SERVER_LBR_PORT
is the port that the load balancer is listening on (HTTP_
SSL_PORT).
■
OAM11G_SERVER_LBR_PROTOCOL
is the URL prefix to use.
■
OAM11G_OIM_INTEGRATION_REQ
should be set to
true
if you are building a topology
which contains both OAM and OIM. Otherwise set to
false
at this point. This
Note: To determine the proxy ports your OAM Servers use:
1. Log in to the Oracle Access Management Console.
2. Click Configuration in the upper right corner.
3. Click Server Instances.
4. Search for the OAM Server, such as WLS_OAM1, and select Open from
the Actions menu.
5. Proxy port is the value shown as Port.
Deploying the Access Portal Service
54-10 Administrator's Guide for Oracle Access Management
value is only set to true when performing Access Manager/Oracle Identity
Manager integration and is set during the integration phase.
■
OAM11G_OIM_OHS_URL
should be set to the URL of your load balancer. This
parameter is only required if your topology contains OAM and OIM.
■
COOKIE_DOMAIN
is the domain in which the WebGate functions.
■
WEBGATE_TYPE
is the type of WebGate agent you want to create.
■
OAM11G_IDSTORE_NAME
is the Identity Store name. If you already have an Identity
Store in place which you wish to reuse (rather than allowing the tool to create a
new one for you), then set the value of this parameter to the name of the Identity
Store you wish to reuse.
■
OAM11G_SERVER_LOGIN_ATTRIBUTE
when set to
uid
, ensures that when users log in,
their username is validated against the
uid
attribute in LDAP.
■
SPLIT_DOMAIN
should be set to
true
If you are creating a domain with just OAM
or OAM located in a different domain from OIM (Split Domain). Otherwise, it is
not necessary to specify this parameter.
54.3.4 Understanding the Access Portal Service Repository Objects
The
vGoLocator
object is required for all repositories and the value of its
vGOLocatorAttribute
attribute specifies the path to the People container in which the
Access Portal Service stores application credentials for each user. The
vGOLocator
object must point to the same data store instance as the Oracle Access Manager
instance on which the Access Portal Service is deployed.
For Oracle LDAP directories, the following applies:
■If there is a single object under the
vGOLocator
container, the
vGoLocatorAttribute
value is parsed regardless of the object's name.
■If there are multiple objects under the
vGOLocator
container, the object named
default is parsed. If no object named
default
exists, the request will fail.
■If
thevGOLocatorAttribute
attribute has no value or does not exist, or if the
vGOLocator
container does not exist, the request will fail.
When using Microsoft Active Directory, the Access Portal Service stores application
credentials under the
Users
container as described below:
■If there is a single object under the
vGOLocator
container, the
vGoLocatorAttribute
value is parsed regardless of the object's name.
■If there are multiple objects under the
vGOLocator
container, the object named
default is parsed. If no object named
default
exists, the data will be within the
USERS
container.
■If
thevGOLocatorAttribute
attribute has no value or does not exist, or if the
vGOLocator
container does not exist, the data will be stored within the
Users
container.
You must explicitly enable the storage of user credentials under respective user objects
using the Oracle Enterprise Single Sign-On Suite Administrative Console. This makes
the following changes to the repository:
■The User class is added as a possible superior to the vGOUserData class.
■All users are granted the right to create vGOUserData objects. These rights are
granted at the directory root and are recursively inherited down to the user
objects.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-11
54.3.5 Preparing and Enabling the Access Portal Service on an Oracle Repository
Before completing this procedure, make sure you have created the required
configuration files as described in Creating the Identity Store Configuration File and
Creating the Oracle Access Manager Configuration File.
The
idmConfigTool
is located at:
IAM_ORACLE_HOME/idmtools/bin
The syntax of the command on Linux is:
idmConfigTool.sh -configOAM input_file=configfile
For example:
idmConfigTool.sh -configOAM input_file=config_oam1.props
When the command runs you are prompted to enter the password of the account you
are connecting to the Identity Store with. You are also asked to specify the passwords
you want to assign to these accounts:
■
IDSTORE_PWD_OAMSOFTWAREUSER
■
IDSTORE_PWD_OAMADMINUSE
R
1. On the machine running your target Oracle Access Manager instance, change into
the following directory:
/Oracle/Middleware/Oracle_IDM1/idmtools/bin
2. Set the following environment variables:
setenv ORACLE_HOME /Oracle/Middleware/Oracle_IDM1
setenv MW_HOME /Oracle/Middleware
setenv JAVA_HOME
JDKPath
(where JDKPath is the full path to the Java Development Kit used by the Oracle
Access Manager instance)
3. Pre-configure the identity store to extend the directory schema with the required
object classes by running the following command:
./idmConfigTool.sh -preConfigIDStore input_file=idstore.props
where
idstore.props
is a property file containing configuration parameters
specific to your environment. For information on assembling this file, see Creating
the Identity Store Configuration File.
4. Create the required users and groups by running the following command:
./idmConfigTool.sh -prepareIDStore mode=all input_file=idstore.props
where
idstore.props
is a property file containing configuration parameters
specific to your environment. For information on assembling this file, see Creating
Note: When you run the
idmConfigTool
, it creates or appends to the
file
idmDomainConfig.param
. This file is generated in the same
directory that the
idmConfigTool
is run from. To ensure that each time
the tool is run, the same file is appended to, always run the
idmConfigTool
from the directory:
IAM_ORACLE_HOME/idmtools/bin
Deploying the Access Portal Service
54-12 Administrator's Guide for Oracle Access Management
the Identity Store Configuration File.
This command does the following:
■Adds the Access Portal Service object classes and attributes to the schema
■Creates the
CO
,
People
, and
vGoLocator
containers (with create permissions
only, including children). For more information on these containers, see
Understanding the Access Portal Service Repository Objects.
5. Create and configure the required Webgate profile by running the following
command:
./idmConfigTool.sh -configOAM input_file=config_oam.props
where
config_oam.props
is a property file containing configuration parameters
specific to your environment. For information on assembling this file, see Creating
the Oracle Access Manager Configuration File.
6. Add conditions to the Admin role in the Security Realm as follows:
a. Log in to the Weblogic Administration Server Console.
b. In the left pane of the console, click Security Realms.
c. On the "Summary of Security Realms" page, click myrealm under the Realms
table.
d. On the "Settings" page for myrealm, click the Roles & Policies tab.
e. On the "Realm Roles" page, expand the Global Roles entry under the Roles
table. This brings up the entry for Roles.
f. Click the Roles link to go to the Global Roles page.
g. On the "Global Roles" page, click the Admin role to go to the Edit Global Role
page:
h. On the "Edit Global Roles" page, under Role Conditions, click Add
Conditions.
i. On the "Choose a Predicate" page, select Group from the predicates list and
click Next.
j. On the Edit Arguments Page, specify
OAMAdministrators
in the Group
Argument field and click Add.
k. Click Finish to return to the "Edit Global Rule" page.
The Role Conditions now show the
OAMAdministrators
Group as an entry.
l. Click Save to finish adding the Admin role to the
OAMAdministrators
Group.
7. Check the log file for any errors or warnings and correct them. A file named
automation.log
is created in the directory where you run the tool.
8. Restart the WebLogic Administration Server.
9. Enable the Access Portal Service:
a. Log on to the Oracle Access Manager Console.
b. Select the Launch Pad tab.
c. In the Configuration section, click Available Services.
d. In the screen that appears, click Enable next to Access Portal Service.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-13
54.3.6 Preparing and Enabling the Access Portal Service on Microsoft Active Directory
The following LDIF file is required for extending the Active Directory schema with
Access Portal Service classes and attributes:
<ORACLE_HOME>/idmtools/templates/ad/esso_schema_extn.ldif
The file is a template file; before proceeding, modify the values such as domain names
and paths to match the target environment.
Complete the following steps to prepare and enable the Access Portal Service with
Microsoft Active Directory:
1. Extend the Active Directory schema by running the following command on the
server machine hosting the repository:
ldifde –i –f esso_schema_extn.ldif
Upon completion, a message will confirm that importing data was successful:
2. Use the
ADSIEdit
tool to create containers named
CO
,
People
, and
vGoLocator
under the repository root.
3. Under the
vGoLocator
container, create an object named
default
of class
vGoLocatorClass
and set its attribute value to the DN of the container that holds
the
People
container. For more information, see Understanding the Access Portal
Service Repository Objects.
4. Enable the storage of user credentials under user objects:
a. Launch the Oracle Enterprise Single Sign-On Suite Administrative Console
and connect to the target repository.
b. In the Console, select Enable Storing Credentials Under User Object (AD
Only) from the Repository menu.
c. The Console displays a dialog informing you of the changes about to be made
to your Active Directory schema. Click OK.
d. Wait for a dialog confirming the changes to appear, then click OK to dismiss it.
Note: After you run
idmConfigTool
, several files are created that you
need for subsequent tasks. Keep these in a safe location.
Two 11g WebGate profiles are created:
Webgate_IDM
, which is used for
intercomponent communication and
Webgate_IDM_11g
, which is used
by 11g Webgates.
The following files exist in the directory
ASERVER_
HOME/output/Webgate_IDM_11g
. You need these when you install the
WebGate software.
■
cwallet.sso
■
ObAccessClient.xml
■
password.xml
Additionally, you need the files
aaa_cert.pem
and
aaa_key.pem
,
which are located in the directory
ASERVER_HOME/output/Webgate_
IDM
.
Deploying the Access Portal Service
54-14 Administrator's Guide for Oracle Access Management
5. Create the users in Active Directory if necessary.
6. Create a user data store:
a. Log on to the Oracle Access Manager console and click Configuration at the
top of the page.
b. Click User Identity Stores.
c. In the screen that appears, click Create under OAM ID Stores.
d. In the dialog that appears, fill in the following required values, leaving the rest
at their defaults:
7. Test the connection and correct any errors if necessary, then click Apply.
8. Update the LDAP authentication module:
a. Log on to the Oracle Access Manager console.
b. In the Plugins section, click Authentication Plug-ins.
c. In the Access Manager section, click Authentication Modules.
d. In the screen that appears, click Search.
e. In the list of search results, select the LDAPPlugin module.
f. In the Steps tab, select the stepUI step.
g. In the KEY_IDENTITY_STORE_REF field, enter the name of the user data
store you created in step 5 of this procedure.
h. Repeat the above for the stepUA step.
i. Click Save to save your changes.
9. Create the identity data store (IDS) profile in Oracle Access Manager:
a. Log on to the Oracle Access Manager console.
b. Click Configuration at the top of the page.
Note: Members of protected groups (i.e., users whose ACLs are
governed by the AdminSDHolder object) will not be able to store
credentials under their user objects until the AdminSDHolder ACL is
updated with permissions required by this feature. See the guide
Deploying Logon Manager with a Directory-Based Repository for
instructions on how to remedy this issue.
Field Value
Store Name
ESSOAuthnStore
Store Type Microsoft Active Directory
Location ad-server-hostname:port
Bind DN domain\username
Password password
Login ID Attribute
cn
User Search Base Fully qualified DN of the Users container
Object Search Base Fully qualified DN of the Groups container
Deploying the Access Portal Service
Configuring the Access Portal Service 54-15
c. Click User Identity Stores.
d. In the IDS Profile section, click Create Form Fill Application IDS Profile.
e. In the form that appears, fill in the fields as follows:
f. Test the connection, then click Apply.
10. Configure the relational mapping of users and groups:
a. Edit the IDS profile you just created.
b. Select the Entity Attributes tab.
c. Add the following new attributes, one at a time (adding multiple attributes at
once is not supported):
member
,
memberOf
,
distinguishedName
d. Select the Entities tab.
e. Under Users, enable the
member
,
memberOf
, and
distinguishedName
entity
attributes.
f. Set the User Base, Group Base, Search Base, and Create Base entities to the
fully qualified DNs of the respective containers in the repository.
g. Repeat steps e and f in the Groups section of the form.
h. Select the Relationships tab.
i. Configure the entity relationships as shown in the following illustration:
Field Value
Name meaningful profile name
Description meaningful profile description
Repository Options Create New
Repository Name meaningful repository name
Directory Type Microsoft Active Directory
Host name Active Directory server host name
Port Active Directory server port
Bind DN domain/user name of repository account
Bind password password of repository account
Base DN fully qualified DN of the repository root
User search base fully qualified DN of the Users container
App template search base fully qualified DN of the CO (ESSO policy data) container
Top search base fully qualified DN of the repository root
Deploying the Access Portal Service
54-16 Administrator's Guide for Oracle Access Management
This makes the following changes in the file
DOMAIN_HOME
/config/fmwconfig/ids-config.xml
:
11. Enable the IDS profile:
a. Select the Launch Pad tab in the Admin console window.
b. At the top of the page, click Configuration.
c. In the Settings section, select Access Portal Service from the View drop-down
list.
d. In the screen that appears, select the IDS profile you created earlier
from the IDS Profile drop-down list.
e. Click Apply.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-17
12. Add the Active Directory schema XML definition file to the IDS server
configuration file:
a. Open the following file in a text editor:
DOMAIN_HOME/config/fmwconfig/ovd/ids/server.os_xml
b. Locate the
<schema check="true">
section and add the following
line inside it:
<location>schema.ms.xml</location>
c. Save and close the file.
d. Restart the managed server instance to apply your changes.
54.3.7 (Active Directory Only) Deploying the OAMAgent Web Application
The
OAMAgent
web application provides the means to configure Access Control Lists
within an Active Directory-based Access Portal Service repository via a web interface
running on Microsoft Internet Information Server.
To deploy th
OAMAgent
web application, do the following:
1. Extract the
OAMAgent.zip
file (available in the Logon Manager folder of the
Enterprise Single Sign-On Suite ZIP archive) into a directory.
2. Using the IIS Manager application, create a new IIS web site; when prompted, in
the Physical Path field, enter the full path to the directory into which you
extracted the
OAMAgent.zip
archive.
3. Edit the newly created web application’s
Web.config
file as follows:
a. Add the following to the
system.webServer
section:
<configuration>
<system.webServer>
<httpHandlers>
<add type="ColumbiaWindowsAgent.Rest.AgentAcl, OAMAgent"
path="ColumbiaWindowsAgent/V1/AgentAcl" verb="POST"/>
</httpHandlers>
</system.webServer>
</configuration>
b. Add the following to the
system.web
section:
<compilation targetFramework="4.0">
<assemblies>
<add assembly="Interop.ActiveDs, Version=1.0.0.0, Culture=neutral"/>
</assemblies>
</compilation>
c. Save and close the file.
4. In the IIS Manager application, navigate to IIS Manager > Target Site > .NET
Compilation > Assemblies and ensure that the new assembly appears in the list
of assemblies (i.e., that the
Interop.ActiveDs.dll
file appears in the web root
directory).
5. Create a new handler mapping:
a. In the IIS Manager application, navigate to IIS Manager > Target Site >
Handler Mappings and click Add Managed Handler in the right-hand pane.
b. In the dialog that appears, fill in the fields as follows and save your changes:
Deploying the Access Portal Service
54-18 Administrator's Guide for Oracle Access Management
6. Enable 32-bit application support:
a. In the IIS Manager application, navigate to IIS Manager > Application Pools.
b. Right-click the target site and select Advanced Settings from the context
menu.
c. Set the Enable 32-bit Applications option to True and save your changes.
7. Make the following site configuration changes:
a. In the IIS Manager application, navigate to IIS Manager > Application Pools.
b. Select the target site.
c. Set the .NET Version to 4.0.
d. Set the Identity option to LocalSystem.
e. Save your changes.
8. In the IIS Manager application, select the host machine, click Server Certificates,
and click Import a Certificate, and provide the path to a root CA certificate trusted
by both the IIS server running the
OAMAgent
web application as well as the server
running the target Access Portal Service instance.
Additionally, the Access Portal Service server must have a certificate signed by
that CA in its keystore. That CA must also be present in the server’s
cacert
file
(trust store).
9. Create a https binding using the newly installed certificate:
a. In the IIS Manager application, right-click the target site and select Edit
Bindings from the context menu.
b. Click Add New Site Binding.
c. Select https from the Type drop-down list.
d. Select the certificate you imported in step 8.
e. Click Close.
10. Enable SSL for the target site:
a. In the IIS Manager application, select the target site.
b. Click SSL Settings.
c. Select the Require SSL check box.
d. Select the Require client certificates check box.
e. Click Apply in the right-hand pane.
11. Add the following to the
oam-config.xml
file on the Access Portal Service server
instance, then restart the instance to apply your changes:
<Setting Name="RestServicePath"
Type="xsd:string">ColumbiaWindowsAgent/V1/AgentAcl</Setting>
<Setting Name="IPAddress" Type="xsd:string">iis-server-hostname</Setting>
Field Value
Path
ColumbiaWindowsAgent/V1/AgentAcl
Type
ColumbiaWindowsAgent.Rest.AgentAcl, OAMAgent
Name
OAMAgent
Deploying the Access Portal Service
Configuring the Access Portal Service 54-19
<Setting Name="Protocol" Type="xsd:string">https</Setting>
<Setting Name="Port" Type="xsd:string">iis-server-port</Setting>
<Setting Name="Version" Type="xsd:string">1</Setting>
<Setting Name="ADPath" Type="xsd:string">AD-server-hostname:port</Setting>
12. Add the following keystore parameters to the managed server’s startup script
JAVA_OPTIONS
line:
-Djavax.net.ssl.keyStore=
keystore-location
-Djavax.net.ssl.keyStorePassword=
keystore-password
54.3.8 Setting the Policy Cache Refresh Interval
When using the Oracle Enterprise Single Sign-On Administrative Console to create
and modify Access Portal Service application policies, the Access Portal Service must
periodically fetch the modified policies from the repository to keep the policy cache up
to date. By default, the cache refresh interval is set to
-1
(never refresh).
To set a custom policy cache refresh interval, complete the steps below. A value of 0
disables the policy cache and causes every request to fetch the corresponding policy
from the repository.
1. Open the following file in a text editor:
OAMDomainHome
/config/fmwconfig/oam-config.xml
2. Locate the following setting string (or add it if it does not already exist).
TimeToLive is set under the ESSOConfig section of the
oam-config.xml
file.
<Setting Name="TimeToLive" Type="xsd:long">-1</Setting>
3. Change the default value (
-1
) to the desired number of minutes.
4. Increment the file's version as described in About the oam-config.xml
Configuration Data File.
5. Save and close the file.
6. Restart both the administration server and the managed server to apply the new
settings.
54.3.9 Integrating with Oracle Privileged Account Manager
When integrating with Oracle Privileged Account Manager, keep the following in
mind:
■Only Oracle Privileged Account Manager templates of type "Privileged" are
supported. Templates of type "Delegated" are not supported when created on the
server side; creating such a template will result in unpredictable behavior.
■You must specify the Oracle Privileged Account Manager server URL in the
Access Portal Service settings in the target Oracle Access Manager server instance.
54.3.9.1 Installing the Oracle Privileged Account Manager Certificates
You must import the certificates into the identity keystore of the application server
running the Oracle Access Manager instance. This procedure is currently only
available for WebLogic; do not perform it on other application servers.
Deploying the Access Portal Service
54-20 Administrator's Guide for Oracle Access Management
1. Obtain the location and name of the identity keystore by examining the value of
the following environment variables in the WebLogic console (where
OAMServerName is the name of the target Oracle Access Manager instance):
environment-servers-
OAMServerName
-keystores
environment-servers-
OAMServerName
-ssl
2. Import the certificate into the identity keystore using the following command:
keytool -importcert -alias
CertificateAlias
-file
CertificateName.crt
-keystore
./IdentityStoreName.jks
-storepass
IdentityStorePassword
where CertificateAlias is a meaningful alias you want to assign to the certificate for
identification, CertificateName is the name of the certificate file, IdentityStoreName is
the name of the target identity store and IdentityStorePassword is the password for
that identity store.
3. Obtain the location and name of the CA certificate by examining the value of the
following environment variable via the WebLogic console:
environment-servers-oam_server1-keystores
4. Import the CA certificate into the identity keystore using the following command:
keytool -importcert -alias
CertificateAlias
-file
CertificateName.der
-keystore
./cacerts
-storepass
IdentityStorePassword
where CertificateAlias is a meaningful alias you want to assign to the certificate for
identification, CertificateName is the name of the certificate file, IdentityStoreName is
the name of the target identity store and IdentityStorePassword is the password for
the
cacerts
identity keystore.
5. Export the target Oracle Access Manager domain's private key certificate (used for
generating the SAML assertion) using the following command:
keytool -export -alias orakey -file orakey.der -keystore
./
IdentityStoreName
.jks
-storepass
IdentityStorePassword
where IdentityStoreName is the name of the target identity store and
IdentityStorePassword is the password for that identity keystore.
6. Change to the following directory:
OPAMDomainHome
/config/fmwconfig
Note: The
listCred
command in OPSS has been deprecated in this
release; keystore passwords must now be retrieved programmatically.
Note: If a keystore type is not explicitly specified in the embedded
trust provider configuration section of the following file:
OAMDomainHome
/config/fmwconfig/jps-config.xml
then the Oracle Key Store Service keystore type is assumed.
If no application stripe name is specified for that KSS keystore, the
service defaults to the following location:
OAMDomainHome
/config/fmwconfig/default-keystore.jks
Deploying the Access Portal Service
Configuring the Access Portal Service 54-21
7. Import the target Oracle Access Manager domain's private key into the target
Oracle Privileged Account Manager domain using the following command:
keytool -importcert -alias orakey -file orakey.der -keystore
./
IdentityStoreName
.jks
-storepass
IdentityStorePassword
where IdentityStoreName is the name of the target identity store and
IdentityStorePassword is the password for that identity keystore.
8. Restart the affected Oracle Access Manager instance and the affected Oracle
Privileged Account Manager instance.
54.3.9.2 Configuring the Oracle Privileged Account Manager Server
Before completing the steps below, make sure you have created a provider on the
target Oracle Access Manager instance for the desired Oracle Privileged Account
Manager instance and placed it as the first provider in the provider list.
On the Oracle Privileged Account Manager instance, do the following:
1. Create a target with the following parameter values:
2. Search for targets and click the target you created in step 1.
3. Click the Privileged Accounts tab.
4. In the Privileged Accounts tab, add the desired privileged account (stored on the
target you created in step 1).
5. Add the desired grantees to the privileged account.
6. Restart both the admin and the privileged Oracle Privileged Account Manager
server instances to apply your changes.
54.3.9.3 Configuring the Provisioning Gateway Server
To create the required template mapping on the Provisioning Gateway server, do the
following:
1. Run the following command on the Provisioning Gateway server machine:
Field Value
Storage Type Deployed repository type
Server Hostname:port of the repository server
Root DN Fully qualified DN of the repository root
User Path Fully qualified DN of the Users container
Connect as User CN of the repository connection account
Password Password of the repository connection account
Use secure connection (SSL) Disabled
Use configuration objects
instead of application list
Enabled
Role/Group support Enabled
Configuration and
role/group objects root DN
Fully qualified DN of the CO container
Admin Group DN (not applicable; leave blank)
User Name Prepend
UID
Deploying the Access Portal Service
54-22 Administrator's Guide for Oracle Access Management
certutil -setreg chain\minRSAPubKeyBitLength 512
2. Restart the Provisioning Gateway server machine.
3. Log on to the Provisioning Gateway Administrative Console.
4. Select the Settings tab, then the Template Mapping section.
5. Click Edit and select the privileged template associated with your Oracle
Privileged Account Manager target, then save your changes. This will create the
required
cn=OpamTemplateMap
mapping in the repository.
6. Test the configuration:
a. Log on to Web Logon Manager as one of the grantees assigned to the target
privileged account.
b. Click Add next to the target privileged template. The privileged account
details will appear in a separate tab.
54.3.10 Deploying the Oracle Traffic Director Administration Server
The Oracle Traffic Director Administration Server provides the means to deploy and
manage Oracle Traffic Director proxy instance(s).
Linux security restricts the opening of ports under 1024 to the
root
user. If you wish to
run Oracle Traffic Director proxies on ports 80 or 443, follow the configuration
gudielines for running as the
root
user described in the "Creating an Administration
Server and Administration Node" chapter of the Oracle Traffic Director Installation
Guide.
1. Launch the installer:
./<OTD-installer>/runinstaller
2. In the screen that appears, click Next.
3. In the next screen, check for and install any applicable updates.
4. In the screen that appears, set the Oracle Traffic Director home directory to the
following and click Next:
/OTD11g/trafficdirector_Home_1
5. Wait for the installation to complete, then change into the following directory:
/OTD11g/trafficdirector_Home_1/bin
6. Create an Oracle Traffic Director administration server instance using the
following command (only include
--server-user=root
if you want to run the
server as the
root
user):
./tadm configure-server --user=admin --host=
otd.hostname
--server-user=root --instance-home=/OTD11g/trafficdirector_Home_
1/instances
Oracle recommends using the default port (
8989
) for the Oracle Traffic Director
administration server.
WARNING: Oracle highly recommends against running Oracle
Traffic Director as the
root
user due to increased security risk; you
should limit the use of the
root
user to development environments
only.
Deploying the Access Portal Service
Configuring the Access Portal Service 54-23
7. Start the Oracle Traffic Director administration server with the following
command:
./OTD11g/trafficdirector_Home_1/instances/admin-server/bin/startserv
8. Log on to the Oracle Traffic Director Admin Console at the following URL:
https://
otd.hostname
:8989
For detailed information on installing Oracle Traffic Director, see the Oracle Traffic
Director Installation Guide.
54.3.11 Deploying the Webgate Binaries and Secure Trust Artifacts
Before completing this procedure, make sure you have created a Webgate profile in
your Oracle Access Manager server as described in Preparing and Enabling the Access
Portal Service on an Oracle Repository; the secure trust artifacts generated during that
procedure are required to complete the steps below.
1. Decompress the Webgate binaries installer into a local directory on the Oracle
Traffic Director host and launch the installer with the following command:
./runInstaller
2. When prompted, specify the full path to your Java runtime environment.
For example:
/usr/local/packages/jdk16
3. In the installer's "Prerequisite Checks" screen, click Next.
4. Specify the installation path and click Next:
/MW_HOME/OAM_OTD_WebGate_HOME
5. Click Install and wait for the installation to complete.
6. Change into the following directory:
/MW_HOME/OAM_OTD_WebGate_HOME/webgate/iplanet/tools/deployWebGate
7. Deploy the Webgate binaries using the following command:
./deployWebGateInstance.sh -w /MW_HOME/wginst1 -oh /MW_HOME/OAM_OTD_
WebGate_HOME -ws otd
8. Copy the Oracle Access Manager artifact files (generated while completing the
steps in Preparing and Enabling the Access Portal Service on an Oracle Repository
as follows:
■Copy the
ObAccessClient.xml
,
cwallet.sso
, and
password.xml
artifact files
to:
/MW_HOME/wginst1/webgate/config
■Copy the
aaa_key.pem
and
aaa_cert.pem
artifact files to:
/MW_HOME/wginst1/webgate/config/simple
9. (Optional) If you deployed your Oracle Traffic Director administration server
instance as the root user, grant that instance permissions to the Webgate
(otherwise, skip this step).
WARNING: Oracle highly recommends against running Oracle
Traffic Director instances as the
root
user due to increased security
risk; you should limit the use of the
root
user to development
environments only.
Deploying the Access Portal Service
54-24 Administrator's Guide for Oracle Access Management
a. Change into
/MW_HOME/wginst1
b. Execute
chmod -R 777 .
54.3.12 (Optional) Configuring the ESSOProvisioning Plugin
When you successfully log on to Oracle Access Manager, the
ESSOProvisioning
plugin
will provision your directory credentials to a specific application in your Access Portal
Service (ESSO) wallet. It will also update the target application credentials if your
directory credentials change.
To enable the plugin, you must assign the ESSOProvAuthnScheme to the
ESSOAuthnPolicy authentication policy in the IAM Suite application domain profile.
1. Log on to the Oracle Access Manager Console.
2. At the top of the page, click Application Security.
3. In the Plug-ins section, click Authentication Modules.
4. In the screen that appears, click Search.
5. In the list of search results, click the ESSOProvisioningModule module.
6. In the screen that appears, select the Steps tab.
7. Edit the
ESSO_PROV_Step
step and enter the name of the target application for
which you want to provision directory credentials.
8. Edit the
ESSO_UI_Step
and
ESSO_UA_Step
steps and add a User Identity Store
value of
KEY_IDENTITY_STORE_REF
to each.
9. Click Save to save the steps, then click Apply to apply your changes to the
module.
10. Select the Launch Pad tab; in the Access Manager section, click Application
Domains.
11. In the screen that appears, click Search.
12. From the list of search results, locate and double-click the IAM Suite profile.
13. Select the Authentication Policies tab.
14. In the list of policies, select ESSOAuthnPolicy.
15. From the Authentication Scheme drop-down menu, select the
ESSOProvAuthnScheme authentication scheme.
16. Click Apply to save your changes.
54.3.13 Creating an Oracle Traffic Director Configuration
1. Log on to the Oracle Traffic Director Admin Console at the following URL:
https://
otd.hostname
:8989
2. Create a new Oracle Traffic Director configuration with the following parameters:
■Name: a descriptive name for the configuration
■Server User: leave at the default value, unless you deployed the Oracle Traffic
Director administration server as root
■Select Origin Server Type:
HTTP
Deploying the Access Portal Service
Configuring the Access Portal Service 54-25
3. Create a listener (your Oracle Traffic Director instance will listen for requests from
the user's browser on this port) with the following parameters:
■Port:
8282
■ServerName: otd.hostname
4. Create an origin server pool with the following parameters:
■Add your target application host as applicationHostname:port
■Select the target node as applicationHostname
5. Click the Instance node in the tree on the left and start the instance.
6. Test the page by accessing the following URL and logging on with your
administrator credentials:
http://
otd.hostname
:8282/
target_webgate_profile
54.3.14 Protecting the Oracle Traffic Director Instance with the Webgate Plugin
To protect your Oracle Traffic Director instance with the Webgate plugin, complete the
steps below.
54.3.14.1 Generating the Secure Trust Artifacts
1. Change into the following directory:
/MW_HOME/OAM_OTD_WebGate_HOME/webgate/iplanet/tools/setup/InstallTools
2. Set the
LD_LIBRARY_PATH
variable:
bash export LD_LIBRARY_PATH=/MW_HOME/OAM_OTD_WebGate_HOME/lib
csh setenv LD_LIBRARY_PATH /MW_HOME/OAM_OTD_WebGate_HOME/lib
3. Run the following command to modify the
magnus.conf
file to include the
directives to load the
webgate
library into the Oracle Traffic Director instance as
well as modify the associated Oracle Traffic Director configuration file to include
the directives to activate the two plugins.
./EditObjConf -f /OTD11g/trafficdirector_Home_
1/instances/
targetInstance
/config/
targetOTDconfiguration
.conf -oh /MW_
HOME/OAM_OTD_WebGate_HOME -w /MW_HOME/wginst1 -ws otd -enableESSO
-enableWLM
54.3.14.2 Loading the Required WebGate Libraries into the OTD Instance
1. Change into the following directory:
/OTD11g/trafficdirector_Home_1/instances/
targetOTDConfiguration
/bin
2. Edit the
startsrv
script in a text editor and add the Webgate library path to the
LD_LIBRARY_PATH
variable as follows:
Note: Only include the
-enableWLM
flag if you have deployed the
Access Portal reference application. Otherwise, the flag is not
necessary.
If you do not include the
-enableWLM
flag and wish to deploy the
Access Portal reference application later, you must manually modify
the appropriate Oracle Traffic Director configuration file as described
in the Access Portal reference application deployment instructions.
Deploying the Access Portal Service
54-26 Administrator's Guide for Oracle Access Management
LD_LIBRARY_PATH="${SERVER_LIB_PATH}:/MW_HOME/OAM_OTD_WebGate_
HOME/lib:${SERVER_JVM_LIBPATH}:${LD_LIBRARY_PATH}";
54.3.14.3 Deploying the Configuration Changes
1. Log into the Oracle Traffic Director Admin Console.
2. Select your configuration and click the Instance Modified notification at the top of
the page.
3. Pull and deploy the changes.
4. When prompted to restart the instance, click OK, then click Finish.
54.3.14.4 Testing the WebGate
1. Navigate to
http://
otd.hostname
:8282/
target_webgate
2. Log on to the Webgate using your repository credentials.
If the target application does not appear, check your configuration for errors.
54.3.15 (Optional) Enabling the Detached Credential Collector for the Target Webgate
This section describes how to enable the Detached Credential Collector for the target
Webgate and how to deploy the Detached Credential Collector pages on Oracle HTTP
Server.
54.3.15.1 Enabling Detached Credential Collector Operations
1. Login to the Oracle Access Management Console.
2. Select Application Security and in the Launch Pad, click Agents icon.
3. In the screen that appears, click Search.
4. From the list of search results, locate and click the agent that is protecting your
OTD Proxy Instance.
5. Check the box Allow Credential Collector Operations.
6. Click Apply to save your changes.
7. Restart the OTD Proxy Instance.
54.3.15.2 Creating and Applying the Detached Credential Collector Authentication
Scheme
1. Login to the Oracle Access Management Console.
2. Select Application Security and in the Launch Pad, click Authentication Schemes
under Access Manager.
3. In the screen that appears, click Search.
4. From the list of search results, locate and click the ESSOProvAuthnScheme
authentication scheme.
5. In the screen that appears, click Duplicate.
6. Give the new scheme a descriptive name - for example
DCC-ESSOAuthnScheme
.
7. In the Challenge Method drop-down list, select FORM.
8. In the Challenge Redirect URL field, enter the Oracle Traffic Director host name
and port in the format
http://
otd.hostname:port
/
(including the trailing slash).
Deploying the Access Portal Service
Configuring the Access Portal Service 54-27
9. In the Challenge URL field, enter
/oamsso-bin/login.pl
10. In the Context Type drop-down list, select external.
11. Click Apply to save your changes.
12. Select the Launch Pad tab.
13. In the Access Manager section, click Application Domains.
14. In the screen that appears, click Search.
15. From the list of search results, locate and click the IAM Suite profile.
16. Select the Authentication Policies tab.
17. Click ESSOAuthnPolicy.
18. In the Authentication Scheme drop-down list of ESSOAuthnPolicy, select the
DCC authentication scheme you just created.
19. Click Apply to save your changes.
54.3.15.3 Deploying Detached Credential Collector Pages on Oracle HTTP Server
1. Enable CGI on the target instance of Oracle HTTP Server if you have not already
done so.
Your httpd.conf should contain the following directive:
LoadModule cgi_module modules/mod_cgi.so
2. Copy the
oamsso
directory from the following location:
$WG_ORACLE_HOME/webgate/iplanet/
To the following location:
$OHS_INSTANCE_DIR/config/OHS/ohs1/htdocs
3. Copy the
oamsso-bin
directory from the following location:
$WG_ORACLE_HOME/webgate/iplanet/
To the following location:
$OHS_INSTANCE_DIR/config/OHS/ohs1/
4. Locate the
<IfModule alias_module>
block in the httpd.conf file.
5. Enable CGI for the following block into the
<IfModule alias_module>
block:
ScriptAlias /oamsso-bin/ "${ORACLE_INSTANCE}/config/
${COMPONENT_TYPE}/${COMPONENT_NAME}/oamsso-bin/"
6. Restart the OHS instance.
7. Test your configuration by accessing the following URL:
http://
ohs.host:port
/oamsso-bin/login.pl
54.3.15.4 Routing Oracle Traffic Director Authentication Requests via the Detached
Credential Collector
1. Under your target Oracle Traffic Director configuration, create a new origin server
pool that points to the Oracle HTTP Server hostname and port.
2. Create a new route that points to the origin server pool created in step 1.
3. Add the following URI condition to the route:
Deploying the Access Portal Service
54-28 Administrator's Guide for Oracle Access Management
/oamsso-bin
OR
/oamsso
4. Save your changes and restart the Oracle Traffic Director instance.
5. Test your configuration by accessing the target application's proxy URL.
54.3.16 Configuring Logon Manager for Compatibility with the Access Portal Service
Complete the steps below to enable interoperability between Logon Manager and the
Access Portal Service. If you have not already done so, install the Authentication
Manager component of Logon Manager on each target end-user machine to enable the
MultiAuth authenticator within Logon Manager.
For more information on configuring Logon Manager repository settings, see the guide
Deploying Logon Manager with a Directory-Based Repository.
54.3.16.1 Modifying the Access Portal Service Configuration
1. In the IDS profile you have configured for the Access Portal Service, ensure that
you are connecting with a user who possesses root privileges (e.g.,
orcladmin
).
2. If you are using Oracle Internet Directory as your repository, set the following
permissions to permit Logon Manager to its First Time Use wizard:
a. For the
vGoLocator
object and its
default
child object:
orclaci = access to attr=(*) by * BindMode="Simple"
(read,search,compare)
orclaci = access to entry by * BindMode="Simple" (browse)
b. For the
People
container:
orclaci = access to attr=(*) by * BindMode="Simple"
(read,write,search,compare)
orclaci: access to entry by * BindMode="Simple" (browse,add,delete)
3. Ensure that the PolicyCache TTL is set to a positive, non-zero value.
54.3.16.2 Modifying the Logon Manager Configuration
1. Launch the Enterprise Single Sign-On Suite Administrative Console and connect
to the Access Portal Service repository.
2. If you are using Active Directory as your repository, do the following (otherwise,
skip this step):
a. Navigate to Global Agent Settings > Live > Synchronization > ADEXT.
b. Select the check box next to the Use secure location for storing user settings
option and select Yes from the drop-down menu.
3. Navigate to Global Agent Settings > Live > Authentication > Authentication
Manager and configure the graded authenticators as required by your
environment. For more information, refer to the Enterprise Single Sign-On Suite
Administrator’s Guide.
Note: For an Application Policy to be compatible, enable the "User
Visible" setting in the Application profile using the Oracle Access
Management Console. This is in addition to the modifications in
Section 54.3.16.1, "Modifying the Access Portal Service Configuration."
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-29
4. Navigate to Global Agent Settings > Live > Authentication and configure each
authenticator as required by your environment, noting the following:
■If using Oracle Internet Directory as your repository, there are two Recovery
Method options Passphrase suppression using entryUUID and Passphrase
suppression using secure key. Select Passphrase suppression using secure
key if displayed; otherwise select Passphrase suppression using entryUUID.
■If using Active Directory as your repository, set the Recovery Method option
to Passphrase suppression using user’s SID.
For more information, see the guide Deploying Logon Manager with a Directory-Based
Repository.
5. Navigate to Global Agent Settings > Live > Synchronization and configure the
appropriate synchronizer as required by your environment, noting the following:
■Enable the Use aggressive synchronization option.
■Enable the Resynchronize when network or connection status changes
option.
■Set the Interval for automatic resynchronization option to
1
.
6. Publish your settings to the repository:
a. In the tree on the left-hand side right-click Live and select Publish from the
context menu.
b. Click Browse and select the target path within the repository. (If prompted,
enter the appropriate connection parameters and click OK to connect.)
c. In the Available configuration objects list, double-click Live to move it to the
list of objects selected for publishing.
d. Click Publish and wait for the operation to complete.
54.4 Enabling Form-Fill Single Sign-On for an Application
This section describes the steps necessary to enable form-fill single sign-on
functionality for an application with the Access Portal Service.
■Configuring a Form-Fill Application Policy
■Configuring Proxy Rules for an Oracle Access Portal Application
54.4.1 Configuring a Form-Fill Application Policy
This section describes how to configure a form-fill application policy. After you create
the policy, you must add a proxy-enabled application URL to the policy to enable
form-fill functionality. Once configured, you must publish the policy to the repository
and test it to ensure that form-fill single-sign on is functioning as expected.
54.4.1.1 Creating a Form-Fill Application Policy
1. Launch the Oracle Enterprise Single Sign-On Administrative Console.
2. In the left-hand tree right-click the Applications node and select New Web
Application from the context menu.
3. In the dialog that appears, enter a descriptive name and click Next. This will
appear as the application policy name in Oracle Access Manager Console.
4. In the screen that appears, select the desired form type and click OK.
Enabling Form-Fill Single Sign-On for an Application
54-30 Administrator's Guide for Oracle Access Management
5. In the screen that appears, enter the URL of the target application.
6. Click Detect Fields.
The application's logon form appears in the window and the appropriate fields are
automatically detected and configured. Verify that:
a. The fields have been detected and configured correctly in the field list.
b. A Submit Button is detected. If no Submit button is defined, Silent Credential
Capture will not function.
For more information on creating application policies (also known as templates),
see the guide Creating and Configuring Logon Manager Application Templates.
7. Click OK to save the application policy.
8. In the General tab, provide optional metadata describing the application (this
metadata will appear in the Access Portal reference application or another user
interface of your choice, if parsed):
■Description – a meaningful description of the application for the user.
■Reference – internal reference describing the version/variant of the
application template.
■Category – the category under which the application will appear in the Access
Portal reference application; for example, "Finance," "Development," and so
on.
■Icon Image URL – URL to the icon image that will appear next to the
application entry in the Access Portal reference application.
■Logo Image URL – URL to the full-size application logo image that will
appear in the Access Portal reference application.
■Vendor – the vendor of the application.
■Administrator – contact information for the application's administrator within
your organization.
9. Select the desired users and/or user groups to whom this template will be
available:
a. Select the Security tab.
b. Select the Access Portal Service repository from the Directory drop-down
menu.
c. Click Add.
d. In the dialog that appears, enter the name of the target user or group.
e. Click Check Names to verify the user or group exists in the directory; if you
receive an error, re-enter the name and try again.
f. Click OK to save your changes.
54.4.1.2 Adding a Proxy-Enabled URL to a Form Fill Application Policy
1. In the policy's General tab, double-click the target form.
2. In the dialog that appears, select the Identification tab and click Add.
3. In the dialog that appears, select the Regular Expression radio button and enter a
launch URL in regular expression format for the target application.
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-31
You must trim any session IDs or other session-sensitive parameters from the
URL, as they will become invalid as soon as the session expires. For example:
.*?https://
otd_proxy_host
\\.oracle\\.com:8282/
target_webgate
/login\\.jsp.*
4. Click OK; then click OK in the parent dialog to save your changes.
54.4.1.3 Configuring Mock Credential Field Values
The Access Portal Service allows you to configure mock credential field values which
will be displayed in the browser during injection for each configured field to prevent
man-in-the-middle snooping.
1. In the policy’s General tab, double-click the target form.
2. In the dialog that appears, select the Proxy tab.
3. In the Mock Fields list, select the desired field and click Edit.
4. In the dialog box that appears, enter the desired mock value and click OK.
To clear the mock values for all fields, click Clear All.
54.4.1.4 Configuring Form Masking
If you want to prevent the user from seeing or altering the injected credentials, you can
configure the Access Portal Service to mask the entire form from view using an
overlay (a solid color or an image of your choice). Keep in mind that:
■If no application credentials exist for the target form, the form will not be masked
even if the mask has been configured, and the user will be able to enter their own
credentials to continue with the form.
■If more than one set of credentials exists for the target form, the Logon Chooser
dialog will appear, allowing the user to choose the desired credentials to inject.
1. In the policy’s General tab, double-click the target form.
2. In the dialog that appears, select the Proxy tab.
3. Select the Mask Form check box to enable form masking.
4. Configure the form mask as follows:
■Mask form – enable/disable masking for the form.
■RED/GRN/BLUE – set the numerical value for the red, green, and blue
components of the desired mask color.
■HEX – enter the hexadecimal value for the desired mask color.
■Select color – opens the color picker, allowing you to pick the desired mask
color visually.
■Image – relative path and filename of the desired mask image to be used
instead of a solid color mask.
■Timeout – number of seconds before the form mask is dismissed.
■Close button – enable/disable the Close button on the form mask (allows user
to remove the mask).
■Opacity – percentage opacity of the form mask.
■Default – reset all form mask options to default values.
Enabling Form-Fill Single Sign-On for an Application
54-32 Administrator's Guide for Oracle Access Management
54.4.1.5 Publishing the Policy to the Repository
1. In the left-hand tree, right-click the target application policy and select Publish
from the context menu.
2. If prompted to connect to the repository, fill in the fields in the "Connect to
Repository" dialog as required.
3. In the "Browse" dialog, navigate to the policies and credentials container you
created in Preparing and Enabling the Access Portal Service on an Oracle
Repository.
For example:
ou=CO,dc=us,dc=oracle,dc=com
4. Click Publish.
54.4.1.6 (Optional) Importing the Policy into the Oracle Access Manager Console
Instead of publishing the policy to the repository, you can import it into the Oracle
Access Manager Console to further edit its basic settings there. If you have already
published it to the repository, you can skip this step, as the Oracle Access Manager
console will retrieve it from the repository and display it in its policies list.
If you modify the policy in the Oracle Access Manager console and then decide to edit
it in the Enterprise Single Sign-On Administrative Console, you will need to manually
pull down the updated version from the Access Portal Service repository.
1. Launch the Enterprise Single Sign-On Administrative Console and load the
desired policy (template) from the repository.
2. Export the policy to a file:
a. From the File menu, select Export.
b. In the "Export to .INI File" dialog that appears, select the policy from the list
and click OK.
c. In the dialog that appears, select Unicode from the Encoding drop-down list,
provide the desired path and name for the exported file, and click Save.
3. Import the template file into Oracle Access Manager:
a. Log on to the Oracle Access Manager console.
b. In the "Access Manager" section of the page that appears, click Applications.
c. In the toolbar above the application list, click Import (blue down-arrow).
d. In the "Import Applications" pop-up that appears, click Browse.
e. In the dialog that appears, navigate to the policy file, and click Open.
f. Click OK in the "Import Applications" pop-up.
g. In the list of applications to import displayed by the pop-up, select the desired
application and click Import.
Note: Oracle recommends creating and configuring the policy in the
Enterprise Single Sign-On Administrative Console as not all Oracle
Access Portal features can be configured in the Oracle Access Manager
Console. Additionally, you must select the Unicode encoding when
saving the exported .INI file; the Oracle Access Management console
does not support importing non-Unicode files.
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-33
h. In the application configuration page that appears, verify that the
configuration settings in each tab have been properly carried over and make
any changes if necessary. When you have finished, click Save.
The imported application policy appears in the application list.
54.4.1.7 Testing the Policy
Test the configuration of your policy as follows:
1. In a Web browser, navigate to
http://
otd.hostname:
8282/
target_webgate and log on
with your repository credentials.
The logon form's fields will highlight indicating the Access Portal Service is ready
to capture application credentials.
2. Enter your application credentials into the logon form and submit them.
3. Close the browser and access the application URL again. You will be automatically
logged on to the application.
If either the credential capture or automatic logon (after credentials have been
captured) do not occur, check your configuration for errors.
54.4.2 Configuring Proxy Rules for an Oracle Access Portal Application
This section provides the basic guidelines for creating the proxy rules necessary to
intercept the user connections to the target application and redirect them to pass
through the Webgate plugin. For in-depth information on configuring Oracle Traffic
Director, please see the Oracle Traffic Director Administrator's Guide.
Since the user connection requested is intercepted by Oracle Traffic Director and
redirected to the origin server, all resources referenced within the page's code must
have their path rewritten to point to the Oracle Traffic Director origin server instead of
the original host; otherwise, those elements will not be loaded and the page will
display improperly and likely not function as intended.
This section contains guidelines for the following types of resources that must be
rewritten for the page to function properly after proxy redirection:
■Path Rewriting Guidelines for HTTP Request/Response Headers
■Path Rewriting Guidelines for Browser Cookies
■Path Rewriting Guidelines for Page Content
54.4.2.1 Adding an Oracle Access Portal Application to Oracle Traffic Director
This section describes the general process for configuring Oracle Traffic Director proxy
rules for an Oracle Access Portal Application residing on a single host server;
applications hosted on multiple servers are not covered. Working knowledge of Oracle
Traffic Director concepts and configuration procedures is assumed.
1. Select the protocol(s) required by the origin server application pages (home, logon,
post URL, landing page) from the following scenarios:
■HTTP only. All of the application’s pages are served over HTTP.
■HTTPS only. All of the application’s pages are served over HTTPS.
■HTTP pre-logon/HTTPS post-logon. Home and login pages are served over
either HTTP or HTTPS; however, the landing page for successfully
authenticated users is served over HTTPS.
Enabling Form-Fill Single Sign-On for an Application
54-34 Administrator's Guide for Oracle Access Management
■HTTP with POST over HTTPS. All of the pages are served over HTTP but the
logon form POST transaction occurs over HTTPS.
For proper security, Oracle highly recommends matching the proxy listener
protocols with those of their respective origin server pages when configuring the
proxy rules. For example, do not configure an HTTP proxy listener for a page that
is originally served over HTTPS.
On the other hand, if you want to configure an HTTPS listener for a page that is
originally server over HTTP, you will need to configure additional proxy rules -
for more information, see the Oracle Traffic Director documentation.
2. Create the appropriate listeners for each protocol and assign them to the target
virtual server.
3. Create the corresponding origin server pools for each protocol. Include the
protocol and URI of the origin application to clearly distinguish between each
pool. For example:
■URI:
http://www.originapp.com
Pool name:
origin-server-pool-http-www-originapp.com
■URI:
https://www.originapp.com
Pool name:
origin-server-pool-https-www-originapp.com
4. Create a route for the origin application using the New Route Wizard as follows:
a. Select the origin server pool you created in step 3. If you created more than
one origin server pool, select the HTTP (non-SSL) pool.
b. Create a URI route condition for the application - this will be the path at which
your application will be accessible. Oracle recommends setting this value to
the name of your origin application or using the condition builder. This path
will be called the
PROXY_MAP
later in this procedure.
For example:
$uri =~ "^/originapp"
c. Complete the remaining steps in the wizard to finish creating the route.
5. In the list of routes, select the route you created in step 4 and open the Advanced
Settings section.
6. In the Rewrite Headers field, add the host header for the origin application in the
following format:
location,content-location,host
7. Apply the following route template and replace the variables as described below:
■
#PROXY_MAP#
- path to the proxied application (reverse map of the From-URI
value) from step 4b. For example:
originapp
.
■
#OTD_HTTP#
- port of the application’s HTTP listener.
For example:
80
■
#OTD_HTTPS#
- port number of the application’s HTTPS listener.
For example:
443
■
#ORIGIN_HOST#
- host name of the origin server pool to rewrite.
For example:
www.originapp.com
■
#DOCUMENT-DOMAIN#
- domain attribute in which cookie values can be
specified.
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-35
For example:
originapp.com
#Instructs OTD to map the incoming URI from the user’s browser to
the root path of the origin server. OTD also uses these values to
create a reverse mapping to rewrite cookie paths.
It is not usually
necessary to change the value of the to parameter.
NameTrans fn="map" to="/" from="/#PROXY_MAP#
"
#Rewrite the https referer header
<If defined $referer and $referer =~
"https://.*?\\.us\\.oracle\\.com:#OTD_HTTPS#/#PROXY_MAP#/(.*)$">
AuthTrans fn="set-variable" set-headers="referer=https://#ORIGIN_
HOST#/$1"
</If>
#Rewrite the http referer header
<If defined $referer and $referer =~
"http://.*?\\.us\\.oracle\\.com:#OTD_HTTP#/#PROXY_MAP#/(.*)$">
AuthTrans fn="set-variable" set-headers="referer=http://#ORIGIN_
HOST#/$1"
</If>
#Remove potential headers that may interfere with mixed proxy
content
<If defined $srvhdrs{'content-security-policy'}>
Output fn="sed-response-header" name="content-security-policy"
sed="s|script-src |script-src 'self' |g"
</If>
<If defined $srvhdrs{'access-control-allow-origin'}>
Output fn="set-variable"
remove-srvhdrs="access-control-allow-origin"
</If>
#rewrite the location header when origin server is redirecting from
HTTP to HTTPS
<If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~
"^https://#ORIGIN_HOST#(:\\d+)?(/?.*)" >
Output fn="set-variable"
$srvhdrs{'location'}="https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#$2"
</If>
Enabling Form-Fill Single Sign-On for an Application
54-36 Administrator's Guide for Oracle Access Management
<If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~
"^http://#ORIGIN_HOST#(:\\d+)?(/?.*)" >
Output fn="set-variable"
$srvhdrs{'location'}="http://$urlhost:#OTD_HTTP#/#PROXY_MAP#/$2"
</If>
#Insert the Dynamic Proxy Script parameters
AuthTrans fn="set-variable"
insert-vars="DYNAMIC-PROXY-ENABLE=on"
insert-vars="DYNAMIC-PROXY-MAP-TO=/#PROXY_MAP#"
insert-vars="DYNAMIC-PROXY-MAP-FROM=/"
insert-vars="DYNAMIC-PROXY-HTTPS=#OTD_HTTPS#"
insert-vars="DYNAMIC-PROXY-HTTP=#OTD_HTTP#"
insert-vars="DYNAMIC-PROXY-IGNORE-PATHS="
#Map all src,href,action,background,data-li-search-action and
data-li-advanced-link attributes found in html content to the
proxied path
Output fn="insert-filter" filter="sed-response" sed="s|\\(
src=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g"
sed="s|\\( src=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2
oap='true'|g" sed="s|\\(
href=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g"
sed="s|\\( href=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2
oap='true'|g" sed="s|\\(
action=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2
oap=\"true\"|g" sed="s|\\(
action=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g"
sed="s|\\( background=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_
MAP#/\\2 oap=\"true\"|g" sed="s|\\(
background=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g"
sed="s|\\(
data-li-advanced-link=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_
MAP#/\\2 oap=\"true\"|g" sed="s|\\(
data-li-advanced-link=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2
oap='true'|g" sed="s|\\(
data-li-search-action=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_
MAP#/\\2 oap=\"true\"|g" sed="s|\\(
data-li-search-action=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2
oap='true'|g" append-newline-at-end="false"
type="(text/html*|text/xml*)"
#Map CSS attributes to the proxied path
Output fn="insert-filter" filter="sed-response"
sed="s|url(\"/\\([^/][^\"]\\)|url(\"/#PROXY_MAP#/\\1|g"
sed="s|url('/\\([^/][^']\\)|url('/#PROXY_MAP#/\\1|g"
sed="s|url(/\\([^/][^)]\\)|url(/#PROXY_MAP#/\\1|g"
type="(text/css*|text/html*)" append-newline-at-end="false"
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-37
#Rewrite full URL links to the OTD proxied host/port. These sed
expressions keep the existing protocols in the URL.
Output fn="insert-filter" filter="sed-response"
sed="s|http://#ORIGIN_HOST#:80|http://$urlhost:#OTD_HTTP#/#PROXY_
MAP#|g" sed="s|http://#ORIGIN_HOST#|http://$urlhost:#OTD_
HTTP#/#PROXY_MAP#|g" sed="s|https://#ORIGIN_
HOST#:443|https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#|g"
sed="s|https://#ORIGIN_HOST#|https://$urlhost:#OTD_HTTPS#/#PROXY_
MAP#|g" sed="s|https:\\\\/\\\\/#ORIGIN_
HOST#|https:\\\\/\\\\/$urlhost:#OTD_HTTPS#\\\\/#PROXY_MAP#|g"
sed="s|http:\\\\/\\\\/#ORIGIN_HOST#|http:\\\\/\\\\/$urlhost:#OTD_
HTTP#\\\\/#PROXY_MAP#|g" type="(text*|application*)"
sed="s|//#ORIGIN_HOST#|https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#|g"
append-newline-at-end="false"
#Sanitize any illegal javascript domain values for our proxied host
Output fn="insert-filter" filter="sed-response"
sed="s|\\(document.domain=\"\\)#DOCUMENT_DOMAIN#\"|\\1$urlhost\"|g"
sed="s|\\(document.domain='\\)#DOCUMENT_DOMAIN#'|\\1$urlhost'|g"
sed="s|\\(document.domain = \"\\)#DOCUMENT_
DOMAIN#\"|\\1$urlhost\"|g" sed="s|\\(document.domain =
'\\)#DOCUMENT_DOMAIN#'|\\1$urlhost'|g" type="(text*|application*)"
append-newline-at-end="false"
#Attempt to rewrite any javascript page redirects
Output fn="insert-filter" filter="sed-response"
sed="s|\\(location.replace(\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_
MAP#/\\2|g"
sed="s|\\(location.replace(\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_
MAP#/\\2|g" sed="s|\\(location.href
=\"\\)\\(/[^/][^\"]*\"\\)|\\1/#PROXY_MAP#\\2|g"
sed="s|\\(location.href ='\\)\\(/[^/][^']*'\\)|\\1/#PROXY_
MAP#\\2|g" type="(text*|application*)"
append-newline-at-end="false"
#Attempt to rewrite any JSON objects that appear as URI paths
.
Output
fn="insert-filter" filter="sed-response"
sed="s|\\(:\"\\)\\(/[^/][^\"]*\"\\)|\\1/#PROXY_MAP#\\2|g"
sed="s|\\(:'\\)\\(/[^/][^\']*'\\)|\\1/#PROXY_MAP#\\2|g"
type="application/json*" append-newline-at-end="false"
#rewrite any javascript page redirects common in ADF applications
Output fn="insert-filter" filter="sed-response" sed="s|\\(redirect
url=\"/\\)|\\1#PROXY_MAP#/|g"
sed="s|<redirect>/\\([^/][^<]*\\)|<redirect>/#PROXY_MAP#/\\1|g"
type="text/xml*"
#Remove any domain attributes from the cookie header. This will
force the browser to use the otd host name as a default
Output fn="sed-response-header" name="set-cookie"
Enabling Form-Fill Single Sign-On for an Application
54-38 Administrator's Guide for Oracle Access Management
sed="s|domain=#DOCUMENT_DOMAIN#||g" sed="s|Domain=#DOCUMENT_
DOMAIN#||g" sed="s|domain=.#DOCUMENT_DOMAIN#||g"
sed="s|Domain=.#DOCUMENT_DOMAIN#||g" sed="s|domain=.#ORIGIN_
HOST#||g" sed="s|Domain=.#ORIGIN_HOST#||g"
8. Paste the generated template into the target route (e.g.
originapp
) section in the
$SERVER-obj.conf file
.
9. If you created one or more HTTPS listeners in step 2, make the following changes
in the target route (e.g.,
originapp
) section of the
$SERVER-obj.conf
file:
a. Locate the following statement:
Route fn="set-origin-server" origin-server-pool=
"origin-server-pool-http-www-originapp-com" rewrite-host="true"
b. Add the following security rule directly above the statement listed in step 9a:
<If $security>
Route fn="set-origin-server"
origin-server-pool="origin-server-pool-https-www-originapp-com"
rewrite-host="true"
</If>
10. Reconfigure the server.
54.4.2.2 Path Rewriting Guidelines for HTTP Request/Response Headers
HTTP request and response headers contain parameters that must be rewritten to
point to the Oracle Traffic Director origin server. Oracle Traffic Director can rewrite
basic location headers that contain the origin server host name and exact protocol, or a
relative path.
A typical HTTP request header looks as follows:
GET /web/en-US/default.aspx HTTP/1.1
Host: www.oracle.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101
Firefox/23.0
Accept: text/html, application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://www.oracle.com/web/en-US/default.aspx ?root=1
Connection: keep-alive
This example header contains the following parameters that require path rewriting:
■
GET
- contains the path of the requested page relative to the Web root, plus HTTP
protocol version.
For example:
GET /web/en-US/default.aspx HTTP/1.1
An example proxy rule for rewriting the
GET
parameter:
NameTrans fn="map" to="/" from="/myLocalPath
"
■
Host
- contains the URL of the page host.
For example:
www.oracle.com
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-39
An example proxy rule for rewriting the
Host
parameter:
Route fn="set-origin-server" origin-server-pool="myoriginserverpool"
rewrite-host="true"
■
Referer
- contains the URL of the page that referred the request. For example:
http://www.oracle.com/web/en-US/default.aspx ?root=1
An example rule for rewriting the
Referer
parameter:
<If defined $referer and $referer =~
"https://myoriginserver.oracle.com/myLocalPath/(.*)$"
>
AuthTrans fn="set-variable"
set-headers="referer=https://www.oracle.com/$1"
</If>
A rewritten version of our example header would then look as follows:
GET /myLocalPath/web/en-US/default.aspx HTTP/1.1
Host: myoriginserver.oracle.com:8484
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101
Firefox/23.0
Accept: text/html, application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: https://myoriginserver.oracle.com:8484/myLocalPath/
web/en-US/default.aspx?root=1
Connection: keep-alive
Oracle Traffic Director can not handle location redirects to another origin server.
For example, if a logon page hosted on one host redirects the user to a page on another
host upon successful logon, you must configure the rewriting rules for this remapping
manually. For example:
<
Object name="route-oracle-travel-sso">
<If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~
"(http|https)://portal.myapplication.com(.*)$">
Output fn="set-variable"
$srvhdrs{'location'}="https://myoriginserver.oracle.com:8484/travel-portal
$2"
</If>
Output fn="sed-response-header" name="set-cookie"
sed="s|path=/travel-sso/|path=/|g"
</Object>
<Object name="route-travel-portal">
Note: Since Web applications vary widely, in addition to the above
examples, you must examine your HTTP headers to account for any
other parameters referencing a URL or a relative path.
Enabling Form-Fill Single Sign-On for an Application
54-40 Administrator's Guide for Oracle Access Management
Route fn="set-origin-server"
origin-server-pool="origin-server-portal-oracle-travle"
rewrite-host="true"
</Object>
54.4.2.3 Path Rewriting Guidelines for Browser Cookies
The path and domain parameters in cookies need to be rewritten to point to the Oracle
Traffic Director origin server instead of the target application host. For example:
Set-cookie: v1st=1666B5EACC906D6; path=/; expires=Wed, 19 Feb 2020
14:28:00 GMT; domain=.www.oracle.com
Must become:
Set-cookie: v1st=1666B5EACC906D6; path=/myLocalPath/; expires=Wed, 19 Feb
2020 14:28:00 GMT; domain=.myoriginserver.oracle.com
When configuring cookie rewriting rules, note the following:
■Oracle Traffic Director cannot rewrite wildcarded domains, such as
.oracle.com
.
A target host name must be specified, for example:
.www.oracle.com
.
■If your application shares cookies across multiple domains, you must create
separate cookie rewriting rules for each domain.
■You must strip out the Oracle Authentication Manager cookie from the cookie set
request, as it interferes with certain Web applications, such as Dropbox.
Example rule for stripping out the Oracle Authentication Manager cookie:
AuthTrans fn="sed-request-header" name="cookie"
sed="s|OAMAuthnCookie[^;]*;| |g" sed="s|OAMRequestContext[^;]*;| |g"
■You must strip out Oracle Authentication Manager headers before sending them
to the application host.
54.4.2.4 Path Rewriting Guidelines for Page Content
Oracle Traffic Director does not directly provide the means to rewrite host names and
resource paths within the HTML code of the target page. You must use sed expressions
to rewrite those values. Common HTML elements whose values will require rewriting
include
src
,
href
, and
action
.
Example sed rule set for rewriting the
src
,
href
, and
action
elements:
Output fn="insert-filter" filter="sed-response"
sed="s|\\(src\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g"
sed="s|\\(src\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g"
sed="s|\\(href\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g"
sed="s|\\(href\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g"
sed="s|\\(action\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g"
sed="s|\\(action\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g"
type="text/html*"
Example rule for rewriting hardcoded host names:
Output fn="insert-filter" filter="sed-response"
sed="s|https://www.oracle.com|https://myoriginserver.oracle.com:8484/myLoc
alPath|g" type="(text*|application*)"
Example rule for rewriting path references within CSS elements:
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-41
Output fn="insert-filter" filter="sed-response"
sed="s|url(\"/\\([^\"|^/]\\)|url(\"/myLocalPath/\\1|g"
sed="s|url('/\\([^'|^/]\\)|url('/myLocalPath/\\1|g"
sed="s|url(/\\([^) |^/]\\)|url(/myLocalPath/\\1|g" type="text/css*"
Note the following when creating host name and path rewriting rules:
■You must include the
"Content-Type"
attribute values for content types used by
the target page in your Oracle Traffic Director configuration file to provide
maximum content compatibility when rewriting.
■Compressed content is not directly supported by sed; you must configure Oracle
Traffic Director to decompress compressed HTML content before applying sed
rewriting rules to the content, and recompress it afterwards.
Example rules for decompressing and recompressing HTML content:
Output fn="insert-filter" type="(text*|application*)"
filter="http-decompression"
Output fn="insert-filter" type="(text*|application*)"
filter="http-compression"
■In some cases, you may be able to strip out the
"Accept Encoding"
parameter in
the request header to prevent the application host from sending compressed data
in the first place.
Example rule for stripping out the
"Accept Encoding"
header:
AuthTrans fn="set-variable" remove-headers="accept-encoding"
■JavaScript code varies widely in complexity and must be examined on a
case-by-case basis in order to create clean, compatible rewriting rules.
54.4.3 Configuring the Webgate Request Filtering
The Webgate plugin provides the following HTTP request filtering mechanisms:
■JavaScript tag injection into incoming (to the user browser) HTML pages
■Mock credential substitution in outgoing POST requests
■HTTP Basic Authentication credential injection and credential capture
■Sanitization of outgoing HTTP requests to remove OAM/ESSO cookies and
headers before the request is forwarded to the origin server
The Webgate plugin requires the following
Init
directives in
magnus.conf
:
■To load NSAPI filters and SAFs:
Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_
Authent,OBWebGate_Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_
Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="
webgate.so
"
obinstalldir="
Webgate_Home_Dir
" obinstancedir="
Webgate_Instance_Dir
"
Init fn="OBWebGate_Init" obinstalldir="
Webgate_Home_Dir
"
obinstancedir="
Webgate_Instance_Dir
" Mode="PEER"
■To enable HTTP Basic Authentication:
Init fn="EssoBasicAuthInit" obinstalldir="
Webgate_Home_Dir
"
obinstancedir="
Webgate_Instance_Dir
" Mode="PEER"
where:
Enabling Form-Fill Single Sign-On for an Application
54-42 Administrator's Guide for Oracle Access Management
54.4.3.1 Configuring the JavaScript Injection Filter
The JavaScript injection filter provides tag injection into pages incoming into the target
user’s Web browser. The following table describes the supported parameters.
For example, adding the following to
obj.conf
Parameter Description
shlib ="
webgate.so
"
Full path to the
webgate.so
module.
obinstalldir ="
WebGate_Home_Dir
"
full path to the target Webgate installation
directory.
obinstancedir ="
WebGate_Instance_Dir
"
full path to the Webgate instance directory.
ESSOEnable ="On|Off"
, default "On"
Enable or disable all plugins.
Parameter Description
ESSOEnable ="on|off"
, default
"on"
Add to either
magnus.conf
or
obj.conf
Enable or disable the JavaScript injection filter. Specifying this
directive in
magnus.conf
disables all ESSO plugin features.
ESSOSearchTag ="str"
, default
"</head>"
Add to
obj.conf
HTML tag to match on for JavaScript injection.
ESSOInjectTag ="before|after"
, default
"before"
Add to
obj.conf
Determines whether to inject the JavaScript tag before or after the
ESSOSearchTag
parameter.
ESSOSearchCaseSensitive ="yes|no"
, default
"no"
Add to
obj.conf
Determines whether the match is case sensitive.
ESSOScriptPath
="path", default
"/oamsso/columbiaWeb.js"
Add to
obj.conf
Passed through to JavaScript as
"src"
ESSOConsoleLoggingLevel ="n"
, default
"0"
,
"5"
is trace.
Add to
obj.conf
Passed through to JavaScript as
"essoConsoleLoggingLevel"
ESSOPartnerId ="str"
Add to
magnus.conf
Partner ID value. Passed through to JavaScript as
"oam_partner"
.
If present, takes precedence over
the "id"
value in
.../webgate/config/ObAccessClient.xml
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-43
AuthTrans fn="set-variable"
insert-vars="DYNAMIC-PROXY-ENABLE=on"
insert-vars="DYNAMIC-PROXY-MAP-TO=/myTarget"
insert-vars="DYNAMIC-PROXY-MAP-FROM=/"
insert-vars="DYNAMIC-PROXY-HTTPS=18484"
insert-vars="DYNAMIC-PROXY-HTTP=18282"
insert-vars="DYNAMIC-PROXY-IGNORE-PATHS=/ignoreMe"
will produce the following result:
Output fn="insert-filter" type="text/*" filter="esso_webproxy"
ESSOSearchTag="</title>"
54.4.3.2 Configuring Dynamic Proxy Support
When dynamic proxy support is enabled (via the
DYNAMIC-PROXY-ENABLE
parameter),
the following parameters are inserted into your route as Oracle Traffic Director server
variables and passed down as JavaScript attributes to configure the dynamic proxy
behavior.
Only non-null values will be passed to the JavaScript tag. If either
DYNAMIC-PROXY-MAP-FROM
or
DYNAMIC-PROXY-MAP-TO
value is not specified, an error
("Dynamic proxy enabled but missing
mapTo
/
mapFrom
") will be logged. Add these
parameters to
obj.conf
.
For example:
<script type='text/javascript' id='MyProxy'
src='/myjavascript/myJavaScript.js'essoConsoleLoggingLevel='5'
...
mapTo='/myTarget' mapFrom='/' ignorePaths='/ignoreMe' otdHttps='18484'
otdHttp='18282'></script></head>
54.4.3.3 Configuring the Mock Credentials Filter
The Mock Credentials filter provides substitution of ESSO mock credentials in the
outgoing POST request. By default, OAM headers are stripped before the request is
passed on to the origin server, but they can be forwarded with the
pass-oam-headers
parameter.
To enable, add a directive with the parameter to your directive in
obj.conf
as follows:
pass-oam-headers="true|false"
, default
"false"
This includes the following headers (by default, they are omitted):
Parameter Description
DYNAMIC-PROXY-ENABLE ="on|off"
, default
"off"
Enables or disables the dynamic proxy functionality. When
disabled, the parameters listed in the remainder of this table
are not passed to the JavaScript injection filter.
DYNAMIC-PROXY-MAP-TO
Destination URI. Default is null (empty string).
DYNAMIC-PROXY-MAP-FROM
Source URI. Default is null (empty string).
DYNAMIC-PROXY-HTTPS
HTTPS port number. Default is null (empty string).
DYNAMIC-PROXY-HTTP
HTTP port number. Default is null (empty string).
DYNAMIC-PROXY-IGNORE-PATHS
URIs that should be ignored. Default is null (empty string).
Enabling Form-Fill Single Sign-On for an Application
54-44 Administrator's Guide for Oracle Access Management
■
OAM_IMPERSONATOR_USER
■
OAM_REMOTE_USER
■
OAM_LAST_REAUTHENTICATION_TIME
■
OAM_IDENTITY_DOMAIN
For example:
Input fn="insert-filter" type="application/x-www-form-urlencoded"
filter="esso_webproxy_input" pass-oam-headers="true"
54.4.3.4 Configuring HTTP Basic Authentication
HTTP Basic Authentication provides the ability to capture and inject credentials from
and into Web browser basic authentication (modal) dialogs.
Configure HTTP Basic Authentication in the
magnus.conf
as follows:
■Add the
EssoBasicAuthInit
and
EssoBasicAuth
functions to the
load-modules
Init directive (explained in Configuring the Webgate Request Filtering).
■Add a standalone Init directive that loads the
ESSOBasicAuthInit
function:
For example:
Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_
Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_
Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="
webgate.so
"
obinstalldir="
Webgate_Home_Dir
" obinstancedir="
Webgate_Instance_Dir
"
Init fn="EssoBasicAuthInit" obinstalldir="
Webgate_Home_Dir
"
obinstancedir="
Webgate_Instance_Dir
" Mode="PEER"
Then, add one or more of the following parameters to
obj.conf
for the header
injection SAF and the credential capture filter:
For example:
NameTrans fn="EssoBasicAuth" policy="BasicAuth1" realm="realm1"
Output fn="insert-filter" filter="esso_output_capture" policy="BasicAuth1"
realm="realm1"
Note: HTTP Basic Authentication is enabled by default when you
install the Access Portal Service. To disable it, remove the
EssoBasicAuthInit
and
EssoBasicAuth
functions from the
load-modules
Init directive and delete the
fn="EssoBasicAuthinit"
standalone directive from the
magnus.conf
file.
Parameter Description
policy
="
policy name
"
Required. Name of the ESSO policy (application
template) to use for authentication.
realm
="
realm name
"
Optional. The desired authentication realm of the
target website, if more than one realm is in use.
Enabling Form-Fill Single Sign-On for an Application
Configuring the Access Portal Service 54-45
54.4.3.5 Configuring the HTTP Request Sanitizer
The HTTP request sanitizer strips the proxied HTTP request of any cookies and
headers added by Oracle Access Manager and the Webgate plugin before the request is
forwarded to the origin server.
The sanitizer removes cookies with the following names:
■
OAM_Partner
■
OAMAuthnCookie_*
■
OAMRequestContext*
■
OAMAuthnHintCookie
■
OAM_*
■
ESSO_BAH*
(Basic Authentication Hint, caches policy, realm, and credential GUID)
Request-specific cookie names (for example, containing the server name) are matched
using a wildcard, indicated above by the trailing asterisk.
The sanitizer removes the following headers:
■
OAM_IMPERSONATOR_USER
■
OAM_REMOTE_USER
■
OAM_LAST_REAUTHENTICATION_TIME
■
OAM_IDENTITY_DOMAIN
To enable the sanitizer, add the
EssoClean
function to the
load-modules
Init directive
in the
magnus.conf
file. For example:
Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_
Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_
Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="
webgate.so
"
obinstalldir="
Webgate_Home_Dir
" obinstancedir="
Webgate_Instance_Dir
"
Then, add the following to the
obj.conf
file:
<If not $uri =~ "/oamsso">
NameTrans fn="EssoClean"
</If>
The Webgate plugin passes the target credential’s GUID value in the proxied URL to
the origin server. If the target application does not function properly due to this value
Note: The Mock Credentials filter also provides this sanitization, but
only while processing HTTP POST requests that contain mock
credentials. The Webgate HTTP request sanitizer performs this
function unconditionally on all requests.
Note: The HTTP Request Sanitizer is enabled by default when you
install the Access Portal Service. To disable it, remove the
EssoClean
function from the
load-modules
Init directive in the
magnus.conf
file,
and remove the above code from the
obj.conf
file.
Adding a Federated Partner Provider Application
54-46 Administrator's Guide for Oracle Access Management
being passed, add the following rewrite rule to the Oracle Traffic Director
configuration to strip out the GUID value:
<If defined $query and $query =~ "(.*?)(ESSOCredGuid={.*?})(.*)$">
AuthTrans fn="set-variable" set-reqpb="query=$1$3"
</If>
54.5 Adding a Federated Partner Provider Application
To add a federated partner provider application to the Access Portal Service
application catalog, do the following:
1. Log on to the Oracle Access Manager console.
2. In the Quick Start Wizards section of the Launch Pad tab, click Application
Registration.
3. In the page that appears, fill in the fields as follows:
a. Vendor - the vendor of the application.
b. Name - a descriptive name for the application.
c. Type - select Federated Server Partner Provider Application from this
drop-down menu, as desired.The application will be available to all Access
Portal users.
d. Description - a meaningful description of the application for the user.
e. Reference - internal reference describing the version/variant of the application
template.
f. Category - the category under which the application will appear; for example,
"Finance," "Development," and so on.
g. Reference - an internal reference for the application template, such as a
version number or features that are enabled.
h. Icon Image URL - URL to the icon image that will appear next to the
application entry. A preview of the image is displayed below the field to
confirm the URL is valid.
i. Logo Image URL - URL to the full-size application logo image. A preview of
the image is displayed below the field to confirm the URL is valid.
j. When you have finished, click Next.
4. In the "Configuration" page that appears, do the following:
a. In the Partner field, enter the desired federated partner name. If you don't
know the exact name, click the Search (magnifier) icon, enter the desired
search term in the pop-up that appears, select the desired partner from the list
of results, and click OK to add that partner to the template.
If you want to create a new partner, click Create and refer to the "Identity
Federation" chapter for more information on creating a new federation
partner.
b. In the Application URL field, enter the URL to the target application; obtain
this URL from your application administrator.
c. Click Next.
Creating an Application Configuration Package
Configuring the Access Portal Service 54-47
5. In the summary page that appears, review your configuration choices. To make
changes, click Back; otherwise, click Finish.
54.6 Adding an Oracle SSO Agent Application
To add an Oracle SSO Agent application to the Access Portal Service application
catalog, do the following:
1. Log on to the Oracle Access Manager console.
2. In the Quick Start Wizards section of the Launch Pad tab, click Application
Registration.
3. In the page that appears, fill in the fields as follows:
a. Vendor - the vendor of the application.
b. Name - a descriptive name for the application.
c. Type - select SSO Agent Application from this drop-down menu, as
desired.The application will be available to all Access Portal users.
d. Launch URL - enter the URL of the target application; obtain this URL from
your application administrator.
e. Description - a meaningful description of the application for the user.
f. Reference - internal reference describing the version/variant of the
application template.
g. Category - the category under which the application will appear; for example,
"Finance," "Development," and so on.
h. Reference - an internal reference for the application template, such as a
version number or features that are enabled.
i. Icon Image URL - URL to the icon image that will appear next to the
application entry. A preview of the image is displayed below the field to
confirm the URL is valid.
j. Logo Image URL - URL to the full-size application logo image. A preview of
the image is displayed below the field to confirm the URL is valid.
k. When you have finished, click Next.
4. In the summary page that appears, review your configuration choices. To make
changes, click Back; otherwise, click Finish.
54.7 Creating an Application Configuration Package
The Access Portal Service ships with a configuration package tool that allows you to
generate an environment-specific Access Portal Service configuration package for
select target applications. The package will contain pre-configured application
templates, as well as Oracle Traffic Director content rewriting and proxy rules that
configure the Access Portal Service for the target application.
54.7.1 Contents of the Application Configuration Package
The application configuration package contains the following:
■Logo image(s) or URL(s) to the logo image(s) for the application.
Creating an Application Configuration Package
54-48 Administrator's Guide for Oracle Access Management
■Application policies (templates) and password generation policies (if defined) in
.INI
format, exported from the Enterprise Single Sign-On Administrative Console
(
formfill.ini
).
■Oracle Traffic Director configuration data (described in detail in Enabling
Form-Fill Single Sign-On for an Application):
–Origin server pool definitions to be added to the
server.xml
file on the target
managed server instance.
–Rewriting rules for SED headers, page content, cookies, and so on, to be added
to the
object.conf
file on the target Oracle Traffic Director instance.
–Route configuration directives to be added to the
routes.conf
file on the
target Oracle Traffic Director instance.
The Oracle Traffic Director configuration data must not contain any hardcoded
values such as host names, port numbers, and session identifiers, and should use
the preprocessor directives described in the next section.
54.7.2 Required Environment-Specific Configuration Data
You must provide the tool with the following configuration data specific to your target
environment:
■
%OTD_HOST%
■
%OTD_HTTP_PORT%
■
%OTD_HTTPS_PORT%
Optionally, you may also provide forward proxy configuration as follows:
■
%FORWARD_PROXY_HOST%
■
%FORWARD_PROXY_PORT%
54.7.3 Customizing an Application Configuration Package to the Target Environment
Create your source configuration files as follows before generating an application
configuration package as described in this section. If desired, compress the files into a
ZIP archive named after the target application for easier portability.
54.7.3.1 Preprocessor Directives for the Oracle Traffic Director Configuration Data
Because a preprocessor will parse your configuration data in order to apply the
configuration to the target Oracle Traffic Director instance, you must define the
following preprocessor directives in your configuration files:
■
%OTD_HOST%
■
%OTD_HTTP_PORT%
■
%OTD_HTTPS_PORT%
Optionally, you may also define the following directives if your environment requires
them:
■
%FORWARD_PROXY_HOST%
■
%FORWARD_PROXY_PORT%
For example, a regex match URI for an application would look as follows:
.*?https://%OTD_HOST%:%OTD_HTTPS_PORT%/myapplication.*
Creating an Application Configuration Package
Configuring the Access Portal Service 54-49
54.7.3.2 Rewriting Directives (object.conf)
This file will contain the Oracle Traffic Director rewriting rules for SED, headers,
content, and routes for the target application. It must not contain any hardcoded
values; use the preprocessor directives listed earlier instead. For example:
<Object name="route-myapplication"><If defined $referer and $referer =~
"$server_url/myapplication/(.*)$">
AuthTrans fn="set-variable"
set-headers="referer=https://participant.myapplication.com/$1"
</If>
NameTrans fn="map" to="/" from="/myapplication"
Route fn="set-origin-server"
origin-server-pool="origin-server-pool-participant-myapplication-com"
Output fn="insert-filter" filter="sed-response"
sed="s|\\(src\\)=\"/\\([^\"]\\)|\\1=\"/myapplication/\\2|g"
sed="s|\\(href\\)=\"/\\([^\"]\\)|\\1=\"/myapplication/\\2|g"
sed="s|\\(action\\)=\"/\\([^\"]\\)|\\1=\"/myapplication/\\2|g"
Output fn="insert-filter" filter="sed-response"
sed="s|https://participant.myapplication.com|https://$urlhost:%OTD_HTTPS_
PORT%/myapplication|g"
</Object>
Name this file
object.conf
and place it in the common package directory. The
package generation tool will create a new file in that directory with the generated
prefix in its name.
54.7.3.3 Origin Server Pools (server.xml)
Name this file
server.xml
and place it in the common package directory. The package
generation tool will create a new file in that directory with the generated prefix in its
name. For example:
<origin-server-pool>
<name>origin-server-pool-participant-myapplication-com</name>
<family>inet</family>
<type>https</type>
<origin-server>
<host>participant.myapplication.com</host>
</origin-server>
</origin-server-pool>
54.7.3.4 Routing Conditions (routes.conf)
Name this file
routes.conf
and place it in the common package directory. The
package generation tool will create a new file in that directory with the generated prefix
in its name. For example:
<If $uri =~ "/myapplication">
NameTrans fn="assign-name" id="route-myapplication"
name="route-myapplication"
</If>
Creating an Application Configuration Package
54-50 Administrator's Guide for Oracle Access Management
54.7.4 Generating the Customized Application Configuration Package
To customize the application configuration package to your target environment, use
the
apspackageutility.jar
tool. The tool is located in the following location within
the Access Management suite installer archive:
../iamsuite/Disk2/stage/Components/oracle.oam.server/11.1.2.3.0/
1/DataFiles/Expanded/server/tools/apsapputility
The tool syntax is as follows:
java -jar apsapputility.jar
-p
properties-file
-z
package-file or
-d
package-directory
where:
■
-p
properties-file - full path and name of the property file to process (
object.conf
,
server.xml
,
route.xml
, or
formfill.ini
). This file contains the values for the
properties listed in Required Environment-Specific Configuration Data.
■
-z
package-file - full path and name of the package ZIP file (if using a ZIP file), or
■
-d
package-directory - full path to the directory containing the configuration files
(if not using a ZIP file)
The
-z
and
-d
options are mutually exclusive; use only one or the other.
The tool will add the customized file(s) to the ZIP file or package directory, depending
on the selected option; the names of the generated files will contain the
generated-
prefix. The generated file(s) will be output one directory up from where the source
files are located.
54.7.5 Deploying the Customized Application Configuration Package
To deploy the customized application configuration package, do the following:
1. Deploy the generated form-fill application policies (templates) and password
generation policies, if defined (
generated-formfill.ini
). Log on to the Oracle
Access Management Console, navigate to the Applications section and upload the
file.
2. Deploy the generated rewriting rules (
generated-object.conf
).
a. Open the following file in a text editor:
target-otd-instance-directory
/config/
server-name
-obj.conf
b. Paste the contents of the
generated-object.conf
file inside the following tag:
<Object name="default">
paste contents here
</object>
3. Deploy the generated origin server pool definitions (
generated-server.xml
):
a. Open the following file in a text editor:
target-otd-instance-directory
/config/server.xml
b. Paste the contents of the
generated-server.xml
file inside the following tag:
Note: The package generation tool requires an up-to-date Java
Runtime Environment installation.
Managing Password Generation Policies
Configuring the Access Portal Service 54-51
<server>
paste contents here
</server>
4. Deploy the generated route conditions (
generated-routes.xml
):
a. Open the following file in a text editor:
target-otd-instance-directory
/config/
server-name
-obj.conf
b. Paste the contents of the
generated-routes.conf
file at the end of the file.
54.8 Managing Password Generation Policies
Password policies facilitate user logons while ensuring the organization's security. The
Access Portal Service lets administrators set policies that control automatic password
generation.
Most applications have constraints for passwords: how long they can or must be,
whether they must or must not include numbers or symbols, and so on. the Access
Portal Service's password generation feature improves application logon security by
automatically creating passwords made up of random characters according to
predefined sets of constraints, stored as password policies. Each policy can apply to
multiple applications or subscribers.
Using predefined password policies, you can completely automate password changes
and implement sophisticated security schemes, including complex passwords and
application-specific passwords unknown to users.
To manage password generation policies, click Federation at the top of the
Administrative Console, then click Password Generation Policies in the Access Portal
Service section. A new tab containing options to search and create opens.
Figure 54–1 Password Generation Policies Search/Create Tab
54.8.1 Searching for Password Generation Policies
To search for an existing policy:
1. Enter a name or partial string in the Name field, and click the Search button. The
results appear in the Search Results table.
Managing Password Generation Policies
54-52 Administrator's Guide for Oracle Access Management
2. Click any policy in the Search Results list to edit the policy configuration.
Continue to step 3 in the next section to learn more about configuring these
settings.
54.8.2 Creating Password Generation Policies
To create a new policy:
Figure 54–2 New Password Generation Policy Summary Tab
1. Click the Create Password Generation Policy button to launch the New Password
Policy tab, which contains two sub-tabs:
■Summary
■Password Constraints
2. On the Summary tab, enter the following information:
■A distinct name for the policy.
■(Optional) A meaningful description to identify the policy.
■(Optional) Internal reference information describing the version/variant of the
policy.
3. Click the Password Constraints tab.
On the Password Constraints tab, specify the following:
■Length Constraints
Note: If you would like to specify your password constraints using
regular expressions, enter the desired REGEX string into the Regular
Expressions Constraint field. Doing so will override and disable the
manual constraint options listed below (except the Previous Password
Constraints options).
Managing Password Generation Policies
Configuring the Access Portal Service 54-53
–The minimum password length. Options are 1-128. Default is 8 characters.
–The maximum password length. Options are 1-128. Default is 8 characters.
■Alphabetic Characters
–Check the box to allow uppercase characters. If you check the box, you
must specify the minimum number required. Default is 0.
–Check the box to allow lowercase characters. If you check the box, you
must specify the minimum number required. Default is 0.
■Special Characters
–Check the box to allow non-alphabetical and/or non-numeric characters.
If you check the box, you must specify the minimum and maximum
number permitted. Default minimum is 0. Default maximum is 8.
–Check the box(es) to allow a special character to start and/or end a
password.
■Excluded Characters
–Enter a list of specific characters to exclude from a password. Do not use
any delimiters.
■Repeat Constraints
–Enter the maximum number of times a given character can be repeated in
a password (in any position). Options are 0-127. Default is 7.
–Enter the number of times a given character can be repeated consecutively
(adjacent to itself). Options are 0-127. Default is 7.
■Numeric Characters
–Check the box to allow numeric characters. If you check the box, you must
specify the minimum and maximum number permitted. Default
minimum and maximum is 0.
–Check the box(es) to allow a numeric character to start and/or end a
password.
■Other Characters
–Check to allow other characters to be included in a password.
■Previous Password Constraints
– Disallow use of previous password. Check the box to prohibit reusing the
previous password entirely.
– Limit use of previous password characters. Select to limit repetition of
characters from the previous password.
– Maximum previous password characters. If you checked the previous
box to permit usage of some previous password characters, select the
maximum number of characters to allow.
Managing Password Generation Policies
54-54 Administrator's Guide for Oracle Access Management
4. Click Save to complete policy configuration, or Cancel to close the tab without
saving the policy.
Figure 54–3 Password Constraints Tab of a Password Generation Policy
54.8.3 Managing Policy Subscribers
Applications that use a password generation policy are called subscribers. You can add
subscribers during creation of the policy or at any time thereafter. Following is the
procedure to add subscribers to a policy.
Note: The Access Portal Service recognizes multiple occurrences of a
character as the same character and will therefore permit more than
one occurrence of that character in the new password.
So, if the previous password contained three "A"s, and you specify
that one character from the previous password can repeat, the Access
Portal Service will allow more than one instance of "A" in the new
password.
Managing Credential Sharing Groups
Configuring the Access Portal Service 54-55
Figure 54–4 Add Applications Dialog
1. On the Password Generation Policy Summary page, click the Add icon. The Add
Applications dialog appears.
2. In the Name field, enter a name or text string and click Search. You can also leave
this field blank to return every available application.
3. After a search, all applications that fit your search criteria appear in the Available
Applications list. For each application, the list includes any policy to which it
subscribes.
4. Select one or more applications from the Available Applications list, and click
Add Selected. Or simply click Add All to add every application returned by the
search.
If you select an application that is already a subscriber to another policy, it will no
longer be subscribed to the other policy.
5. Click Add when you are finished, or Cancel to dismiss the dialog without making
changes.
6. Click Save to save your policy.
54.9 Managing Credential Sharing Groups
Credential sharing groups are sets of applications that share the information of one or
more fields to facilitate account management, allowing users to apply a credential
change made in one application to other specified applications automatically. For each
group that you create, you can include any number of applications and designate
which credentials they have in common.
When the Access Portal Service handles a credential change for any application that is
a member of the sharing group, it automatically applies the credential change to all
other group members. Any number or combination of applications can share a single
credential. You can also designate a key field; that is, a field that the Access Portal
Service uses when updating shared credentials, changing credentials only for accounts
with the same key value.
Managing Credential Sharing Groups
54-56 Administrator's Guide for Oracle Access Management
the Access Portal Service provides flexibility and granularity for you to control how
credential sharing groups work. You can configure the following options:
■Sharing any or all fields for a group of applications:
■Pre-filling all shared fields when a user first encounters an application in a sharing
group, thus requiring the user to enter information only for fields that are not
shared by the group.
■Automatically creating an account when a user encounters an application for
which all credentials are pre-determined.
■Designating a key field; that is, a field that the Administrative Console uses when
updating shared credentials, changing credentials only for accounts with the same
key value.
The next sections describe how to create new groups or edit existing ones. After you
create a group, the process for configuring it is the same as editing an existing one.
54.9.1 Searching for Credential Sharing Groups
To search for an existing group:
1. Click Federation at the top of the Administrative Console, then click Credential
Sharing Groups in the Access Portal Service section of the tab that appears.
2. Enter a name or partial string in the Name field, and click the Search button. The
results appear in the Search Results table.
3. Click on any group in the Search Results list to edit its configuration. Continue to
step 3 in the next section to learn more about configuring these settings.
Figure 54–5 Credential Sharing Groups tab
54.9.2 Creating Credential Sharing Groups
To create a new group:
Note: Applications will share credentials only for their initial
deployment unless you enable credential sharing groups.
Managing Credential Sharing Groups
Configuring the Access Portal Service 54-57
1. Click the Create Credential Sharing Group button to launch the New Credential
Sharing Group page.
2. In the Name field, enter a name for the group. Optionally, you can add a
description and reference information in the fields at the bottom of this section.
3. In the Shared credentials settings, select which credentials the group will share.
You can include any or all fields:
–Username
–Password
–Third Field
–Fourth Field
4. From the Key Credential within group dropdown, select a field. The key
credential field provides more granular criteria for updating shared credentials
within a group. When a credential changes, updates will only occur for members
that share the key field. to update shared credentials only for accounts that share
this field value.s only for accounts that share this field value.:
If the user wants to create an account that is not constrained by the key field, that
account must have a new key field to avoid updating all existing accounts.
Choose one of the following from the dropdown:
■None (Default)
■Username
■Third Field
■Fourth Field
5. If desired, select to pre-fill shared fields. This specifies that shared fields will be
pre-populated with the shared credentials when the user creates a new account for
an application. By default, this option is enabled.
6. If desired, select to automatically create accounts when all credentials are known.
This means that the Access Portal Service will create an account automatically
when the user encounters an application that has all fields pre-determined.
7. Click Save to complete policy configuration, or Cancel to close the tab without
saving the group.
Note: This field is available only if Key credential within group is
set to None.
Managing Credential Sharing Groups
54-58 Administrator's Guide for Oracle Access Management
Figure 54–6 New Credential Sharing Group Page
54.9.3 Managing Applications in Credential Sharing Groups
You can add applications to a group during creation of the group or at any time
thereafter. Following is the procedure to add applications to a group.
Managing Global Agent Settings
Configuring the Access Portal Service 54-59
Figure 54–7 Add Applications Dialog
1. In the Applications section of the group page, click the Add icon. The Add
Applications dialog appears.
2. In the Name field, enter a name or text string and click Search. You can also leave
this field blank to return every available application.
3. After a search, all applications that fit your search criteria appear in the Available
Applications list. For each application, the list includes any credential sharing
group to which it belongs.
4. Select one or more applications from the Available Applications list, and click
Add Selected. Or simply click Add All to add every application returned by the
search.
If you select an application that is already a member of another group, it will no
longer be part of that group.
5. Click Add when you are finished, or Cancel to dismiss the dialog without making
changes.
6. Click Save to store the changes made to the credential sharing group.
54.10 Managing Global Agent Settings
Global Agent Settings determine single sign-on behavior when users encounter
password-protected applications. With these settings you specify what the user sees
and is allowed to do when navigating to an application.
The next sections describe how to create new sets of Global Agent Settings or edit
existing sets. You can use existing sets created in the the Access Portal Service, or
Managing Global Agent Settings
54-60 Administrator's Guide for Oracle Access Management
import preconfigured settings in the format of INI files. After you create a set, the
process for configuring it is the same as that for editing an existing one.
54.10.1 Searching for Sets of Global Agent Settings
To search for an existing set:
1. Click Federation at the top of the Administrative Console, then click Global
Agent Settings in the Access Portal Service section.
2. Enter a name or partial string in the Name field, and click the Search button. The
results appear in the Search Results table.
3. Click on any group in the Search Results list to edit its configuration. Continue to
step 3 in Creating a Set of Global Agent Settings to learn more about configuring
these settings.
Figure 54–8 Global Agent Settings Search tab
54.10.2 Importing an INI File with a Global Agent Settings Configuration
To import an INI file (unicode format only):
1. Click the Import icon to launch the Import Global Agent Settings dialog, and
click the Browse button.
2. Navigate to an existing INI file, select it and click Open. Then click the Update
button. The Global Agent Settings' configuration page opens. Continue to step 3 in
Creating a Set of Global Agent Settings to learn more about configuring these
settings.
54.10.3 Creating a Set of Global Agent Settings
To create a new set:
Managing Global Agent Settings
Configuring the Access Portal Service 54-61
Figure 54–9 New Global Agent Settings Page
1. Click the Create Global Agent Settings button to launch the Create Global Agent
Settings page.
2. In the Name field, enter a name for the group. Optionally, you can add a
description of this set.
3. In the Credential Field Identification settings, specify the following:
–Whether to display a highlighted border around the credential fields of an
application during logon. The default is to show the border.
Managing Global Agent Settings
54-62 Administrator's Guide for Oracle Access Management
–The default border color/size/style for highlighting detected web page fields.
The default is a solid red border, six pixels in width.
Following is an example of the results of using the default settings for this
group.
4. In the Behavior settings, specify the following:
■URL Matching Precision. The number of levels of the host portion of the URL
used for application detection and response. Default is 2.
For example, for the URL
http://mail.company.co.uk
:
2=match to
*.co.uk
3=match to
*.company.co.uk
4=match to
*.mail.company.co.uk
■Scroll into View. Enables or disables scrolling the browser window to bring
the logon fields into view. Default is No.
This setting disables scrolling when the user has not yet stored credentials for
a Web application. Scrolling always occurs when injecting credentials into the
logon fields for an account that already exists.
5. In the Password Change Behavior settings, select a Default Password Policy from
the dropdown list, if desired. Default is None.
6. In the Response Control settings:
■Enter the list of Web pages to Ignore. This is typically used when the BHO
causes conflicts with specific Web applications or sites. Click the ellipsis ("…")
button to enter the regular expressions that match the URLs to be ignored (one
per line).
Examples:
–
.*http://login\.company\.com/.*
–
.*http://.*\.company\.com/.*
■Enter the list of Allowed Dynamic Web Pages. Use this setting to list the
permissible dynamic (DHTML) Web pages. By default, the BHO does not
detect changes made to a dynamic page after the initial presentation of the
page.
Examples:
–
.*http://login\.company\.com/.*
–
.*http://.*\.company\.com/.*
7. In the Allowed Character Sets settings, enter the permissible characters for each of
the four types of fields. The fields are pre-populated with the defaults for each
character set.
Note: Values less than 2 are treated as 2.
Managing Global Agent Settings
Configuring the Access Portal Service 54-63
8. In the Masked Fields Security settings, specify the following.
■Obfuscate Length. Specifies whether to display encrypted fields with a string
of blank characters different from the length of the obfuscated data. Default is
Yes.
■Allow Revealing. Specifies whether the user is permitted to reveal masked
fields. Default is Yes.
■Require Reauthentication to Reveal. Specifies whether the user must enter
the Access Portal Service credentials in order to reveal masked fields,
assuming that you have set Allow revealing to Yes. Default is Yes.
9. In the Authentication section, specify the naming attribute string for the target
data repository (if required by your environment). For more information, see the
Enterprise Single Sign-On Suite Administrator’s Guide.
10. Click Save to complete global agent setting configuration, or Cancel to close the
tab without saving the set.
Managing Global Agent Settings
54-64 Administrator's Guide for Oracle Access Management
Part XIV
Part XIV
Using Identity Context
This part introduces Oracle Identity Context.
Part X contains the following chapters:
■Chapter 55, "Using Identity Context"
55
Using Identity Context 55-1
55
Using Identity Context
Identity Context allows organizations to meet growing security threats by leveraging
the context-aware policy management and authorization capabilities built into the
Oracle Access Management platform. Identity Context secures access to resources
using traditional security controls (such as roles and groups) as well as dynamic data
established during authentication and authorization (such as authentication strength,
risk levels, device trust and the like). The following sections contain additional
information on Identity Context and how to use it.
■Introducing Identity Context
■Understanding Identity Context
■Working With the Identity Context Service
■Using the Identity Context API
■Configuring the Identity Context Service Components
■Validating Identity Context
55.1 Introducing Identity Context
Over the last decade, changes have been made to enterprise application infrastructures
in order to web-enable the business applications that these infrastructures support.
The changes allow for access by a greater number of users using different types of
devices. To compensate for the additional risk associated with the greater number of
users, the underlying security models used for access management have evolved from
a silo-based implementation to a more dynamic one in which identity and risk data is
shared across components of the entire application delivery process. This dynamic
implementation relies on systems that offer Web single sign-on (SSO), fine-grained
authorization, Web Services Security, Identity Federation and the like to aggregate
security controls within a particular run-time deployment environment (web server or
application server container) and provide policy-based security controls to manage
access to application resources. Additionally, the identity and risk data provides a
context for the user who is requesting access.
Initially, application security controls focused on unifying silos within a specific
enterprise application deployment paradigm (for example, all web server applications,
all web services applications, or all application server applications) but a growing
presence of external and internal security threats now requires the unification of
disparate security models in order to properly manage the greater amount of risk.
This requirement is further magnified by the advent of the cloud and mobile
computing paradigm in which applications are no longer made up of components
running neatly in the protected confines of a secure enterprise.
Introducing Identity Context
55-2 Administrator's Guide for Oracle Access Management
The ability of applications to leverage cloud services comes at the cost of having to
account for the greater amount of risk stemming from those services being silos in
their own way. With the number of threats to cloud deployments and mobile delivery
channels growing steadily, it is required for the end-to-end application delivery
process to implement the necessary policy controls for dealing with the greater range
of threats. These policy controls require access to information about the requesting
user on the basis of which security decisions must be made. Thus, a security policy
management infrastructure must be context-aware to allow for an Administrator to
create policy that controls the level of security imposed on a user who is requesting
access to a protected application environment.
Previously, Identity Context was defined by the presence of an identity record in one
or more identity stores (such as an LDAP directory or a SQL database). The identity
record includes profile attributes, groups of which the user is a member, and enterprise
roles. However, the constantly expanding reach of web, cloud, and mobile application
delivery channels requires authorization policy controls that are aware of more
dynamic information regarding the identity. This information is associated with the
identity attempting to access the protected resource and may include some or all of the
following:
■Presence (location, historical patterns)
■Authentication strength (weak, strong)
■Level of Assurance (NIST levels, X509 certificates)
■Risk Assessment (pattern analysis)
■Federation (partner attributes)
■Device characteristics (fingerprint, device health, device protection, trusted data)
■Assertions from trusted partners (SAML tokens, etc.)
■Single Sign On sessions (session time outs)
The following examples illustrate how Identity Context data might be used by an
application. The application might:
■Disable a particular business function if the user is not authenticated using a
strong credential such as smart card.
■Secure access to a transaction based on the identity data supplied by a business
partner (via Identity Federation) with whom the organization does business.
■Request additional authentication credentials if it detects that access is originating
from a location known for fraudulent activities.
■Limit the scope of administrative authority if the Administrator's industry
certification (as maintained by a third party) has expired.
■Disable certain business functions if it detects that access is originating from an
unknown device.
By incorporating the concept of Identity Context into access management, control can
now be determined using dynamic data that is not necessarily contained in an identity
profile (referred to as Identity Context attributes). In short, Identity Context is
considered the environment and circumstances surrounding a user's request to access
a particular protected resource. It can be a sphere of activity, a geographical region, a
communication platform, an application, or a logical or physical domain.
Understanding Identity Context
Using Identity Context 55-3
55.2 Understanding Identity Context
With this release, Access Manager enables context-aware access management by
incorporating Identity Context as a built-in service of the Oracle Access Management
platform. Figure 55–1 illustrates the flow of the Identity Context process, implemented
by multiple system components. Each application delivery component has its own
security policy infrastructure responsible for protecting its individual slice of the
application. This specific use case involves the end user device, a Web Server running
static GUI pages, an Application Server running the Portal Server rendering dynamic
content, a Service Bus Server exposing the Web service endpoint, a database server
containing transactional data, and an LDAP server containing identity profile data.
Figure 55–1 End to End Identity Context Process
Each component of the process has its own security infrastructure where the
authorization policies governing access to protected resources are defined
administratively and enforced at runtime. Additionally, some or all of the components
may have externalized policy management to an external authorization server such as
Oracle Entitlements Server - which is the case if the applications were built leveraging
Oracle Platform Security Services. Figure 55–2 illustrates the functional architecture of
Identity Context based on the Oracle applications of which it is comprised.
Figure 55–2 End To End Identity Context Process Components
As seen in the illustrations, context-aware security policy management is achieved by
leveraging the Oracle Access Management platform. This platform contains native
Working With the Identity Context Service
55-4 Administrator's Guide for Oracle Access Management
support for working with and enforcing Identity Context attributes (including risk
score, trusted device data, authentication data, and the like) without changing
end-user applications.
55.3 Working With the Identity Context Service
The Oracle Access Management platform enables Identity Context data to be collected,
propagated across the involved components (as defined in Figure 55–2), and made
available for granting or denying authorization to access protected resources. The
Identity Context Service allows access to the Identity Context Runtime through the
Identity Context API. The Identity Context Dictionary schema specifies the Identity
Context attributes. The following sections contain more information on these
components.
■Using the Identity Context Dictionary
■Understanding Identity Context Runtime
55.3.1 Using the Identity Context Dictionary
At the core of the Identity Context architecture is the Identity Context Dictionary. The
dictionary defines the Identity Context schema by specifying the identity context
attributes as defined by the Oracle Access Management platform. The Schema
describes each attribute with a unique name that equals namespace : attribute.
Table 55–1 documents the Schema attributes.
Note: Virtual attributes (as documented in Table 55–1) represent an
abstract class of identity information from which specific attributes are
created. When publishing virtual attributes, the Identity Context API
expects the attribute value to contain attr-name=attr-value. The actual
attribute will be created using the name namespace : attribute :
attr-name and a value of attr-value. This approach allows the
publication of attributes whose value comes from a source not directly
managed by the Oracle Access Management components.
Table 55–1 Identity Context Schema Attributes
Namespace Attribute Type Virtual
Primary
Publisher Description
oracle:idm:claims:n
ameid
value string no OAM Indicates a unique user identifier.
Access Manager currently
publishes User DN
oracle:idm:claims:n
ameid
format string no OAM Indicates the type of user
identifier. Access Manager
currently publishes
"urn:oasis:names:tc:SAML:1.1:nam
eid-format:x509SubjectName"
oracle:idm:claims:n
ameid
qualifier string no OAM Indicates a logical Identity
Domain to whom the user
belongs. Access Manager
currently publishes a logical name
of the identity store, such as
UserIdentityStore1.
Working With the Identity Context Service
Using Identity Context 55-5
oracle:idm:claims:n
ameid
spprovidedid string no OAM Indicates unique identifier that
can be used by any SP to locate
the user in SP's own identity
store(s). Access Manager currently
publishes the value of the unique
id attribute as configured in a
registered identity store.
oracle:idm:claims:c
lient
firewallenable
d
boolean no OESSO Indicates client device has firewall
enabled.
oracle:idm:claims:c
lient
antivirusenabl
ed
boolean no OESSO Indicates client device has
antivirus enabled.
oracle:idm:claims:c
lient
fingerprint string no OESSO,
Oracle
Access
Manageme
nt Mobile
and Social
(OMS)
Indicates fingerprint of the client
device.
oracle:idm:claims:c
lient
ostype string no OMS Indicates client device's Operating
System type.
oracle:idm:claims:c
lient
osversion string no OMS Indicates client device's operating
system version.
oracle:idm:claims:c
lient
jailbroken boolean no OMS Indicates if client device is
Jailbroken (iOS) or Rooted
(Android).
oracle:idm:claims:c
lient
macaddress string no OMS Indicates client device's Ethernet
(MAC) Address.
oracle:idm:claims:c
lient
ipaddress string no OMS Indicates client device's Client IP
Address.
oracle:idm:claims:c
lient
vpnenabled boolean no OMS Indicates if client's device has
VPN enabled.
oracle:idm:claims:c
lient
geolocation string no OMS Indicates client device location's
geographical coordinates in the
form of "latitude,longitude.
oracle:idm:claims:ri
sk
newdevice boolean no OAAM Indicates if the client device has
been seen before. True when
logging in from a device never
seen before; otherwise, false.
oracle:idm:claims:ri
sk
level integer no OAAM Indicates risk level. Level
increases after unsuccessful logins.
oracle:idm:claims:ri
sk
safeforuser boolean no OAAM Indicates if the user answered a
secondary challenge question.
True after the user successfully
answers it; otherwise false.
oracle:idm:claims:ri
sk
fingerprint string no OAAM Indicates device fingerprint as
measured by OAAM. Different
devices will leave different
fingerprints; can be switched
between device (obtained via
Flash) fingerprint and browser
(http-only) fingerprint
oracle:idm:claims:s
ession
authnlevel integer no OAM Indicates authentication level for
Access Manager
oracle:idm:claims:s
ession
usercount integer no OAM Indicates number of sessions held
by the users
Table 55–1 (Cont.) Identity Context Schema Attributes
Namespace Attribute Type Virtual
Primary
Publisher Description
Working With the Identity Context Service
55-6 Administrator's Guide for Oracle Access Management
oracle:idm:claims:s
ession
appdomain string no OAM Indicates name of the Access
Manager Application Domain
containing policies
oracle:idm:claims:s
ession
apppolicy string no OAM Indicates name of the Access
Manager policy that allowed
access
oracle:idm:claims:s
ession
appagent string no OAM Indicates the name of the agent
from which the request came to
Access Manager
oracle:idm:claims:s
ession
appclientip string no OAM Indicates the IP address of the
client sending the request to
Access Manager
oracle:idm:claims:s
ession
sessionid string no OAM Indicates the Access Manager
session ID
oracle:idm:claims:s
ession
attributes string yes OAM Indicates session attributes as
retrieved from the session store.
For example, in Access Manager,
select
"oracle:idm:claims:session:attribut
es" as the claim name and then
specify the session attribute using
the following notation:
"attr-name=$session.attr.name
where name is the name of the
attribute stored in the session. The
claim will be created with the
name of
"oracle:idm:claims:session:attribut
es:attr-name" and value equal to
session's name attribute.
oracle:idm:claims:f
ed
partner string no OAM--or
IF?
Indicates partner ID as
determined by Identity Federation
oracle:idm:claims:f
ed
nameidvalue string no OAM--or
IF?
Indicates user ID from a
federation partner as determined
by Identity Federation
oracle:idm:claims:f
ed
nameidformat string no OAM--or
IF?
Indicates format of the user ID
from a federation partner as
determined by Identity Federation
oracle:idm:claims:f
ed
attributes string yes OAM Indicates federation attribute as
supplied by the partner and
determined by Identity
Federation. For example, in Access
Manager, select
"oracle:idm:claims:fed:attributes"
as the claim name and then
specify the federation attribute
using the following notation:
"attr-name=$session.attr.fed.attr.na
me, where name is the name of the
SAML attribute in the partner's
SAML assertion. The claim will be
created with the name of
"oracle:idm:claims:fed:attributes:at
tr-name" and value equal to the
partner's assertion provided in the
SAML's name attribute.
Table 55–1 (Cont.) Identity Context Schema Attributes
Namespace Attribute Type Virtual
Primary
Publisher Description
Working With the Identity Context Service
Using Identity Context 55-7
55.3.2 Understanding Identity Context Runtime
Identity Context Runtime refers to a collection of Identity Context attributes (as
defined in the Identity Context Dictionary) that is asserted by various trusted
application components and/or security frameworks known to be authoritative for the
attributes; this is the Oracle Access Management platform. Runtime context represents
current surroundings, circumstances, environment, background, or settings which
determine, specify, or clarify the meaning of an event for an identity in the runtime
application environment.
The Oracle Access Management platform leverages a common infrastructure
component called the Context Management Engine (CME). CME ensures that an
Identity Context is generated for every transaction that is processed through the
Oracle Access Management platform. The context data gathered by CME applies to
transactions a user performs over the web channel or web service channel and using
many of the software products available in the Oracle Access Management platform.
Some transactions that are initiated on the back end may also require access to Identity
Context, and may require Identity Context to be persisted for some duration of time.
In a typical Oracle middleware deployment the Identity Context Runtime will be
utilized primarily by the Oracle Access Management platform to perform policy-based
decisions on behalf of protected applications. However, it is also possible for any
applications running in the container to directly integrate with, and consume, the
Identity Context Runtime by leveraging the Identity Context API. The amount of
available Identity Context data will vary depending on what products have been
deployed. There will be a default set of Identity Attributes that will be available out-of
the box, which are mainly configured in the Access Manager by leveraging the
Identity Assertion. Table 55–1, " Identity Context Schema Attributes" documents these
default attributes. The following list provides details on the end-to-end flow of the
Identity Context Runtime. Figure 55–3 below the list illustrates the flow.
Process overview: End-to-end flow of the Identity Context Runtime
1. User accesses a protected application from a device.
oracle:idm:claims:i
ds
attributes string yes OAM For example, in Access Manager,
select
"oracle:idm:claims:ids:attributes"
as the claim name, and then
specify the ID Store attribute
using the following notation:
"attr-name=$user.attr.name where
name is the name of the attribute
on the user profile. The claim will
be created with the name of
"oracle:idm:claims:ids:attributes:at
tr-name" and value equal to user
profile's name attribute.
oracle:idm:claims:t
enant
tenantid string no OAM Currently reserved for future use.
(Indicates tenant id.)
oracle:idm:claims:t
enant
attributes string yes OAM Currently reserved for future use.
(Indicates tenant attributes as
supplied by the Publisher. The
claim value is meant to contain
"attr-name=attr-value". The claim
will be created with the name of
"oracle.idm:claims:tenant:attr-nam
e" and value of attr-value.)
Table 55–1 (Cont.) Identity Context Schema Attributes
Namespace Attribute Type Virtual
Primary
Publisher Description
Working With the Identity Context Service
55-8 Administrator's Guide for Oracle Access Management
2. Access Manager asserts the identity, collects Identity Attributes from the
participating Access Management publishing components and creates an Identity
Context.
3. Access Manager generates an Identity Assertion (a SAML Session token) and
incorporates the Identity Context attributes. The Access Manager Identity Asserter
processes the Identity Assertion and publishes the Identity Context to the
WebLogic Server container using the OPSS Attribute Service.
4. The protected application calls the OES PEP API to make an authorization
decision. OES automatically propagates the Identity Context to the local OES PDP.
5. OES finds the appropriate Authorization Policy and evaluates it's Conditions
(based on the Identity Context attributes). Evaluation can be done using a built-in
Identity Context function or a custom function.
6. The protected application makes a JRF web service call in which the Oracle Web
Service Manager (OWSM) client uses the SAML token to propagate Identity
Context into the Web Service application environment.
7. OWSM (on the web service side) processes the SAML assertion with the Identity
Context and publishes the Identity Context to the WebLogic Server container by
using the OPSS Attribute Service.
8. Web Service application calls OES PEP API to make an authorization decision.
9. OES automatically propagates Identity Context to the remote OES PDP where
conditions based on Identity Context attributes are evaluated using a built-in
Identity Context function or a custom function.
Figure 55–3 Identity Context Process Flow
Once CME propagates Identity Context into the application tier and underlying
Application Server container, the Identity Context is then made available to the
container and applications running in it. Table 55–2 documents which Access
Management platform products do what when working with Identity Context.
Using the Identity Context API
Using Identity Context 55-9
55.4 Using the Identity Context API
The Identity Context API is a set of Java classes designed to work with the Identity
Context Dictionary and Identity Context Runtime. The API is delivered as
IdentityContext.jar
, a part of Oracle Java Required Files (JRF). Example 55–1
illustrates an application working with Identity Context Dictionary.
Example 55–1 Working with Identity Context Dictionary
// Display Identity Context Dictionary
try {
ClaimDictionary idCtxDict = new ClaimDictionary();
System.out.println
("IDC Dictionary :" + idCtxDict.getClaimCount() + "attributes");
Iterator<String> iterNamespace = idCtxDict.getAllNamespaces();
while (iterNamespace != null && iterNamespace.hasNext()) {
String namespace = iterNamespace.next();
System.out.println("Namespace : " + namespace);
Iterator<ClaimSchema>
Table 55–2 Mapping Identity Context Operations
Role and Context
Operation Description Components
Publisher - publishes
Identity Context
Trusted security framework protecting an
application component obtains from another
trusted security framework, or derives from the
information available to it, suitable facts about
the identity and/or identity's access request.
The information collected by the authoritative
component is based on the environmental context
available to component's runtime framework. For
example, Access Manager determines the user's
level of authentication strength, OAAM
computes the risk score associated with a specific
online session, and OESSO determines whether
or not the client device has a firewall enabled.
■OAM – Session,
Federation, and identity
store attributes
■OAAM – Risk attributes
■OESSO – Device attributes
■OMS Mobile SDK - Device
attributes
Propagator -
propagates Identity
Context
Trusted security framework propagates Identity
Context attributes for use by another application
security framework or directly by the application.
For example, OAAM propagates user's risk score
into the Access Manager session for the user,
Access Manager propagates Identity Assertion
(SAML token) for with the authenticated user's
unique id and authentication level, and OWSM
client propagates the current Identity Context
over to the web service where OWSM agent will
rebuild Identity Context in the web service
application.
■OAM is between Web tier
and container tier
■OWSM is between web
service client tier and web
service tier
■OPSS is between Access
Manager Identity Asserter
or OWSM agent and
WebLogic Server container
■OMS is between the OMS
Mobile SDK and Access
Manager
Evaluators -
evaluate Identity
Context
Trusted security framework or end-user
application using Identity Context attributes to
perform policy decisions or personalize
application business logic. For example, when
OAAM is present and configured to compute the
risk score, the application's authorization policy
in OES allows access only when the risk score is
under a certain threshold. Also, when Identity
Federation in Access Manager is configured, the
application uses a partner-supplied assertion
(available in the Identity Context) to authorize
access to a transaction using OES.
■OAM – Web Perimeter
Policy
■OWSM – Web Service
policy
■OES – App-specific or
WLS-specific policy for all
PEP API calls made from
the container where
Identity Context exists.
This includes all ADF apps,
IAM apps, custom apps,
etc.
Using the Identity Context API
55-10 Administrator's Guide for Oracle Access Management
iterClaimSchema=idCtxDict.getClaimsForNamespace(namespace);
while (iterClaimSchema != null && iterClaimSchema.hasNext()) {
out.println(iterClaimSchema.next().getUniqueName());
}
}
} catch (Exception e) {
System.out.println("Unable to acquire IDC Dictionary. " + toString());
}
Applications work with the Identity Context Runtime to obtain the runtime state of
the Identity Context as it currently exists in the application infrastructure. In order to
work with the Identity Context Runtime, the protected application must be deployed
to either a WebLogic Server domain built on Oracle Fusion Middleware PS5 with the
OPSS Opatch for PS5, or Oracle Fusion Middleware PS6 or later.
Additionally, working with the Identity Context Runtime is a privileged operation that
requires applications running in the WebLogic Server (with the required Identity
Context support) to have proper source code grants. The privileged application,
running in the WebLogic Server container, can then access the Identity Context
Runtime by requesting it from the OPSS Attribute Service. Example 55–2 demonstrates
how to use WLST to grant the OPSS Attribute Service permission to access an
application (in this case,
ssofilter.jar
).
Example 55–2 Using WLST To Grant Attribute Service Access To Application
# sh ../oracle_common/common/bin/wlst.sh
connect ('<username>', '<password>','t3://localhost:7001')
grantPermission(codeBaseURL="file:${common.components.home}/
modules/oracle.ssofilter_11.1.1/ssofilter.jar",
permClass="oracle.security.jps.service.attribute.AttributeAccessPermission",
permTarget="*", permActions="get, set, remove")
exit()
Example 55–3 illustrates an application working with Identity Context Runtime.
Example 55–3 Working with Identity Context Runtime
import java.security.AccessController;
import java.security.PrivilegedAction;
import oracle.security.jps.internal.api.runtime.AppSecurityContext;
import oracle.security.idm.IdentityContext;
…
// get runtime ID Context from OPSS
private static Object getIDContext() {
Object idc = AccessController.doPrivileged(new PrivilegedAction<Object>() {
public Object run() {return
AppSecurityContext.getSecurityContext().getAttribute
(oracle.security.idm.IdentityContext.Constants.IDC_API_ID); }});
return idc;
}
…
// Display runtime ID Context
try {
Context idCtx = (Context)getIDContext();
if (idCtx != null) {
System.out.println("IDC Runtime :" + idCtx.getSize() + "attributes");
Configuring the Identity Context Service Components
Using Identity Context 55-11
Iterator<Claim> i = idCtx.getClaims();
while (i != null && i.hasNext()) {
Claim c = i.next();
System.out.println(c.getName() + " : " + c.getValue());
}
} else {
System.out.println("Identity Context Runtime is not available");
}
} catch (Exception e) {
System.out.println("Unable to acquire Identity Context Runtime. " +
e.toString());
}
…
// Obtain few attributes from Identity Context Runtime
Attr authnLevel = ctx.getAttr (Constants.ATTR_SESSION_AUTHN_LEVEL);
Attr isFirewallEnabled = ctx.getAttr(Constants.ATTR_CLIENT_FIREWALL_ENABLED);
Attr isTrustedDevice = ctx.getAttr(Constants.ATTR_RISK_TRUSTED_DEVICE);
// Use user's authentication strength established at login by OAM
int authLevel = new Integer(authnLevel.getValue()).intValue();
if (authLevel < 20) {
// do something
}
More information can be found in the Oracle Fusion Middleware Java API Reference for
Oracle Platform Security Services.
55.5 Configuring the Identity Context Service Components
Support for Identity Context is pre-integrated into each participating Oracle Access
Management component listed in Table 55–2, " Mapping Identity Context Operations".
Because of this, each component must be configured to accommodate business
requirements.
The following sections provide a high level overview of the necessary Identity Context
configurations. However, detailed information can be found in documentation
accompanying individual products.
■Configuring Oracle Fusion Middleware
■Configuring Access Manager
■Configuring Oracle Adaptive Access Manager
■Configuring Web Service Security Manager
■Configuring Oracle Entitlements Server
■Configuring Oracle Enterprise Single Sign On
■Configuring Oracle Access Management Mobile and Social
55.5.1 Configuring Oracle Fusion Middleware
The application to be protected must be deployed in a WebLogic Server domain built
on Oracle Fusion Middleware 11.1.1 patch set 5 (PS5) with the Oracle Platform
Security Services (OPSS) Opatch for PS5 or, Oracle Fusion Middleware PS6 or later.
The WebLogic Server domain in which the application is running must be protected by
the Access Manager Identity Asserter component that will validate the Identity
Configuring the Identity Context Service Components
55-12 Administrator's Guide for Oracle Access Management
Assertion received from Access Manager and start the process of creating the Identity
Context Runtime. The Access Manager Identity Asserter must be configured to detect
the token type, OAM_IDENTITY_ASSERTION. Also, the protected application
working with the Identity Context Runtime directly must be granted source code
grants to work with the OPSS Attribute Service (as in Example 55–2).
55.5.2 Configuring Access Manager
As the main publisher and propagator of Identity Context, OAM serves as the central
configuration point for collecting Identity Context data from its participating
components. The following sections describe key elements of the architecture behind
Identity Context management.
■Configuring Identity Assertion
■Configuring Federation Attributes
■Configuring Session Attributes
■Configuring Identity Store Attributes
55.5.2.1 Configuring Identity Assertion
Oracle recommends that you define Asserted Attributes in Access Manager
Authorization policies for proper enforcement of end-to-end security between the Web
and application tiers.
In addition to ensuring trust between the WebGate protecting a Web resource and the
Application Server container, Identity Assertion (a SAML Session token) is used to
publish the Identity Context data as SAML attributes.
Identity Assertion must be enabled and populated with Asserted Attributes as
required by the business logic expecting specific attributes in the Identity Context. It is
configured within the OAM Policy Responses tab and can be defined for both
Authentication and Authorization policies.
55.5.2.2 Configuring Federation Attributes
Once a resource is protected by the Access Manager authentication scheme
FederationScheme, Access Manager will act as the service provider and receive the
SAML assertion as provided by the federation partner. After the federation single sign
on (SSO) operation, the following attributes will be present in the authenticated
identity's Access Manager session:
■
$session.attr.fed.partner
(contains the partner name)
■
$session.attr.fed.nameidvalue
(contains the SAML NameID Value)
■
$session.attr.fed.nameidformat
(contains the SAML NameID Format)
■one
$session.attr.fed.attr.
name entry per SAML Attribute (contained in the
SAML Assertion received from the partner)
These federation attributes can be used in configuring an Identity Assertion by
selecting
oracle:idm:claims:fed:attributes
as the Asserted Attribute, and
See Also: Oracle Fusion Middleware Application Security Guide for
more information on configuring Access Manager Identity Asserter, as
well a source code grants.
See Also: Access Manager Identity Assertion and Asserted
Attributes (Table 25–25).
Configuring the Identity Context Service Components
Using Identity Context 55-13
setting the value to "attr-name
=$session.attr.fed.attr.
name" where attr-name is
the name given to the Identity Context attribute and name is the name of the
SAML attribute in the partner's SAML assertion.
For example, defining
oracle:idm:claims:fed:attributes
with the value of
partner-role=$session.attr.fed.attr.role
will result in the creation of the
Identity Context attribute
oracle:idm:claims:fed:attributes:partner-role
having a value of "manager" (assuming
$session.attr.fed.attr.role
contains
"manager" as specified in the partner's SAML assertion for the SAML attribute
"role").
55.5.2.3 Configuring Session Attributes
Access Manager session attributes can be used in configuring Identity Assertion by
selecting
oracle:idm:claims:session:attributes
as the Asserted Attribute and
setting the value to "attr-name=$session.attr.name" where attr-name is the name given to
Identity Context attribute and name is the name of the Access Manager session
attribute.
For example, defining
oracle:idm:claims:session:attributes
with the value of
authn-strength=$session.attr.authnlevel
will result in the creation of the Identity
Context attribute
oracle:idm:claims:session:attributes:authn-strength
having a
value as defined by the authentication scheme used during the login process.
55.5.2.4 Configuring Identity Store Attributes
Identity Store attributes can be used to configure an Access Manager Identity
Assertion by selecting
oracle:idm:claims:ids:attributes
as the Asserted Attribute
and setting the value to "attr-name=
$user.attr
.name" where attr-name is the name
given to the Identity Context attribute and name is the name of the Identity Store
attribute.
For example, defining
oracle:idm:claims:ids:attributes
with the value of
first-name=$user.attr.fname
will result in the creation of the Identity Context
attribute
oracle:idm:claims:ids:attributes:first-name
having a value from the
user's
fname
attribute as maintained in the identity store.
55.5.3 Configuring Oracle Adaptive Access Manager
As part of the integration between Oracle Access Manager and Oracle Adaptive
Access Manager (OAAM), OAAM publishes and propagates risk-based Identity
Context attributes. In this case, OAAM attributes are passed to OAM at the end of user
authentication flow (on the OAAM side) in a DAP Token. The DAP Token will carry
attributes as defined by the oracle:idm:claims:risk namespace in Table 55–1, " Identity
Context Schema Attributes". OAM then pushes these attributes into the
$session.risk.attr namespace. The following sections contain information regarding
configuration of OAAM and OAM.
■Setting Up Oracle Adaptive Access Manager
■Configuring Access Manager for OAAM Integration
■Validating Identity Context Data Published by OAAM
55.5.3.1 Setting Up Oracle Adaptive Access Manager
This section contains information on installing and setting up OAAM.
Configuring the Identity Context Service Components
55-14 Administrator's Guide for Oracle Access Management
To setup Oracle Adaptive Access Manager
1. Set up OAAM by importing snapshots.
See Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access
Manager for details.
2. Integrate OAAM and Access Manager as documented in the Oracle Fusion
Middleware Integration Guide for Oracle Access Manager.
The TAP token version must be v2.1 and not v2.0.
3. Ensure that the following properties are set to true.
■
oracle.oaam.idcontext.enabled
is true by default; use the OAAM
Administration Console to change the value.
■
bharosa.uio.default.registerdevice.enabled
must be true for proper
operation of the 'safeforuser' claim.
4. From the OAAM Administration Console, go to Properties, Create New Property.
5. Enter the property name
oaam.uio.oam.dap_token.version
with a value equal to
v2.1
.
6. Restart oaam_server_server1.
55.5.3.2 Configuring Access Manager for OAAM Integration
Perform the following steps. Using the TAPScheme forces the user to authenticate
using the OAAM authentication schemes.
To configure Access Manager for Integration with OAAM Integration
1. Protect a resource (Defining Authentication Policies for Specific Resources on
page 25-31) using the TAPScheme for authentication (Table 22–21).
2. Add the following challenge parameter to the TAPScheme (Table 22–22):
TAPOverrideResource=http://IAMSuiteAgent:80/oamTAPAuthenticate
55.5.3.3 Validating Identity Context Data Published by OAAM
The following information describes how you might validate Identity Context data
published by OAAM.
■
oracle:idm:claims:risk:newdevice
will be true after a login from a new device;
false otherwise.
■
oracle:idm:claims:risk:level
will have a high value after a couple of
unsuccessful logins followed by a successful login. To test for this, try a few
unsuccessful logins and then a successful one.
■
oracle:idm:claims:risk:safeforuser
will have true after a user successfully
answers the challenge question.
■
oracle:idm:claims:risk:fingerprint
contains the user's device's fingerprint. By
default, the fingerprint built out of HTTP header data is used; if that is not
available, fingerprint data built out of Flash will be used. To test for different
fingerprints, try different devices.
Note: Do not use OAAM Advanced or OAAM Basic.
Configuring the Identity Context Service Components
Using Identity Context 55-15
55.5.4 Configuring Web Service Security Manager
Do the following to enable Oracle Web Service Security Manager (OWSSM) to
propagate Identity Context.
To configure Web Service Security Manager for Identity Context
1. Configure Security Policy by modifying the Identity Context supported OWSSM
security policies to contain the
propagate.identity.context
element with a value
of true.
2. Configure the Keystore and Credential Store to sign the SAML assertion and
messages: copy the updated Keystore and Credential Store to your
$DOMAIN_
HOME/config/fmwconfig/
directory.
55.5.5 Configuring Oracle Entitlements Server
Runtime integration with Oracle Entitlements Server (OES) is fully automated. When
an application invokes the PEP API to make an authorization call, the PEP API
automatically propagates the entire Identity Context Runtime to the OES PDP where
Conditions (the policy objects that define the Identity Context) are evaluated.
Conditions are built, based on the Identity Context schema, by a security
Administrator using the OES Administration Console. The following built-in functions
are used to specify Conditions using Identity Context attributes:
■ASSERT_IDENTITY_CONTEXT
■GET_STRING_IDENTITY_CONTEXT
■GET_INTEGER_IDENTITY_CONTEXT
■GET_BOOLEAN_IDENTITY_CONTEXT
Custom OES functions receive the full Identity Context Runtime information as a
well-known request attribute. This data structure can be converted into Identity
Context Runtime using the Identity Context API. Example 55–4 shows a custom OES
function creating a context from the received parameter.
Example 55–4 Custom Function Creating Identity Context
public OpssString GET_STRING_IDENTITY_CONTEXT_V2 (
Note: propagate.identity.context (by default, false) is a configuration
override property on SAML related policies. To enable it globally,
configure a global policy with the property set to true.
Note: When making authorization calls, ensure that the last
argument passed into the
newPepRequest()
method is not null, and is
at least an empty hashmap as shown in this example:
PepRequestFactory requestFactory =
PepRequestFactoryImpl.getPepRequestFactory();
PepRequest request = requestFactory.newPepRequest (subject,
action, resource, new HashMap<String, Object>());
PepResponse response = request.decide();
boolean isAuthorized = response.allowed();
Configuring the Identity Context Service Components
55-16 Administrator's Guide for Oracle Access Management
RequestHandle requestHandle,
Object[] args,
Subject subject,
Map roles,
Resource resource,
ContextHandler contextHandler) throws RuntimeException {
// Obtain string representation of the runtime ID Context from the request handle.
Context runtimeCtx = null;
try {
AttributeElement ctxAttr = requestHandle.getAttribute
(Constants.IDM_IDC_API_ID, false);
if (ctxAttr != null) {
String ctxStr = (String) ctxAttr.getValue();
runtimeCtx = new Context(ctxStr);
} else {
throw new RuntimeException ("Unable to acquire ID Context from request
handle");
}
} catch (Exception e) {
throw new RuntimeException (e.toString());
}
…
// start using Context which now contains the same exact Identity Context Runtime
as was present in the application that made the PEP API call
…
}
55.5.6 Configuring Oracle Enterprise Single Sign On
As part of the Identity Context Service, Oracle Enterprise Single Sign-on (OESSO) can
publish and propagate client-based Identity Context attributes. Once full integration
has been configured, client-specific Identity Context attributes (as documented in
Section 55.3.1, "Using the Identity Context Dictionary") will be sent by OESSO to OAM
in the session initiation request together with the user credentials submitted in the
access request.
After the request has been received, OESSO makes a call to an SSL-protected OAM
REST API (previously configured by the OESSO Administrator and included as part of
the OESSO client distribution). This API returns the OAM_ID cookie to OESSO.
OESSO then propagates the valid OAM_ID cookie to the client browsers (Internet
Explorer and Firefox) which enables OESSO resources to be protected and enables
single sign-on (SSO) with those resources that are protected by the OAM Embedded
Credential Collector. (This does not include resources that are protected by the
Distributed Credential Collector.) OESSO then provides OAM credentials that are
acceptable to the OAM Embedded Credential Collector as well as client context
information in the payload.
Note: The payload is secured by:
■Generating a 16 byte Random Salt
■Generating a SHA-256 Hash using the 16 Byte Random Salt
■Encrypting the claims using the OAM password protected by
OESSO
Configuring the Identity Context Service Components
Using Identity Context 55-17
To configure OESSO to get attributes for Identity Context
1. Refer to "Installing Logon Manager Client-Side Software" in the Oracle Enterprise
Single Sign-On Suite Plus Installation Guide for details on integrating OAM and
OESSO.
2. See additional details in the Oracle Enterprise Single Sign-On Suite Plus
Administrator's Guide section "Oracle Access Management Support in Logon
Manager".
55.5.7 Configuring Oracle Access Management Mobile and Social
Oracle Access Management Mobile and Social (Mobile and Social) provides
REST-based authentication services, in addition to a user profile service and an
authorization service, for mobile and desktop devices. When Mobile and Social is
configured to provide authentication using Access Manager, it can publish Identity
Context attributes provided by the mobile client to Access Manager. The Identity
Context attributes are published by the Mobile and Social SDK for iOS and Java
platforms.
Mobile applications use the Mobile and Social SDK to access and use services
provided by the Mobile and Social server. When a mobile application uses the iOS or
Android API to perform authentication, it captures the Identity Context attributes and
publishes the data to the Mobile and Social server which, in turn, publishes the
attributes to the Access Manager server. The Administrator can configure the Mobile
and Social server to get all the attributes or only the required ones.
The Administrator configures the Identity Context attributes to be sent by the
application in the Application Profile configuration page of the Mobile and Social
accordion under the System Configuration tab in the Access Manager Administration
Console.
The Mobile and Social server passes the required Identity Context attributes to the
Mobile and Social SDK when it contacts the server for the application profile. (An
application profile has information regarding the type of authentication to be
performed as well as the Identity Context attributes to be collected.) The SDK collects
the attributes, if allowed by the user or the platform, and publishes them to the Mobile
and Social server as part of the authentication request.
To configure the Mobile and Social server to publish the attributes collected from the
Mobile and Social SDK to the user session created on and maintained by the OAM
Server, the administrator must configure Mobile and Social server to enable ID
Context, as illustrated in Figure 55–4.
Note: Some mobile platforms (iOS, for example) forbid applications
from collecting certain device attributes (for example, the UDID or
IMEI device number). The user can also deny an application from
getting a location update. Thus, even if the server requests attributes,
it is not guaranteed that all of them can be collected by the SDK.
Validating Identity Context
55-18 Administrator's Guide for Oracle Access Management
Figure 55–4 OAM Authentication Provider Configuration
To configure Mobile and Social to get attributes for Identity Context
1. Confirm that the Mobile and Social Service is enabled as described in "Enabling or
Disabling Available Services" on page 3-3.
2. On the
MobileOAMAuthentication
Service Provider page, add the
IDContextEnabled
Attribute with the value of
true
.
55.6 Validating Identity Context
Use the following procedure to ensure correct operation of the Identity Context with
Access Manager.
See Also:
■Chapter 49, "Configuring Mobile and Social Services" for full
configuration details
■Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details on how to develop applications using the
iOS SDK
Validating Identity Context
Using Identity Context 55-19
To validate your Identity Context operations
1. Perform the following to validate the Identity Assertion response that Access
Manager is constructing.
a. Configure Access Manager to protect the
/testidc
resource with a WebGate
agent and return the Identity Assertion with the desired Asserted Attributes
as part of the Authorization response.
b. Use the OAM Tester to validate that the Identity Assertion is returned as an
OAM_IDENTITY_ASSERTION attribute in response to the authorization
request for /testidc.
2. Perform the following to validate that WebGate is creating an HTTP header that
contains the Identity Assertion.
a. Ensure the
/cgi-bin/printenv.pl
script is protected by the same policy that
protects the /testidc resource.
b. Access the
printenv.pl
to trigger a login and display the HTTP headers.
c. Ensure that the HTTP_OAM_IDENTITY_ASSERTION header contains a
SAML token with Asserted Attributes.
Note:
printenv.pl
ships as part of OHS and must have permission
to execute. Any script to display header information can be used
instead.
Validating Identity Context
55-20 Administrator's Guide for Oracle Access Management
Part XV
Part XV
Integrating Access Manager with Other
Products
Part XI describes how to integrate Access Manager with products from other vendors.
Part XI contains the following chapters:
■Chapter 56, "Integrating RSA SecurID Authentication with Access Manager"
■Chapter 57, "Configuring Access Manager for Windows Native Authentication"
■Chapter 58, "Integrating JBoss with Access Manager"
■Chapter 59, "Integrating Microsoft SharePoint Server with Access Manager"
■Chapter 60, "Integrating Access Manager with Outlook Web Application"
■Chapter 61, "Integrating Microsoft Forefront Threat Management Gateway 2010
with Access Manager"
■Chapter 62, "Integrating Access Manager with SAP NetWeaver Enterprise Portal"
■Chapter 63, "Integrating Oracle Access Manager with SAP NetWeaver Enterprise
Portal Using OpenSSO Policy Agent 2.2"
56
Integrating RSA SecurID Authentication with Access Manager 56-1
56
Integrating RSA SecurID Authentication with
Access Manager
[37]
Oracle provides components that interface with RSA Security products to provide
native RSA SecurID® authentication for Access Manager protected resources.
This chapter introduces SecurID authentication and the components, requirements,
and processes needed to successfully integrate SecurID authentication with Access
Manager 11.1.2. The following topics are included:
■Introduction to Access Manager and RSA SecurID Authentication
■Components Required for SecurID Authentication
■SecurID Authentication Modes
■Configuring Access Manager for RSA SecurID Authentication
■Running a Custom RSA Plug-in
56.1 Introduction to Access Manager and RSA SecurID Authentication
Access Manager 11.1.2 integrates with RSA components to provide SecurID
authentication. RSA SecurID authentication is based on two factors: something the
user knows and something the user has:
■Something the User Knows: This is a secret personal identification number (PIN),
similar in concept to a personal bank code PIN. In this case, the PIN may be
system generated or personally chosen and registered with the RSA
Authentication Manager.
■Something the User Has: This is the current code generated by a hand held device
known as a token. Oracle Access Manager supports all RSA SecurID token form
factors, both hardware and software-based.
These tokens algorithmically, based on an internal clock or event, generate tokencodes
with unpredictable values. Together, the user's PIN and the SecurID tokencode become
the user's Passcode.
Access Manager uses and supports RSA two-factor SecurID authentication security
features and enables integration with SecurID authentication by providing:
■The HTML forms required for SecurID authentication operations
■The RSA SecurID Plugin you can use with the User Identification Plugin to create
and orchestrate authentication
Access Manager integrates with RSA Authentication Manager and provides the
integration features described in Table 56–1.
Introduction to Access Manager and RSA SecurID Authentication
56-2 Administrator's Guide for Oracle Access Management
Access Manager does not support the RSA features in Table 56–2.
Table 56–1 Access Manager Support for RSA Features
RSA Feature Access Manager Support
Authentication method Native SecurID authentication
New PIN Mode (user-generated PINs) Asks for new PIN with confirmation.
The token may be in New PIN mode the first time the user logs in
or the Authentication Manager Administrator can enable New
PIN mode. New PIN mode requires the user to complete a
sequence of forms to define, or have the system generate, a new
PIN number.
Oracle-Provided New PIN Forms and Functions:
■System Generated PIN (not supported)
■User Defined (4-8 Alpha/numeric characters)
■User Defined (5-7 Numeric)
■Deny 4 and 8 Digit PIN
■Deny Alphanumeric PIN
■Deny Numeric PIN
■PIN Reuse
See Also: "SecurID New PIN Authentication" on page 56-6.
Next Tokencode During authentication, the Authentication Manager may direct
the user to provide the next tokencode that appears on their
SecurID token to prove that they have the assigned token. This
operation is known as Next Tokencode mode, which can be
triggered by one of the following situations:
See Also: "SecurID Next Tokencode Authentication". on
page 56-6.
Passcode ■16 Digit Passcode
■4 Digit Fixed Passcode
Load Balancing RSA Authentication Manager Replicas.
Secondary server support Yes
SecurID user specification Designated users
SecurID protection of Administrators Yes
Access Manager features and functions All
Table 56–2 RSA Features Not Supported
RSA Feature Not supported by Access Manager
RSA Authentication
Manager 7.1 SP2
Is not supported in an Active Directory Forest multi-domain environment
Multiple ACE Realms The RSA Authentication API uses an automatic response time load balancing
algorithm to determine where to send an authentication request. Such requests
go to either a primary RSA Authentication Manager or a replica. The
automatic algorithm can be overridden by creating a manual load balancing
configuration file, sdopts.rec. However manually weighting an RSA
Authentication Manager as a server of last resort does not preclude the Agent
from communicating with it. As such, a true failover setup cannot be achieved
with this method. For more information, see your RSA Authentication
Manager documentation
System Generated PINs Not supported by Access Manager.
Failover Not supported for OAM SecurID Servers because only one OAM SecurID
Server can perform SecurID authentication.
Components Required for SecurID Authentication
Integrating RSA SecurID Authentication with Access Manager 56-3
56.2 Components Required for SecurID Authentication
The following components are needed for the integration:
■Supported Versions and Platforms
■Required RSA Components
■Installation and Configuration Requirements
56.2.1 Supported Versions and Platforms
For the latest support information, see the Oracle Technology Network (OTN). You
must register with OTN to view this information.
The certification matrix provides platform and version support for this integration,
which includes RSA Authentication Manager v7.x and the SecurID Authentication
API:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
56.2.2 Required RSA Components
The following RSA components are required for integrating Access Manager and
SecurID Authentication.
■RSA Authentication Manager
■RSA SecurID Tokens
56.2.2.1 RSA Authentication Manager
Residing somewhere in your network are records of users, agents, tokens, and user's
PINs. Portions of these records might reside in the Authentication Manager or in
LDAP directories. During authentication, Authentication Manager compares these
records to the information it receives when a user attempts to access the network. If
the records and tokencode or passcode match, the user is granted access.
56.2.2.2 RSA SecurID Tokens
An RSA SecurID token is either a hardware device or software-based security token
that generates and displays a random number that enables users to securely access
protected resources. The random number is called a tokencode. Before a user can
authenticate with a token, the token must be recognized by Authentication Manager.
RSA, or your vendor, ships a token seed file that you must import into the data store.
Seeds listed in this file are assigned to tokens for generating the tokencode when an
authentication request is received from an Authentication Manager agent.
During the SecurID authentication process, users must submit their username and
passcode using an HTML form. The RSA Authentication Manager authenticates the
identity of each user through a server that is registered with the Authentication
Manager as a client (RSA Authentication Agent). One Access Server (known as the
Oracle SecurID Access Server to distinguish it from other Access Servers) must be
registered and set up as a client/Agent.
The RSA Authentication Manager compares the tokencode it has generated with the
tokencode the user has entered. Tokencodes change at a specified interval, typically 60
seconds. Time synchronization ensures that the tokencode displayed on a user's token
is the same code the Authentication Manager software has generated for that moment.
Components Required for SecurID Authentication
56-4 Administrator's Guide for Oracle Access Management
Authentication is successful when the tokencodes match. Two-factor authentication
provides stronger legal evidence of who performed the task. When properly
configured, the Authentication Manager tracks all login requests and operations to
reliably identify the user who is responsible for each logged action.
56.2.3 Installation and Configuration Requirements
SecurID requires affinity between the OAM Server and the RSA Authentication
Manager for a user interaction. Therefore, the authentication dialog between the user
and OAM Server must be sticky (this constraint is a security feature of SecurID
authentication). In a cluster environment, if a load balancer is used to route requests to
multiple managed server, ensure that stickiness is set between the load balancer and
OAM Server.
The SecurID Authentication API is bundled with Access Manager and installed on all
OAM Servers. The SecurID Authentication API provides the connection functionality
that eliminates the need for an Authentication Agent to be installed on the OAM
Server. In other words, the API is the agent.
Every OAM Server must be registered as an RSA Authentication Agent host on the
Authentication Manager along with other requirements in Table 56–3.
Table 56–3 Installation and Configuration Guidelines
Only one designated OAM SecurID Server can complete SecurID authentication. However,
every OAM Server must be registered as an RSA Authentication Agent Host on the
Authentication Manager.
Enable the OAM SecurID Server to be recognized as an Authentication Manager client.
Port 5500 (UDP) should be available for the Authentication Manager to communicate with
authentication agents (OAM SecurId Server). This service receives authentication requests
from Oracle SecurId Server and sends replies. For more details refer to your RSA
Authentication Manager documentation.
Manage authentication requests from the client to the Authentication Manager.
Enforce two-factor authentication and block unauthorized access.
Provide automatic load balancing by detecting replica Authentication Manager response times
and routing authentication requests accordingly.
Ensure that the system time on the client is correct to prevent the server and client from being
out of sync.
Failover is not supported for Access Manager.
The SecurID Authentication Manager must be installed on a supported platform.
The system time must be correct to prevent the server and client from being out of sync.
The SecurID tokens or key fobs must be provisioned with the Authentication Manager by
providing it with the token seed records
Each user name must be mappable through an LDAP filter to a Distinguished Name in the
directory
An Authentication Manager slave and/or replicated Authentication Manager can provide
failover if the primary Authentication Manager is down
SecurID Authentication Modes
Integrating RSA SecurID Authentication with Access Manager 56-5
56.3 SecurID Authentication Modes
The following scenarios illustrate the three modes of operation:
■Standard SecurID Authentication
■SecurID Next Tokencode Authentication
■SecurID New PIN Authentication
56.3.1 Standard SecurID Authentication
When a user attempts to access a resource protected by the SecurID authentication
scheme, the following process occurs. For information on Credential Collectors, see
Chapter 23, "Understanding Credential Collection and Login."
Process overview: When the user requests a resource
1. The WebGate intercepts the resource request and queries the Access Server to
determine if and how the resource is protected, and if the user is authenticated.
2. The OAM SecurId Server queries the directory for the authentication scheme, and
receives authentication information from the directory.
3. The WebGate redirects to the Credential Collector, which presents a form
challenging the user for a two-part SecurID Passcode.
4. The user submits credentials to the Credential Collector
5. The Credential Collector hands off the credentials to the OAM SecurId Server
6. The SecurID Authentication API on the OAM SecurId Server performs the
authentication dialog and sends an LDAP bind to the Authentication Manager.
7. The Authentication Manager database matches the SecurID passcode to the user
ID and returns a success response to the Authentication Manager, which matches
the user's PIN.
8. The Authentication Manager returns the response to its Agent, the OAM SecurId
Server.
9. When the user's credentials are valid, SecurID authentication is successful. The
OAM SecurId Server creates a session for the user and redirects the user to the
Webgate, which then queries the OAM SecurId Server for resource authorization:
■Under certain conditions a New Tokencode mode is initiated, as described in
"Standard SecurID Authentication".
■Under certain conditions a New Pin mode is initiated, as described in "SecurID
Next Tokencode Authentication".
This integration requires a custom HTML login form and a properties file. Sample
Oracle-provided custom html and custom html properties files can be found in:
$ORACLE_HOME/oam/server/tools/customLoginHtml
See Also:
■Developing Custom Login Pages in the Oracle Fusion Middleware Developer's Guide for
Oracle Access Management
■"Configuring Access Manager for RSA SecurID Authentication" on page 56-6
Table 56–3 (Cont.) Installation and Configuration Guidelines
Configuring Access Manager for RSA SecurID Authentication
56-6 Administrator's Guide for Oracle Access Management
10. The OAM SecurId Server evaluates the authorization request, which allows or
denies access based upon the authorization rule.
11. When access is granted, the OAM SecurId Server passes authorization to the
WebGate, which presents the resource to the user.
56.3.2 SecurID Next Tokencode Authentication
When Next Tokencode mode is On, the user must supply the next tokencode on their
SecurID token. This mode can be triggered when:
■An incorrect Passcode was provided repeatedly during login. When a user
attempts authentication with incorrect passcodes four consecutive times, the
Authentication Manager turns on Next Tokencode mode, as noted in the
Authentication Manager's Activity Report. The next time the user successfully
authenticates with their correct Passcode, they are challenged for the next
tokencode that appears on their SecurID token.
■The Authentication Manager requires confirmation of, or synchronization with the
token. Even with a correct Passcode, the Authentication Manager Administrator
might set the Next Tokencode mode On to force the user to confirm that they have
the SecurID token or to synchronize the token with the Authentication Manager.
When Next Tokencode mode is On, the Next Tokencode challenge form is
presented to the user immediately following a successful login.
Process overview: When Next Tokencode is On
1. The Credential Collector presents a form to challenge the user for the next
tokencode on the token following a successful login.
2. The user enters a username, waits 60 seconds, then enters the next tokencode on
the SecurID token.
3. When the tokencode is correct, the Passcode the user originally entered is accepted
and the user is authenticated.
56.3.3 SecurID New PIN Authentication
When the user is required to have a new PIN, the Credential Collector prompts the
user with specific forms.
Process overview: When New PIN is required
1. The Credential Collector presents a form that allows the user to enter the PIN they
want.
2. The user enters the new PIN and then re-enters the new PIN to complete the form.
3. The OAM SecurID Server forwards the information to the Authentication
Manager.
4. The Authentication Manager registers the new PIN, which becomes part of the
Pincode the user must supply during subsequent logins.
5. The Login Form appears again where the user enters the username and Passcode
for a forced re-authentication.
56.4 Configuring Access Manager for RSA SecurID Authentication
Users with valid Oracle Access Management Administrator credentials can follow the
steps in this section to enable RSA SecurID authentication.
Configuring Access Manager for RSA SecurID Authentication
Integrating RSA SecurID Authentication with Access Manager 56-7
Prerequisites
See Table 56–3 for installation and configuration that is outside the scope of this
manual) and which must be completed before you begin SecurID integration with
Access Manager.
To set up SecurID Authentication with Access Manager
1. In your oam-config.xml, set the OAM SecurID Sever serverRequestCacheType
parameter to BASIC, as follows:
a. Stop all WebLogic servers (OAM Servers and AdminServer).
b. Locate oam-config.xml in the following path:
$DOMAIN_HOME/config/fmwconfig/oam-config.xml
c. Change the
serverRequestCacheType
from
COOKIE
(default) to
BASIC
, as
follows:
<Setting Name="serverRequestCacheType" Type="xsd:string">BASIC</Setting>
d. Start all WebLogic Servers (OAM Servers and AdminServer).
2. Register a Web agent from the RSA Console that will be used by Access Manager,
then copy the agent configuration file (sdconf.rec) as follows:
$DOMAIN_HOME/config/fmwconfig/servers/$SERVER_NAME/oam/sdconf.rec
3. Using the Oracle Access Management Console, create a custom authentication
module for RSA, as follows:
a. Click Application Security at the top of the window.
b. Select Create Custom Authentication Module from the Create (+) drop-down
menu in the Plug-ins section.
c. Select the General tab and enter the following:
Name: RSA_AUTH
d. Select the Steps tab and enter a name for the Step, then choose the RSA
SecurID Plugin
Step Name: stepRSA
Plugin Name: RSA SecurID Plugin
OK
e. In the stepRSA, Step Details tab, enter and Save the Step Details shown in the
next screen, which should also appear in your customhtml.properties file:
See Also:
■Developing Custom Login Pages in the Oracle Fusion Middleware
Developer's Guide for Oracle Access Management
See Also: "Orchestrating Multi-Step Authentication with Plug-in
Based Modules" on page 22-29
Configuring Access Manager for RSA SecurID Authentication
56-8 Administrator's Guide for Oracle Access Management
f. Steps tab: Add the User Identification Plugin: Enter a name for the Step, then
choose the RSA SecurID Plugin:
Step Name: rsa_useridentification
Plugin Name: UserIdentificationPlugin
OK
g. rsa_useridentification, Step Details: Enter and Save the following details for
your environment:
KEY_LDAP_FILTER: (uid={KEY_USERNAME})
KEY_IDENTITY_STORE_REF: The registered Default Store.
KEY_SEARCH_BASE_URL: dc=us,dc=example,dc=com
4. Orchestrate the steps as follows: stepRSA should be first (to authenticate the user
with the RSA Server); designate your User Identification Plugin for the success
step.
Initial Step: stepRSA
Name: StepRSA
On Success: rsa_useridentification
On Failure: failure
On Error: failure
Apply
Name: rsa_useridentification
On Success: Success
On Failure: failure
On Error: failure
Apply
5. Create a new authentication scheme (RSACredScheme, for example) that uses the
custom authentication module that you just created for RSA with a custom HTML
login form. Sample values are shown in the following screen:
Note: The On Failure and On Error fields must both be set to failure.
Configuring Access Manager for RSA SecurID Authentication
Integrating RSA SecurID Authentication with Access Manager 56-9
6. Use this scheme in the Application Domain protecting resources requiring SecurID
authentication.
7. Ensure that your custom HTML file is present in:
$DOMAIN_HOME/config/fmwconfig/customhtml.html
The Custom HTML for RSA Login Form requires form action set to
/oam/server/auth_cred_submit
, as follows:
<form id="loginData" action="/oam/server/auth_cred_submit" method="post"
name="loginData">
<div id="oam_credentials" class="input-row">
<span class="ctrl"></span>
</div>
div class="button-row">
<span class="ctrl">
<input id="login_button" type="submit" value="Login" class="formButton"
onclick="this.disabled=true;document.body.style.cursor = 'wait';
this.className='formButton-disabled';form.submit();return false;"/>
</span>
</div>
<div id="oam_error_messages"></div>
</form>
8. Ensure that your
customHTML
.
properties
file is:
■Named as your custom HTML file with a .
properties
extension
■Stored in the same path as your custom HTML file
Note: The authentication scheme's Context Value specifies the path
to your custom HTML login form. Your custom HTML properties file
must share the same name as the form (with a .properties extension)
in the same directory path. This example uses customhtml.html and
customhtml.properties.
Challenge parameters specify the initial RSA command for
authentication (RSA_USER_PASSCODE). The
is_rsa=true
parameter
and value must be specified for RSA.
Running a Custom RSA Plug-in
56-10 Administrator's Guide for Oracle Access Management
■Confirmed; settings match the RSA SecurID plugin configuration parameters.
For example:
username=Username
password=Password
passcode=Mother's maiden name
rsa_new_pin=RSA New Pin
rsa_new_pin_confirm=RSA Confirm New Pin
Pin=RSA Pin
rsa_sysgen_pin=RSA Create New Pin
rsa_sysgen_pin_confirm=RSA System Generated Pin
error1=Username not specified
9. Restart OAM Servers.
10. Test your configuration by accessing the appropriate protected resource and
validating the various modes.
11. See "RSA SecurID Issues and Logs" on page E-24 for details if you experience
problems.
56.5 Running a Custom RSA Plug-in
These steps should be followed to run a custom RSA plug-in, located in <ORACLE_
HOME>/oam/custom_plugins/rsa/RSAPlugin.jar.
1. Download the RSA dependent libraries named
authapi.jar
and
cryptoj.jar
.
2. Add the
authapi.jar
and
cryptoj.jar
libraries to <DOMAIN_
HOME>/config/fmwconfig/oam/plugin-lib.
3. Get the custom RSAPlugin.jar file from its directory and import the plugin to add
it to the list of custom plugins.
4. Once successfully imported, distribute and activate the plug-in.
Activation will fail the first time. When it does, restart the server and activate
again. After activation, use the plugin to specify the necessary orchestration steps.
57
Configuring Access Manager for Windows Native Authentication 57-1
57
Configuring Access Manager for Windows
Native Authentication
[38]
Access Manager enables Microsoft Internet Explorer users to automatically
authenticate to their Web-based single sign-on applications using their desktop
credentials. This is known as Windows Native Authentication (WNA)
This chapter contains the following sections to describe how to prepare your
environment and perform this integration using Active Directory:
■Introducing Access Manager with Windows Native Authentication
■Preparing Your Active Directory/Kerberos Topology
■Confirming Access Manager Operations
■Enabling the Browser to Return Kerberos Tokens
■Integrating KerberosPlugin with Oracle Virtual Directory
■Integrating the KerberosPlugin with Search Failover
■Configuring Access Manager for Windows Native Authentication
■Validating WNA with Access Manager Protected Resources
■Configuring WNA For Use With DCC
■Troubleshooting WNA Configuration
57.1 Introducing Access Manager with Windows Native Authentication
Access Manager supports Active Directory Multi-Domain and Multi-Forest topology
integration with Windows Native Authentication (WNA). The Active Directory
directory service uses a data store (known as the directory) for all information about
objects (users, groups, computers, domains, organizational units, and security
policies).
For the integration described in this chapter, an application must be protected by an
Access Manager authentication policy that uses the Kerberos authentication scheme
(KerberosScheme) with WNA as the Challenge Method with the KerberosPlugin
Authentication Module. In this case, credentials must be stored in a Windows Active
Directory instance that is registered as a user-identify store with Access Manager.
See Also: The System Requirements and Supported Platforms for
Oracle Identity and Access Management 11gR1 at
https://www.oracle.com/technetwork/middleware/ias/downloads/
fusion-certification-100350.html
Introducing Access Manager with Windows Native Authentication
57-2 Administrator's Guide for Oracle Access Management
Put another way, each protected resource is defined in an Application Domain. The
Authentication Policy includes the Authentication Scheme (KerberosScheme) that uses
an Authentication Module (Kerberos) that is tied to the default User Identity Store.
The store uses the value of "User Name Attribute" for authentication. This value is tied
to the user in Active Directory and its values for
userprincipalname =
username@domian
or
SamAccountName = username
, depending on the specific Access
Manager release.
When Access Manager single sign-on is combined with WNA, a Kerberos session
ticket is generated that contains the user's login credentials (among other things). This
Kerberos session ticket is not visible to the user.
Access Manager interoperates with WNA, which uses Kerberos credentials obtained
when the user logs in to a Windows Domain. This cross-platform authentication is
achieved by emulating the negotiate behavior of native Windows-to-Windows
authentication services that use the Kerberos protocol. For this cross-platform
authentication to work, OAM Servers must parse SPNEGO tokens to extract the
Kerberos tokens that are then used for authentication.
■SPNEGO is a Generic Security Services Application Programming Interface
(GSSAPI) "pseudo mechanism" used to negotiate one of a number of possible real
mechanisms. SPNEGO is largely employed in the Microsoft "HTTP Negotiate"
authentication extension which uses it to allow initiators and acceptors to
negotiate either Kerberos or NTLMSSP mechanisms. GSSAPI implementation is
included with most major Kerberos distributions. For more information on
SPNEGO see
http://tools.ietf.org/html/rfc4559
.
■Kerberos is a network authentication protocol that provides strong authentication
for client/server applications and services using a secret-key cryptography. A free
implementation of Kerberos protocol is available from the Massachusetts Institute
of Technology and is also commercially available.
For more information, see:
■Understanding Access Manager WNA Login and Fall Back Authentication
■Understanding Supported Kerberos Authentication Modules
57.1.1 Understanding Access Manager WNA Login and Fall Back Authentication
With WNA implemented, a user can open a Web application without another
challenge for credentials because the Kerberos session ticket is passed through the
browser to the OAM Server. The OAM Server decrypts the received token (using
keytab) and derives the authenticated user name from it. If authentication succeeds the
user is granted access to the Web application automatically.
The following sections describe an overview of the process of two WNA login
scenarios.
■Successful Access Manager WNA Authentication
■Access Manager WNA Fallback Authentication
See Also: Supported browsers in the System Requirements and
Supported Platforms for Oracle Identity and Access Management
11gR1 at
https://www.oracle.com/technetwork/middleware/ias/downloads/
fusion-certification-100350.html
Introducing Access Manager with Windows Native Authentication
Configuring Access Manager for Windows Native Authentication 57-3
57.1.1.1 Successful Access Manager WNA Authentication
1. The Browser is configured for Integrated Windows Authentication (IWA).
This is a browser security configuration. If the browser being used is not
configured to use IWA, no TGT is supplied when a resource protected by the
Kerberos authentication module is requested. A browser basic authentication
window is displayed where you can enter a valid username/password
combination defined in the Default Identity Store for
User login attribute
.
2. A resource protected by Access Manager and WNA is called.
The protected resource should be configured as an intranet resource. This is done
by adding the site in the "Local Intranet" zone of the Browser configuration.
3. A valid Kerberos ticket is present - Http headers... Authorization: Negotiate
YIIJ/...
4. The user is not challenged for authentication.
5. The requested resource is displayed, proving that WNA works.
In other words, when the browser is configured to use Integrated Windows
Authentication, and a resource is protected by the Kerberos authentication module,
then:
■If a Kerberos ticket is received by Access Manager (regardless of the domain),
authentication is attempted:
–Successful: Access is granted.
–Failure: An incorrect user name or password error occurs if information from
the Kerberos ticket is either not present or does not match the value of the
User Name Attribute defined in the Default User Identity Store. Access is
denied. The browser automatically submits the ticket, and the interaction with
Access Manager is repeated until the user has been locked out. The browser
cannot be made to pause before the start of each exchange.
■If the user is not logged on to a Windows Domain by way of Kerberos
authentication, the browser sends OAM an NTLM token for authentication instead
of a Kerberos token. Depending on how Access Manager is configured, it either
uses WNA Fallback Authentication upon receiving an NTLM token or
authentication fails.
NTLMSSP is a security support provider that is available on all versions of the
Distributed Component Object Model (DCOM). It uses the NTLM protocol for
authentication, which does not actually transmit the user's password to the server
during authentication.
Note: You need to configure Access Manager to provide fallback
authentication when the browser sends an NTLM token. Without
configuration, authentication fails. For configuration steps, see
Section 57.7.3, "Configuring WNA for NTLM Fallback."
Note: If a Kerberos ticket cannot be identified by Access Manager
(regardless of browser, Operating System, domain-login, and so on),
the fallback mechanism is invoked.
Introducing Access Manager with Windows Native Authentication
57-4 Administrator's Guide for Oracle Access Management
57.1.1.2 Access Manager WNA Fallback Authentication
Fallback uses the authentication scheme "BasicScheme" with a challenge method of
"Basic" and authentication module "LDAP". This LDAP Authentication Module uses
the LDAP plug-in. In this plug-in, the User Identity Store can be defined as any
currently registered User Identity Store in which you define the attribute to be used for
"User Name Attribute." The authentication module can be changed using the console.
1. The Browser is configured for Integrated Windows Authentication (IWA).
This is a browser security configuration. Access Manager handles two types of
WNA fallback authentication.
■Within Domain where IWA is enabled: OAM supports WNA for the
SPNEGO token. But sometimes due to configuration or other issues, OAM
receives NTLM tokens from the client rather than SPNEGO. During the
DEFAULT flow, OAM will try to authenticate using the NTLM token and fail
because OAM doesn't have the capability to authenticate NTLM tokens. Thus,
with introduction of "HandleNTLMResponse" configuration, OAM server will
challenge client with Basic prompt for authentication. i.e. The fallback here is
to prompt for basic mode of authentication if client is sending NTLM tokens to
OAM Server. See Section 57.7.3, "Configuring WNA for NTLM Fallback" for
details.
■Outside Domain where IWA is disabled: Here no extra configuration is
needed. By default the OOTB user will see a BASIC prompt during
authentication.
2. A resource protected by Access Manager and WNA is called.
The protected resource should be configured as an intranet resource. This is done
by adding the site in the "Local Intranet" zone of the Browser configuration.
3. No ticket is present (NTLM/Kerberos) - Http headers... Authorization: Basic
4. A basic authentication window pops up.
5. The user enters a valid username/password.
6. The requested resource is displayed (WNA Fallback works).
57.1.2 Understanding Supported Kerberos Authentication Modules
Use the Kerberos Authentication Module or KerberosPlugin Authentication Module
when configuring Access Manager for Windows Native Authentication. The Kerberos
Authentication Module identifies the key tab file and krb5 configuration file names
and Principal. The KerberosPlugin Authentication Module relies on bundled plug-ins
(or those that are developed using the Access Manager Authentication Extensibility
Java API). This module uses more than one plug-in that you can orchestrate to ensure
that each one performs a specific authentication function. The KerberosPlugin
Authentication Module is more robust and richer in functionality than the Kerberos
Authentication Module. The KerberosPlugin Authentication Module (along with a
plain WNA configuration) supports the following approaches:
■Kerberos Plugin with Oracle Virtual Directory: Using Access Manager with
orchestrated authentication plug-ins integrated with Oracle Virtual Directory
virtualize multiple Active Directory Global Catalogs.
■Kerberos Plugin with Search Failover Across Multiple ADGCs: Using Access
Manager with orchestrated authentication plug-ins that exercise a failover pattern
across multiple Active Directory Global Catalogs.
Preparing Your Active Directory/Kerberos Topology
Configuring Access Manager for Windows Native Authentication 57-5
57.2 Preparing Your Active Directory/Kerberos Topology
You need a fully-configured Microsoft Active Directory authentication service set up
as described here. The procedure in this section ensures that Active Directory and the
Kerberos client will operate together. The tasks in this section are required regardless
of the approach you choose. However, none of this is Oracle specific.
As a sample scenario, consider two Active Directory forests operating within a
company.
Consider that a child domain exists within the ORACLE forest:
child.lm.example.com
.
Trust is required as follows:
■Between forests: Two-way, non-transitive trust.
■Between the child domain and its parent: Two-way, transitive trust.
The suffixes and inheritance are:
■SPRITE users have UPN suffixes such as
sun.com
or
java.com
. The SPRITE forest
contains
testuser.java.com
.
■ORACLE users have suffixes such as
myoracleco.com
and
oracleco.com
. The
ORACLE forest contains
testuser.oracleco.com
.
■ORACLE child domain inherits the UPN suffixes of the parent domain.
For integration with WNA, the
User Name Attribute
defined for the Default Identity
Store can be any attribute whose value matches the Active Directory user's
samAccountName
.
You also need to know which encryption type your environment will use. In some
cases a user might be created with "Use DES encryption types for this account"
enabled. However, Active Directory is not using DES encryption.
See Also:
■Preparing Your Active Directory/Kerberos Topology
■Confirming Access Manager Operations
■Integrating KerberosPlugin with Oracle Virtual Directory
Note: The following sample scenario represents a typical Active
Directory topology, and is not a requirement dictated by or for Access
Manager. The naming used here is an example only. Your
environment will be different.
Forest Domain Name
ORACLE
lm.example.com
SPRITE
lmsib.sprite.com
Note: Pre-Windows user names formed as DOMAIN\USERNAME,
are not supported.
Preparing Your Active Directory/Kerberos Topology
57-6 Administrator's Guide for Oracle Access Management
Access Manager supports what JGSS/JDK6 supports. The limitation on the TGT
encryption that can be used would be determined by the piece that is the least
common or lowest encryption supported: KDC, Keytab, Operating System, Kerberos
client.
Access Manager does not support any specific Kerberos encryption type. It is
dependent on the Generic Security Services (GSS)/Kerberos jdk encryption types with
which it is certified. Access Manager is not dependent on any encryption type and
does not use TGT encryption. As part of SPNEGO token Access Manager only looks
into the Service Ticket which is encrypted with a key that the service (in this case
Access Manager) has registered when executing the ktpass/keytab commands.
Encryptions are used for communication among the different OS (Windows/Linux
acting as Kerberos Server/Client). OAM Server just needs the SPNEGO token, from
which it extracts the user credential. The encryption used in this three way negation
process between the Windows Client (Browser), the Windows KDC, and the Generic
Security Services (GSS) classes used by Access Manager, depend on the versions used
(which must match).
In the trusted domain (for example, the root domain
lm.example.com
), it is required
that you follow the steps provided to:
■Create an account for the OAM Server.
■Extract the keytab file that was configured with the Active Directory
Multi-Domain or Multi-Forest topology and trust relationships.
■Specify the Service Principal Name (SPN) using the fully-qualified hostname of
the OAM Server (or the load balancer that represents the OAM Cluster), followed
by the Realm name.
For this example the names in Table 57–1 are used.
Note: The keytab file created in the following procedure uses
RC4-HMAC encryption.
Note: The keytab file created in the following procedure uses
RC4-HMAC encryption.
See Also: My Oracle Support for details about the Kerberos
Encryption types Access Manager Supports [Doc 1212906.1] at:
https://support.oracle.com/CSP/main/article?cmd=show&type=NO
T&id=1212906.1
Table 57–1 Sample Naming
Name Description
kdc.lm.example.com
KDC hostname
KDC is a trusted network service that supplies session tickets and
temporary session keys to users and computers within an Active
Directory domain. The KDC runs on each domain controller as
part of Active Directory Domain Services and is implemented as a
domain service. The KDC uses Active Directory as its account
database. In implementations of the Kerberos protocol, the KDC
is a single process that provides two services: Authentication
Service (AS) and Ticket Granting Service (TGS).
Preparing Your Active Directory/Kerberos Topology
Configuring Access Manager for Windows Native Authentication 57-7
The following procedure documents how to prepare Active Directory and Kerberos.
Commands are for a Unix Operating System. Command syntax will vary depending
on the specific Operating System in your environment.
1. Check the Oracle certification matrix to ensure you are installing a supported
version of Active Directory for this integration:
https://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certificatio
n-100350.html
2. Install and configure Active Directory as follows:
■Multi-Forest topology with requisite trust relationships configured and
functional, including:
a. User accounts to map Kerberos services
b. Service Principal Names (SPNs) for these user accounts (the name by which
a client uniquely identifies an instance of a service).
c. Key tab files
■Active Directory Global Catalog (ADGC) enabled and functional within each
forest
■Multi-Forest Deployment: In this case, ensure there exists a naming attribute
(available in global catalog) that uniquely identifies the users originating from
various forests. Generally,
userprincipalname
is unique for the forest and
samAccountName
is unique for the domain
■One domain that is directly or indirectly trusted by every other domain,
regardless of forest affiliation.
3. Create a user for Access Manager use during WNA authentication and record this
user name for generating the keytab file (no DES encryption).
4. Record the OAM Server hostname. For example:
oam11g.example.com
kdc.lm.example.com
AdminServer hostname
This is the same as the KDC hostname.
oam11g.example.com
OAM Server hostname
LM.EXAMPLE.COM
LMSIB.SPRITE.COM
Default Active Directory Realm
Second Active Directory Realm
The realm name identifies the location of the user account. A
realm name can be either a prefix or a suffix.
When an access client sends user credentials, a user name is often
included. Within the user name are two elements: a user account
name and user account location.
HTTP/fully_qualified_
OAMServerhostname@REAL
M_NAME (in CAPITAL
letters
Service Principal Names (SPNs) are needed for user accounts (the
name by which a client uniquely identifies an instance of a
service).
Note: If you install multiple instances of a service on computers
throughout a forest, each instance must have its own Service
Principal Name.
Table 57–1 (Cont.) Sample Naming
Name Description
Preparing Your Active Directory/Kerberos Topology
57-8 Administrator's Guide for Oracle Access Management
5. Record the KDC hostname and the Active Directory domain/realm:
KDC = kdc.lm.example.com
Default AD Realm = lm.example.com
6. Create the Service Principal Name (SPN) of the Active Directory user that the
OAM Server client is using, and record the results (including encryption type).
The user name should be in the format
user_name@example.com
where
example.com
is the domain name of the Active Directory. For example:
ktpass -princ <protocol/oamserver_host> -pass <mypassword> -mapuser <user from
step 3> -out <path_to_filename>
ktpass -princ HTTP/oam11g.example.com@lm.example.com -mapuser oam -pass
examplepw -out c:\temp\oam.keytab
C:\Users\Administrator>ktpass -princ HTTP/oam11g.example.com@LM.EXAMPLE.COM
-mapuser oam -pass welcome1 -out c:\temp\oam.keytab
Targeting domain controller: kdc.lm.example.com
Using legacy password setting method
Successfully mapped HTTP/oam11g.example.com to oam.
WARNING: pType and account type do not match. This might cause problems.
Key created.
Output keytab to c:\temp\oam.keytab:
Keytab version: 0x502
keysize 80 HTTP/oam11g.example.com@lm.example.com ptype 0 (KRB5_NT_
UNKNOWN) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0xa3a685f89364d4a
5182b028fbe79ac38)
7. Copy the newly created keytab file to the proper location on the OAM Server and
ensure permissions are correct so that the user who created Access Manager can
access this file for running
ktpass
command.
Note: Ensure that the case of the user name is consistent when
entering it with the ktpass, kinit and klist commands. If you enter the
user name in lower case when running one command, it must be
entered in lower case when running the other commands.
For example, the case used in the commands to create the keytabs and
the configuration in /etc/krb5.conf file need to match. When ktpass is
run to create the keytab (as below), the host name of the KDC server is
lm.example.com. Since this is all lower case, the configuration in the
/etc/krb5.conf file must also be lower case. Case sensitivity is not the
issue as long as the case matches.
Note: If the user is not part of the Administrators group, follow this
procedure to explicitly allow a remote desktop connection for the user.
1. From the Oracle Access Management Console, navigate to the Remote tab
through Control Panel -> Remote Settings -> System Properties.
2. Select the "allow connections from computers running any version of
Remote Desktop" option.
3. Click Select Users.
4. Add the user.
5. Click Apply.
Preparing Your Active Directory/Kerberos Topology
Configuring Access Manager for Windows Native Authentication 57-9
8. Create a simple OAM Server Kerberos krb5.conf or krb5.ini configuration. For
example:
[libdefaults]
default_realm = lm.example.com
ticket_lifetime = 600
clock_skew = 600
[realms]
lm.example.com = { --
kdc = kdc.lm.example.com
admin_server = kdc.lm.example.com
default_domain = lm.example.com
}
[domain_realm]
lm.example.com =LM.EXAMPLE.COM
.lm.example.com = LM.EXAMPLE.COM
9. Veri fy t he
klist
and
kinits
work using the keytab file and SPN of the Active
Directory and Access Manager user created, then record the results.
a. kdestroy
b. klist [-k] [-t <keytab_filename>]. For example:
bash-3.2$ klist -k -t -K -e FILE:/refresh/home/oam.keytab
Keytab name: FILE:/refresh/home/oam.keytab
KVNO Timestamp Principal
---- ----------------- ---------------------------------------------------
3 12/31/69 19:00:00 HTTP/oam11g.example.com@lm.example.com (ArcFour
with HMAC/md5)(0xa3a685f89364d4a5182b028fbe79ac38)
bash-3.2$
c. kdestroy
d. kinit [-k] [-t <keytab_filename>] [<principal>]. For example:
klist -k -t -K -e FILE:/refresh/home/oam.keytab
bash-3.2$ kinit -V -k -t /refresh/home/oam.keytab
HTTP/oam11g.example.com@lm.example.com
Authenticated to Kerberos v5
e. klist -e
bash-3.2$ klist -e
Ticket cache: FILE:/tmp/krb5cc_8000
Default principal: HTTP/oam11g.example.com@lm.example.com
Valid starting Expires Service principal
02/25/12 18:46:55 02/25/12 18:56:55 krbtgt/LM.EXAMPLE.COM@LM.EXAMPLE.COM
Etype (skey, tkt): ArcFour with HMAC/md5, AES-256 CTS mode with 96-bit
SHA-1 HMAC
Kerberos 4 ticket cache: /tmp/tkt8000
klist: You have no tickets cached
bash-3.2$
Note: The OAM account is created in one domain that is trusted by
all, lm.example.com. This is not required for lmsib.sprite.com.
Confirming Access Manager Operations
57-10 Administrator's Guide for Oracle Access Management
10. Proceed as follows:
Successful: Continue with "Confirming Access Manager Operations".
Not Successful: Stop and resolve the issue which is not related to this integration.
Any failure at this point indicates Access Manager WNA cannot work.
57.3 Confirming Access Manager Operations
You need a fully-functioning Access Manager deployment. The tasks in this section are
required regardless of the approach you choose. In this procedure you will install and
register a WebGate, which configures an Application Domain to protect resources.
Then you verify that the environment is working with an authentication scheme other
than Kerberos.
1. Log in to the Oracle Access Management Console using Administrator credentials.
2. Verify the Default Identity Store connection.
3. Register and install WebGate as an OAM Agent and accept automatic policy
generation.
4. Add resources to the Application Domain and customize the authentication policy
protecting resources to use any Authentication Scheme other than Kerberos.
5. Test the configuration to ensure that resource protection and access are working as
expected.
6. Proceed to "Enabling the Browser to Return Kerberos Tokens."
57.4 Enabling the Browser to Return Kerberos Tokens
Use either of the following procedures to configure the Internet Explorer or Mozilla
Firefox browsers to return Kerberos tokens. Perform the appropriate procedure on all
Active Directory servers.
■Enabling Kerberos Tokens in Internet Explorer
■Enabling Kerberos Tokens in Mozilla Firefox
57.4.1 Enabling Kerberos Tokens in Internet Explorer
1. On a Windows host in the Active Directory domain, sign in as a domain user.
2. Open the Internet Explorer browser.
3. From the Tools menu, click Internet Options, click Security, click Local Intranet,
click Advanced.
4. On the Advanced tab, Security section, check the box beside Enable Integrated
Windows Authentication, and click OK.
See Also: Oracle Fusion Middleware High Availability Guide for details
about high availability environments with two or more Managed
Servers configured to operate as a cluster
Note: With Internet Explorer browsers, Integrated Windows
Authentication is enabled by default and you might not need any
changes to the default configuration for WNA to work.
Integrating KerberosPlugin with Oracle Virtual Directory
Configuring Access Manager for Windows Native Authentication 57-11
5. Add Oracle Access Manager CC host or domain name to Local Intranet zone (use the
format
http://node.host:port
(the port is not required)). For example:
http://oam11g.example.com
6. Restart the Internet Explorer browser to enable the change.
57.4.2 Enabling Kerberos Tokens in Mozilla Firefox
1. In the browser Address bar, enter
about:config
.
2. Add Oracle Access Manager CC host or domain name under
network.negotiate-auth.trusted-uris as:
network.negotiate-auth.trusted-uris=http://oam11g.example.com
Multiple URIs are separated with a comma.
57.5 Integrating KerberosPlugin with Oracle Virtual Directory
Oracle Virtual Directory provides the ability to integrate LDAP-aware applications
into diverse directory environments while minimizing or eliminating the need to
change either the infrastructure or the applications. This section provides the tasks you
must perform to configure Access Manager KerberosPlugin authentication for WNA
with Oracle Virtual Directory.
1. Perform tasks in this section:
■Preparing Oracle Virtual Directory for Integration
■Registering Oracle Virtual Directory as the Default Store for WNA
■Setting Up Authentication with Access Manager KerberosPlugin and OVD
2. Configuring Access Manager for Windows Native Authentication
3. Enabling the Browser to Return Kerberos Tokens
4. Validating WNA with Access Manager Protected Resources
57.5.1 Preparing Oracle Virtual Directory for Integration
Oracle Virtual Directory communicates with other directories through adapters. Before
you can start using Oracle Virtual Directory as an identity store, you must create
adapters to each of the directories you want to use.
The procedure differs slightly, depending on the directory to which you are
connecting. If you choose to use Oracle Internet Directory, Active Directory, Oracle
Directory Server Enterprise Edition (ODSEE), or Oracle Unified Directory, the required
adapters are created and configured while installing and configuring the Oracle
Identity Management Server. For more information on managing the adapters, see
"Managing Identity Virtualization Library (libOVD) Adapters" in the Oracle Fusion
Middleware Administrator's Guide for Oracle Identity Manager.
In the following procedure you create an account for the OAM Server in the trusted
domain. Additionally, you create two Active Directory Adapters (one for each forest)
using the fully-qualified domain names as namespaces. By default Active Directory
uses
dc
to construct the root context distinguished name. If this is different in your
deployment, adjust your adapter namespaces accordingly.
1. Perform tasks described in "Confirming Access Manager Operations".
Integrating KerberosPlugin with Oracle Virtual Directory
57-12 Administrator's Guide for Oracle Access Management
2. Install Oracle Virtual Directory, as described in Oracle Fusion Middleware Installation
Guide for Oracle Identity and Access Management.
3. In Oracle Virtual Directory Console, create two Active Directory Adapters (one
for each forest) using the fully-qualified domain names as namespaces as follows:
a. Adapter 1, EXAMPLE Adapter namespace (domain DNS
lm.example.com
):
dc=lm,dc=example,dc=com
b. Adapter 2, SPRITE Adapter namespace (domain DNS
lmsib.sprite.com
):
dc=lmsib,dc=sprite,dc=com
4. Shut down the OAM Cluster.
5. Restart the AdminServer and all OAM Servers.
6. Proceed with "Registering Oracle Virtual Directory as the Default Store for WNA".
57.5.2 Registering Oracle Virtual Directory as the Default Store for WNA
Users with valid Oracle Access Management Administrator credentials can perform
the following task to register Oracle Virtual Directory as the user store for Access
Manager interoperating with Windows Native Authentication.
For Windows Native Authentication, the user credentials must reside in Microsoft
Active Directory. Access Directory can be managed by Oracle Virtual Directory
instance. For single sign-on with Access Manager, each User Identity Store must be
registered to operate with Access Manager.
Typically,
userprincipalname
reflects the Windows login name. For WNA with Access
Manager, either leave the User Search Base and Group Search Base blank or provide
the distinguished name path that is common to both the adapters configured while
performing prerequisite tasks. Before you begin, be sure to complete the sections
Preparing Your Active Directory/Kerberos Topology and Confirming Access Manager
Operations.
1. In the Oracle Access Management Console, click Configuration at the top of
the window.
2. Click User Identity Stores.
3. In the OAM ID Stores section, click Create.
4. Enter required values for your Oracle Virtual Directory instance. For example:
Name:
OVD
LDAP Url:
ldap://ovd_host.domain.com:389
Principal:
cn=Administrator,cn=users,dc=lm,dc=example,dc=com
Credential:
********
User Search Base:
dc=com
User Name Attribute:
userprincipalname
Group Name: cn
Group Search Base:
dc=com
LDAP Provider: Oracle Virtual Directory
5. Default Store: Click the Default Store button to make this the user Identity Store
for Access Manager.
6. Click Apply to submit the registration, then dismiss the Confirmation window.
7. Restart the AdminServer and OAM Servers.
Integrating KerberosPlugin with Oracle Virtual Directory
Configuring Access Manager for Windows Native Authentication 57-13
8. Proceed to "Setting Up Authentication with Access Manager KerberosPlugin and
OVD".
57.5.3 Setting Up Authentication with Access Manager KerberosPlugin and OVD
When a native authentication module does not offer enough flexibility for your needs,
you can create a custom authentication module using plug-ins designed to meet
specific needs.
The
KerberosPlugin
is a credential mapping module that matches the credentials
(encrypted username in the Kerberos ticket (SPNEGO token)) of the user who requests
the resource. By default,
KerberosPlugin
maps the domain DNS name to the
corresponding distinguished name using the
dc
component. However, if the mapping
is different, you can specify the correct mapping as a semi-colon (;) separated list of
name:value tokens. For example:
LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com
Users with valid Oracle Access Management Administrator credentials can perform
the following task to replace default
KerberosPlugin
steps with steps that enable
integration for Windows Native Authentication using the Oracle Access
Management Console.
1. In the Oracle Access Management Console, click Application Security at the
top of the window.
2. Click Authentication Modules in the Plug-ins section.
3. Click Search, locate the KerberosPlugin plug-in and open it for editing.
4. On the KerberosPlugin page, click the Steps tab.
Steps Tab: Replace stepKTA, as described here, then click Save.
a. Click stepKTA then click the Delete (x) button to remove this step.
b. Click the Add (+) button and add the following step to the plug-in:
Step Details:
Edit this new stepKTA to change the Step Orchestration value from NULL
(defined during the step deletion) to its default value of:
On Success: StepUIF Failure Failure
Also, confirm that this new stepKTA includes the parameter
KEY_DOMAIN_DNS2DN_
MAP
(created earlier), enter the appropriate values for your deployment and click
Save.
Element Description
Name stepKTA
Class KerberosTokenAuthenticator
Integrating the KerberosPlugin with Search Failover
57-14 Administrator's Guide for Oracle Access Management
5. stepUIF Details: Configure as follows and click Save:
6. stepUI and stepUA: Configure as follows and Save:
7. Save the changes.
8. Restart the OAM Cluster.
9. Proceed with "Configuring Access Manager for Windows Native Authentication".
57.6 Integrating the KerberosPlugin with Search Failover
In cases where an Oracle Virtual Directory deployment is not viable, and it is
acceptable to perform search failover based on some order or hierarchy when finding
the user, you can configure Access Manager as described in the following task
overview.
1. Complete tasks in the following earlier sections:
■"Preparing Your Active Directory/Kerberos Topology"
■"Confirming Access Manager Operations" (except "Preparing Oracle Virtual
Directory for This Integration", which is not needed for Search Failover)
■"Enabling the Browser to Return Kerberos Tokens"
2. Perform tasks in this section:
■"Registering Microsoft Active Directory Instances with Access Manager"
■"Setting Up the KerberosPlugin for ADGCs"
3. "Configuring Access Manager for Windows Native Authentication"
4. "Validating WNA with Access Manager Protected Resources"
Element Description
KEY_DOMAIN_DNS2DN_MAP Active Directory Forests in your deployment. For example:
LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPR
ITE.COM:dc=lmsib,dc=sprite,dc=com
Note: By default, a DN domain name a.b.c is mapped into
dc=a,dc=b,dc=c. Only if the mapping is different, one has to
specify the parameter. Otherwise it is best not to use it and let
the default behavior take its course.
Service Principal HTTP/oam11g.example.com@LM.EXAMPLE.COM
keytab.conf keytab.conf location for stepKTA
krb5.conf krb5.conf location for stepKTA
Element Description
KEY_LDAP_FILTER (samAccountName={KEY_USERNAME})
KEY_IDENTITY_STORE_REF OVD
KEY_SEARCHBASE_URL Leave this empty
KEY_IDENTITY_STORE_REF OVD
Integrating the KerberosPlugin with Search Failover
Configuring Access Manager for Windows Native Authentication 57-15
57.6.1 Registering Microsoft Active Directory Instances with Access Manager
Users with valid Oracle Access Management Administrator credentials can perform
the following task to register each Active Directory Global Catalog (ADGC), with
relevant search bases and naming attributes, as an individual User Identity Store for
Oracle Access Management.
A fully-configured Microsoft Active Directory authentication service should be set up
with User accounts for mapping Kerberos services, Service Principal Names (SPNs) for
those accounts, and Key tab files. For more information, see Oracle Fusion Middleware
Securing Oracle WebLogic Server 11g Release 1 (10.3.3).
1. In the Oracle Access Management Console, click Configuration at the top of
the window.
2. Click User Identity Stores.
3. In the OAM ID Stores section, click Create.
4. Enter required values for your first ADGC. For example:
Name:
ADGC1-EXAMPLE
LDAP Url:
ldap://ADGC1_host.domain.com:389
Principal:
cn=Administrator,cn=users,dc=lm,dc=example,dc=com
Credential: ********
User Search Base:
dc=lm,dc=example,dc=com
User Name Attribute:
userprincipalname
Group Search Base:
dc=lm,dc=example,dc=com
LDAP Provider: AD
5. Default Store: Click the Default Store button.
6. Click Apply to submit the changes and dismiss the confirmation window.
7. Repeat these steps to add the second ADGC (ADGC2-SPRITE) with appropriate
search bases and naming attributes.
Name:
ADGC2-SPRITE
LDAP Url:
ldap://ADGC2_host.domain.com:389
Principal:
cn=Administrator,cn=users,dc=lm,dc=example,dc=com
Credential: ********
User Search Base:
dc=lmsib,dc=example,dc=com
User Name Attribute:
userprincipalname
Group Search Base:
dc=lmsib,dc=example,dc=com
LDAP Provider: AD
8. Restart the AdminServer and OAM Servers.
9. Proceed to "Setting Up the KerberosPlugin for ADGCs".
57.6.2 Setting Up the KerberosPlugin for ADGCs
When a native authentication module does not offer enough flexibility for your needs,
you can create a custom authentication module using plug-ins designed to meet
specific needs.
The KerberosPlugin is a credential mapping module that matches the credentials
(username and password) of the user who requests a resource to the encrypted
"Kerberos ticket". By default, KerberosPlugin maps the domain DNS name to the
corresponding distinguished name using the
dc
component. However, if the mapping
Integrating the KerberosPlugin with Search Failover
57-16 Administrator's Guide for Oracle Access Management
is different, you can specify the correct mapping as a semi-colon (;) separated list of
name:value tokens. For example:
LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com
Users with valid Oracle Access Management Administrator credentials can perform
the following task to replace or update KerberosPlugin steps with steps that point to
the ADGCs you have created. These will operate in tandem with their counterparts (if
the initial step and ADGC fail, the secondary ADGC is used). Before you begin, be
sure to complete the sections Preparing Your Active Directory/Kerberos Topology and
Confirming Access Manager Operations.
1. In the Oracle Access Management Console, click Application Security at the
top of the window.
2. Click Authentication Modules in the Plug-ins section.
3. Click Search, locate the KerberosPlugin plug-in and open it for editing.
4. On the KerberosPlugin page, click the Steps tab.
Steps Tab: Replace stepKTA, as described here, then click Save.
a. Click stepKTA then click the Delete (x) button to remove this step.
b. Click the Add (+) button and add the following step to the plug-in:
New stepKTA Details:
Confirm that this new stepKTA includes the parameter
KEY_DOMAIN_DNS2DN_MAP
(created earlier) and enter values for your deployment:
5. stepUIF: Step Details (configure as follows and save):
Element Description
Name stepKTA
Class KerberosTokenAuthenticator
Element Description
KEY_DOMAIN_DNS2DN_MAP
LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.
SPRITE.COM:dc=lmsib,dc=sprite,dc=com
Service Principal HTTP/oam11g.example.com@LM.EXAMPLE.COM
keytab.conf keytab.conf location for stepKTA. For example:
/refresh/home/oam.keytab
krb5.conf krb5.conf location for stepKTA.
/etc/krb5.conf
Element Description
KEY_IDENTITY_STORE_REF ADGC1-ORACLE
KEY_SEARCHBASE_URL {KEY_USERDOMAIN}
KEY_LDAP_FILTER (samAccountName={KEY_USERNAME})
NOTE: For untrusted, multi-domain Active
Directory environments, use the
userPrincipalName
user attribute.
Configuring Access Manager for Windows Native Authentication
Configuring Access Manager for Windows Native Authentication 57-17
6. stepUI and stepUA: Step Details (configure these steps and save):
7. Save the changes.
8. Add stepUIF2: This will operate in tandem and execute if stepUIF fails:
9. Add stepUI2: This will operate in tandem and execute if stepUI fails:
10. Add stepUA2: This executes when stepUI2 succeeds:
11. Add Step Details: Common Configuration, Plugins, KerberosTokenAutheticator.
Enter values for your deployment:
12. Restart the OAM Cluster.
13. Proceed with "Configuring Access Manager for Windows Native Authentication".
57.7 Configuring Access Manager for Windows Native Authentication
Whether you are using Oracle Virtual Directory or Active Directory with Global
Catalogs, this section provides the following topics with steps you can follow:
■Creating the Authentication Scheme for Windows Native Authentication
■Configuring Policies for Windows Native Authentication
■Configuring WNA for NTLM Fallback
■Verifying the Access Manager Configuration File
Element Description
KEY_IDENTITY_STORE_REF ADGC1-ORACLE
Element Description
KEY_IDENTITY_STORE_REF ADGC2-SPRITE
KEY_SEARCHBASE_URL {KEY_USERDOMAIN}
KEY_LDAP_FILTER (samAccountName= {KEY_USERNAME})
NOTE: For untrusted, multi-domain Active
Directory environments, use the
userPrincipalName
user attribute.
Element Description
KEY_IDENTITY_STORE_REF ADGC2-SPRITE
Element Description
KEY_IDENTITY_STORE_REF ADGC1-EXAMPLE and ADGC2-SPRITE,
respectively
Element Description
keytab.conf keytab.conf location for stepKTA. For example:
/refresh/home/oam.keytab
krb5.conf krb5.conf location for stepKTA. For example:
/etc/krb5.conf
Configuring Access Manager for Windows Native Authentication
57-18 Administrator's Guide for Oracle Access Management
57.7.1 Creating the Authentication Scheme for Windows Native Authentication
Users with valid Oracle Access Management Administrator credentials can perform
the following task to define an authentication scheme to use in policies protecting
applications for Windows Native authentication. Before you begin, be sure to complete
one of the following sections: Integrating KerberosPlugin with Oracle Virtual
Directory or Integrating the KerberosPlugin with Search Failover.
1. In the Oracle Access Management Console, click Application Security at the
top of the window.
2. Click Authentication Schemes in the Access Manager section.
3. Under Search, type KerberosScheme in the Name box and click Search.
4. Click KerberosScheme in the search results to open it.
Set (or confirm) the following attributes:
Challenge Method: WNA
Authentication Module: KerberosPlugin
5. Finish configuring KerberosScheme for your deployment.
6. Click Apply and close the confirmation window.
7. Proceed to "Configuring Policies for Windows Native Authentication".
57.7.2 Configuring Policies for Windows Native Authentication
In this procedure you edit (or Create) an Application Domain and policies to protect
resources for Windows Native Authentication. Before you begin, complete Creating
the Authentication Scheme for Windows Native Authentication.
1. In the Oracle Access Management Console, click Application Security at the
top of the window.
2. Click Application Domains in the Access Manager section.
3. Open (or Create) the desired Application Domain, as described in "Managing
Application Domains Using the Console" on page 25-10.
4. Resource Definitions: Add Resource Definitions to the domain as described in
"Adding and Managing Policy Resource Definitions" on page 25-13.
5. Authentication Policies:
a. Open the Authentication Policies node, and open (or Create) the desired
Authentication Policy with the following attributes:
Authentication Scheme: KerbScheme as the and ensure that it includes the
updated KerberosPlugin.
Choose KerbScheme as the Authentication Scheme and ensure that it includes
the updated KerberosPlugin.
b. Click Apply, close the Confirmation window.
c. Resources for Authentication Policy: Add Resources to the Authentication
Policy as described in the Oracle Fusion Middleware Administrator's
Guide for Oracle Access Management.
d. Complete the Authentication Policy with any desired Responses.
Configuring Access Manager for Windows Native Authentication
Configuring Access Manager for Windows Native Authentication 57-19
6. Authorization Policies: Complete the Authentication Policy with any desired
Responses or Conditions as described in "Defining Authorization Policies for
Specific Resources" on page 25-35.
7. Proceed to "Verifying the Access Manager Configuration File".
57.7.3 Configuring WNA for NTLM Fallback
Follow these steps to configure Access Manager to use WNA Fallback Authentication
upon receiving an NTLM token. For more information, see Section 57.1.1,
"Understanding Access Manager WNA Login and Fall Back Authentication."
1. Stop the OAM managed server.
2. Back up the following file to a safe location:
<WLS domain>/config/fmwconfig/oam-config.xml
3. Modify
<WLS domain>/config/fmwconfig/oam-config.xml
as follows:
a. Find the following line:
<Setting Name="CredentialCollector" Type="htf:map">
b. After the line, add the following elements (if they are not already present):
--------------------------------------------------------------------------
<Setting Name="WNAOptions" Type="htf:map">
<Setting Name="HandleNTLMResponse" Type="xsd:string">BASIC</Setting>
</Setting>
--------------------------------------------------------------------------
If the following parameter already exists:
<Setting Name="HandleNTLMResponse" Type="xsd:string">DEFAULT</Setting>
change the
HandleNTLMResponse
value from
DEFAULT
to
BASIC
. For example:
<Setting Name="HandleNTLMResponse" Type="xsd:string">BASIC</Setting>
4. Restart the OAM server processes.
57.7.4 Verifying the Access Manager Configuration File
Verify that the following are specified in the
oam-config.xml
file as in Example 57–1:
■path to the
krb5.conf
file
■path to the
keytab
file
■a principal to connect with KDC
Example 57–1 oam-config.xml
<Setting Name="KerberosModules" Type="htf:map">
<Setting Name="6DBSE52C" Type="htf:map">
<Setting Name="principal"
Type="xsd:string">HTTP/oam11g.example.com@LM.EXAMPLE.COM
</Setting>
Note: See Section 57.10.4, "Two BASIC Authentication Prompts Are
Displayed" for troubleshooting information.
Validating WNA with Access Manager Protected Resources
57-20 Administrator's Guide for Oracle Access Management
<Setting Name="name" Type="xsd:string">XYZKerberosModule</Setting>
<Setting Name="keytabfile"
Type="xsd:string">/refresh/home/oam.keytab
</Setting>
<Setting Name="krbconfigfile" Type="xsd:string">/etc/krb5.conf</Setting>
</Setting>
</Setting>
57.8 Validating WNA with Access Manager Protected Resources
Integrated Windows Authentication (IWA) is associated with Microsoft products that
use SPNEGO, Kerberos, and NTLMSSP authentication protocols included with certain
Windows operating systems. The term Integrated Windows Authentication (IWA) is
used for the automatic authentication process that happens between Microsoft Internet
Information Services, Internet Explorer, and Microsoft's Active Directory.
WNA authentication occurs internally. When integrated with Access Manager:
■The user is redirected to the Access Manager for authentication.
■The OAM Server requests authentication with a www-negotiate header when the
resource is protected by Access Manager with a challenge method of WNA.
■The browser configured for Integrated Windows Authentication (IWA) sends the
Kerberos SPNEGO token to the OAM Server for decryption.
■The OAM Server decrypts the received user SPNEGO token (using keytab) and
redirects the user back to the Agent with the cookie and gets access to the resource.
Use this procedure to validate WNA with Access Manager protected resources.
1. Log in to a Windows system in the Active Directory domain as a domain user.
2. Sign in to the Windows OS client using the Windows domain credentials stored in
a hosted Active Directory that is registered with Access Manager.
3. Open an Internet Explorer browser window, and enter the URL for the
OAM-protected application in your environment.
4. Confirm that you are logged in to the application with your Windows domain
credentials with no additional login.
57.9 Configuring WNA For Use With DCC
The Kerberos authentication protocol provides a mechanism for mutual authentication
between entities before a secure network connection is established. This section
provides information on how to configure Windows Native Authentication and
Kerberos to use the DCC with Access Manager. It contains the following topics.
■Initializing the Kerberos Protocol
■Configuring Access Manager
Note: IWA is also known by other names such as HTTP Negotiate
authentication, NT Authentication, NTLM Authentication, Domain
authentication, Windows Integrated Authentication, Windows NT
Challenge/Response authentication and Windows Authentication.
Configuring WNA For Use With DCC
Configuring Access Manager for Windows Native Authentication 57-21
57.9.1 Initializing the Kerberos Protocol
To initialize Access Manager for the Kerberos protocol, do the following.
1. Run the
ktpass
command on the Windows data store, substituting the appropriate
values for service, realm, user and user password.
ktpass -princ <SPN>@<REALM> -pass <Password> -mapuser <UserName>
-out <Keytab file name>
For example:
ktpass -princ HTTP/adc.example1.com@EXAMPLE.COM -pass Welcome1 -mapuser
anil@example.com -out foobar2.keytab
This command creates an SPN and associates it with the local service account
created in the previous step.
2. Copy the keytab output generated by the
ktpass
command and leave it at an
appropriate location on the DCC host machine.
3. Modify the
/etc/krb5.conf
file on the DCC host machine accordingly.
For example:
[loggings]
default = FILE:/scratch/anikukum/krb/krb5libs.log
kdc = FILE:/scratch/anikukum/krb/krb5kdc.log
admin_server = FILE:/scratch/anikukum/krb/krbadmin.log
[libdefaults]
default_realm = EXAMPLE.COM
ticket_lifetime = 24h
forwardable = yes
dns_lookup_realm = false
dns_lookup_kdc = false
default_tkt_enctypes = rc4-hmac
default_tgs_enctypes = rc4-hmac
permitted_enctypes = rc4-hmac
clockskew = 3600
[realms]
EXAMPLE.COM = {
kdc = adc.example1.com
admin_server = adc.example1.com
default_domain = EXAMPLE.COM
}
[domain_realm]
example.com = EXAMPLE.COM
.example.com = EXAMPLE.COM
Note: See Understanding Credential Collection and Login for details
on DCC.
Note: Only RC4-HMAC encryption is supported; do not use DES
encryption.
Configuring WNA For Use With DCC
57-22 Administrator's Guide for Oracle Access Management
4. Run the
kinit
command on the DCC host machine to obtain a Kerberos ticket.
kinit -k -t <keytab file> <SPN>@<Realm>
For example:
kinit -k -t foobar1.keytab HTTP/adc.example1.com@EXAMPLE.COM
5. Validate the Kerberos ticket on the DCC host machine using the klist command.
klist
57.9.2 Configuring Access Manager
This procedure will configure Access Manager to use the Kerberos Authentication
Module.
1. Modify the Challenge Method of the Kerberos authentication scheme to WNA, if
applicable.
a. In the Oracle Access Management Console, click Application Security at the
top of the window.
b. In the Launch Pad tab, click Authentication Schemes in the Access Manager
section.
c. Search for KerberosScheme and click Edit.
d. Change the Challenge Redirect URL to DCC WebGate URL.
For example, http://<DCC-WebGate-Hostname>:<Port>/
e. Click Apply and close the page.
2. Configure the User Identity Store for LDAP Authentication Module to the
configured Windows data store.
Note: For multiple domain Active Directory environments, add
entries for each domain as documented below.
[realms]
EXAMPLE.COM = {
kdc = adc.example1.com
admin_server = adc.example1.com
default_domain = EXAMPLE.COM
}
SPRITE.COM = {
kdc = lmsib.sprite.com
admin_server = lmsib.sprite.com
default_domain = SPRITE.COM
}
[domain_realm]
example.com = EXAMPLE.COM
.example.com = EXAMPLE.COM
sprite.com = SPRITE.COM
.sprite.com = SPRITE.COM
Troubleshooting WNA Configuration
Configuring Access Manager for Windows Native Authentication 57-23
a. In the Oracle Access Management Console, click Application Security at the
top of the window.
b. In the Launch Pad tab, click Authentication Modules in the Access Manager
section.
c. Search for LDAP and click Edit.
d. Change the User Identity Store to, for example, Active Directory.
e. Click Apply and close the page.
3. Configure the Application Domain protecting the resource to use the Kerberos
authentication scheme.
Before accessing the protected resource ensure that its URL is added to the local
intranet Site of Security. Additionally, check the Enable Integrated Windows
Authentication option under Security in the Advance tab.
57.10 Troubleshooting WNA Configuration
This section provides information about the following errors:
■Kinit Fails
■"An Incorrect Username or Password was Specified" Is Displayed
■User Identity Store is Not Registered Correctly
■Two BASIC Authentication Prompts Are Displayed
57.10.1 Kinit Fails
While retrieving initial credentials, the client may not be found in the Kerberos
database. This is the Kerberos version of "User not found" and might be related to one
of the following:
■Misspelling or typo of the principal name
■The principal was not added to the Kerberos database, the principal doesn't exist.
■The user name does not exist in Active Directory or has not been registered as a
Kerberos user.
■The SPN is not unique.
■On the Active Directory side one or more duplicate entries were found.
The solution would be to have the Active Directory Administrator search the LDAP
tree for duplicate entries of the SPN, and remove them.
57.10.2 "An Incorrect Username or Password was Specified" Is Displayed
If unable to access a resource protected by Access Manager using the WNA
authentication scheme and the error "An incorrect Username or Password was
specified" is displayed, check the following.
■An incorrect username or password was specified.
■There is a mismatch in the encryption types being used.
See Also: Access Manager WNA Quick Start Guide on My Oracle
Support, Knowledge Base note 1416903.1 at:
https://support.oracle.com/
Troubleshooting WNA Configuration
57-24 Administrator's Guide for Oracle Access Management
■The key version number (kvno) of the SPN mentioned in the keytab does not
match the kvno of the mapped user in the identity store.
57.10.3 User Identity Store is Not Registered Correctly
By default, the OAM identity store is Embedded LDAP. If you are using a different
identity store (for example, Active Directory or Oracle Unified Directory) be sure to
register the identity store. Chapter 5, "Managing Data Sources" has complete details on
identity stores and how to register them.
■To set the identity store being used as the Default Store, see Section 5.2.2, "Using
the System Store for User Identities."
■To register the User Identity Store being used, see Section 5.2.5, "Registering a New
User Identity Store" with details in Section 5.2.4, "Defining the User Identity Store
Registration Settings."
57.10.4 Two BASIC Authentication Prompts Are Displayed
If OAM is configured for WNA and the client browser is not configured for IWA, two
BASIC authentication prompts might be displayed when accessing a WNA protected
resource. One prompt comes from the Weblogic Server and the second from OAM. To
avoid this, the WebLogic Server must be configured to ignore HTTP Basic
authentication requests.
1. Stop all WebLogic managed server and the admin server.
2. Create a copy of the config.xml file.
$WLS_DOMAIN/config/config.xml
3. Add the following parameter at the end of the "<security-configuration>" section
in the config.xml file.
<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-c
redentials>
Be sure to add this parameter BEFORE the
<cross-domain-security-enabled>false</cross-domain-security-enabled>
parameter.
4. Restart the WebLogic environment.
58
Integrating JBoss with Access Manager 58-1
58
Integrating JBoss with Access Manager
Oracle provides a J2EE-type JBoss Agent and JBoss Login Module for a smooth
integration between Access Manager and JBoss. This chapter provides the following
information to assist you with this integration.
■Overview of JBoss Integration with Access Manager
■Understanding the Integration Topology
■Preparing Your Environment for JBoss 6.x Integration
■Preparing Your Environment for JBoss 5.x Integration
■Protecting JBoss-Specific Resources
■Protecting Web Applications with the JBoss Agent
■Configuring JBoss Server to Access a Host Name (not localhost)
■Configuring the Login Module to Secure EJBs
■Configuring the Login Module to Secure Web Service Access
■Configuring Logging for the JBoss Agent and Login Module
■Validating Your Configuration
58.1 Overview of JBoss Integration with Access Manager
JBoss application server is an open source alternative to the IBM WebSphere and SAP
NetWeaver application servers. The JBoss application server and related services are a
J2EE platform used for developing and deploying enterprise Java applications, Web
applications services, and portals. J2EE allows the use of standardized modular
components and enables the Java platform to handle many aspects of programming
automatically. For integration with JBoss, Oracle provides:
■A J2EE type JBoss Agent
■A JAAS-compliant Login Module, which can be used with any client to
authenticate against Access Manager
Integration between JBoss and Access Manager enables you to:
■Protect Web applications and establish user single sign-on
■Secure EJB access by configuring the login module for EJBs
Note: There is no special processing within (or by) Access Manager
with (or for) the JBoss Agent.
Overview of JBoss Integration with Access Manager
58-2 Administrator's Guide for Oracle Access Management
■Secure Web Services using the login module with Web service handlers to
authenticate and authorize the caller
There are no client interfaces. For more information, see the following topics:
■Understanding the Configuration of and Processing by the JBoss Agent
■Understanding the Configuration of and Processing by the Login Module
58.1.1 Understanding the Configuration of and Processing by the JBoss Agent
The JBoss Agent is a fully capable agent running on the JBoss Server. This JBoss Agent
supports Access Manager Web single sign-on flows with (or without) a WebGate.
Authentication and authorization are based on resource URLs defined within Access
Manager policies. The JBoss Agent intercepts every incoming request to the OAM
Server and checks for access permissions for the requested resource. If the resource is
protected by an OAM policy, the JBoss Agent initiates authentication and
authorization for the user trying to access the resource.
Whenever an unauthenticated user requests access to any protected resource, the JBoss
Agent redirects the user to the credential collector for a user name and password. The
username and password that is entered is authenticated by the OAM Server. The JBoss
Agent then establishes user session on the JBoss Container using the login module for
the user. The login module queries the LDAP directory and fetches the authenticated
user principals to set the subject.
The JBoss Agent requires OAM Server communication details, certificate store, and
more, which can be configured as:
■A properties file containing all configuration details (the path to this file can be set
as a filter parameter)
■The absolute path of the properties file added within the filter configuration in
web.xml
The application filter should log messages at different logging levels (FATAL, ERROR,
WARNING, DEBUG, TRACE). Each level indicates the severity of information logged,
in descending order. The filter should be able to log the detailed trace of an incoming
message as one set. The JBoss Agent and the Login Module are both equipped with
messages for various log levels. For logging in the same log file (server.log):
<category name="<<Component_code_package>>">
<priority value="FINEST" class="org.jboss.logging.log4j.JDKLevel"/>
</category>
For example, for ASDK, the category name in the previous tag is
oracle.security.am.asdk, as shown:
<category name="<<oracle.security.am.asdk>>">
<priority value="FINEST" class="org.jboss.logging.log4j.JDKLevel"/>
Note: The JBoss Agent depends on the Pure Java ASDK classes and
APIs for accessing and communicating with the OAM Server. The
JBoss Agent implements the javax.servlet.Filter interface. For more
information, see the Access Manager Java API Reference.
Note: The custom headers that are defined by the Oracle Access
Management Administrator can only be defined using these methods.
Overview of JBoss Integration with Access Manager
Integrating JBoss with Access Manager 58-3
</category>
The following overview outlines the processing functions for the Access Manager
JBoss Agent.
1. Query the OAM Server to check whether the requested resource is protected.
2. Call the OAM Server to retrieve the authentication scheme.
3. Analyze the authentication scheme for the protected resource, and redirect the
request to the credential collector.
4. Authenticate the user credentials.
5. Successful Authentication: Set the authentication token generated from the OAM
Server in the cookie.
6. Authentication Token: Validate the integrity of the token before servicing the
request. Request the OAM Server to verify the user is authorized to access the
protected resource and handle the response from the OAM Server accordingly.
7. Depending upon the user requests and OAM Server responses, the JBoss Agent
identifies where user requests should be redirected to allow or deny access to the
protected resource.
The JBoss Agent is comprised of components described in Table 58–1. Each component
uses the Access ASDK to communicate with the OAM Server.
58.1.2 Understanding the Configuration of and Processing by the Login Module
The JAAS-compliant Access Manager Login Module is a pluggable authentication
module using JAAS APIs provided by the Access Manager
javax.security.*
package. The JAAS-compliant Login Module interfaces enable the client to pass
authentication data to the server. The login module is configured with the JBoss server
Table 58–1 JBoss Agent Composition
Component Description
Authentication Valve Invoked during the JBoss Authentication phase for all incoming requests. If
the resource is marked as protected by security constraints in the
application's Web descriptor, the Authentication Valve checks for the
presence of a user principal in the HTTP session:
■Valid User Present: The Authentication Valve evaluates whether the
user principal satisfies the security constraints from the application's
Web description. If constraints are satisfied, the request proceeds.
Otherwise, an authorization failure message is displayed.
■Valid Single Sign On Cookie Present (ObSSOCookie) (No Valid User):
The Authentication Valve verifies the cookie's validity by using the
Access Manager Login module (and sets the user principal in the
session).
■No Valid Single Sign On Cookie Present (ObSSOCookie) / No Valid
User: The Valve redirects to the OAM Login page when the resource is
marked as protected using Access Manager policies.
Authentication Filter Invoked for each incoming request following the JBoss authentication
phase. For each incoming request, the filter verifies whether a token is
present.
■Token Present: The filter uses the ASDK to validate the token.
■Invalid Token: The filter redirects to the Access Manager Login page.
Access Manager Login
Module
Used internally by the JBoss Agent to authenticate the user based on the
SSO token.
Any client (stand alone or deployed within the JBoss Container) can use the
Login Module to authenticate the incoming user based on username and
password or a valid token.
Overview of JBoss Integration with Access Manager
58-4 Administrator's Guide for Oracle Access Management
and application to integrate the module with the JBoss application server. The Login
Module implementation class is:
public class OAMLoginModule implements LoginModule
The standard JAAS packages required by this class are
javax.security.*
. The login
module class is stored in a jar file: $JBOSS_HOME/server/default/lib.
The login-config.xml file is the default JBoss Login Module configuration file. This
Login Module requires a JAAS security domain name (
OAMLoginModule
, for instance).
Information is stored in login-config.xml as a list of named security domains, each of
which specifies a number of JAAS Login Modules that are used for authentication
within that domain. For example, you add this manually and then restart the JBoss
Server.
<application-policy name="OAMLoginModule">
<authentication>
<login-module
code="oracle.security.am.agent.common.jaas.login.OAMLoginModule"
flag="required">
<module-option name="loginType">tokenBased</module-option>
<module-option name="configPath">D:/agentconfig</module-option>
<module-option name="publicAuthnResourceName">/Authen/Basic</module-option>
<module-option name="rolesParam">OAM_GROUPS</module-option>
<module-option
name="publicAuthzResourceName">/Authen/SSOToken</module-option>
</login-module>
</authentication>
</application-policy>
The JAAS-compliant Login Module consumes either user name/password or Access
Manager token. It authenticates and validates the credentials or token with the OAM
Server (using the Access Manager Java ASDK APIs) and populates the JAAS subject
with user and group information obtained from the OAM Server.
The Login Module can operate in either usernamePassword mode or tokenBased
mode. The following sections provide details.
■Understanding the Login Module Process in usernamePassword Mode
■Understanding the Login Module Process in tokenBased Mode
58.1.3 Understanding the Login Module Process in usernamePassword Mode
The usernamePassword mode authenticates the user based on user name and
password or a user and certificate combination that forms a security identity and
credential pair. The Login Module does not directly query the LDAP. Instead the login
module uses the OAM Java ASDK to communicate and authenticate the user
Note: Whenever an application requires security, you must specify
the domain name to use in the application's JBoss-specific deployment
descriptors (either one or both):
■jboss.xml: Defines JBoss-specific configurations for an application.
■jboss-web.xml: Defines JBoss for a Web application. This file must
declare the security domain and should be placed in the WEB-INF
folder.
Understanding the Integration Topology
Integrating JBoss with Access Manager 58-5
credentials with the OAM Server; user and group information is retrieved as
responses. Following is an overview of the process.
1. Fetches login information.
2. Authenticates the user with Access Manager based on credentials collected by the
JBoss Agent.
3. Creates the container session for the client on the server.
4. Sets the JAAS subject with the userID and roles.
5. On logout, clears the principal settings of the subject in the session and removes
the privilege settings associated with the roles of the subject.
58.1.4 Understanding the Login Module Process in tokenBased Mode
The tokenBased mode sets the Subject by validating the SSO token.
1. Fetches login information.
2. Validates the SSO authentication token generated from the OAM Server in the
cookie.
3. Creates the container session for the client on the server.
4. Sets the JAAS subject with the userID and roles fetched using the existing SSO
session token.
5. On logout, clears the principal settings of the subject in the session and removes
the privilege settings associated with the roles of the subject.
58.2 Understanding the Integration Topology
This section provides the following information.
■Topology: Access Manager with JBoss Agent
■Topology: JBoss Agent Behind Web Server Configured with WebGate
■Sample Integration Topology
58.2.1 Topology: Access Manager with JBoss Agent
Figure 58–1 illustrates the various clients (whether browser, EJB, or Web serivce) that
can securely access any J2EE application deployed on the JBoss Application Server.
The JBoss Agent is configured for this access and is deployed within the JBoss
Application Server.
Figure 58–1 Various Clients Deployed on JBoss Application Server
Understanding the Integration Topology
58-6 Administrator's Guide for Oracle Access Management
58.2.2 Topology: JBoss Agent Behind Web Server Configured with WebGate
In addition to operating alone, the JBoss Agent can be also work in conjunction with
an Oracle HTTP Server (proxy) configured with a WebGate, as shown in Figure 58–2.
Figure 58–2 JBoss Agent Deployed with an Oracle HTTP Server WebGate
Applications are deployed in the JBoss Application Server protected with the JBoss
Agent. Additionally the request comes through an Oracle HTTP Server instance that is
configured with a WebGate. Both the WebGate and the JBoss Agent are configured
against the same Access Manager deployment. Here, the JBoss Agent plays the role of
an Identity Asserter that simply validates that the token forwarded by the WebGate is
valid and uses the identity established by the WebGate.
58.2.3 Sample Integration Topology
Figure 58–3 illustrates the topology used in this chapter for integration between Access
Manager and JBoss.
Figure 58–3 Sample Integration Topology
Details for this deployment are described in "Preparing Your Environment for JBoss
5.x Integration" on page 58-9.
Use Cases
The topology in Figure 58–3 supports:
■Protecting Web Applications
This use case is Application specific and JBoss specific. It uses Access Manager
SSO with the JBoss Agent and an authorization policy for browsers accessing Web
applications on JBoss (with local EJB invocation, if any).
–Access Manager (Host 1)
Preparing Your Environment for JBoss 6.x Integration
Integrating JBoss with Access Manager 58-7
–Application hosted on JBoss Application Server (Host 2)
■Invoking Secured EJBs using Rich Java Clients
The client can access an EJB in different ways depending on the client architecture,
as follows:
a. Configure the JAAS-compliant Login Module on the JBoss Container to secure
access to the EJB. The client can then make use of JBoss-specific mechanism to
propagate the Access Manager SSO token to the JBoss Container.
The client can either make use of an already procured Access Manager SSO
token or the client can use the JAAS-compliant Access Manager Login Module
to obtain the SSO token based on user's credentials.
b. Alternatively, the Access Manager SSO token can be obtained using a custom
HTTP Web server-based Access Manager Authentication Service exposed to
Rich Java clients.
■EJB invocation as a Web Service Provider (WSP)
JAAS-compliant Access Manager Login Module can be configured on the Web
Service Provider side to validate the Username and Password or the SSO Token.
Alternatively: If only the Username is available for Web Services Consumption
(WSC), you need the WSP requiring the SAML token issued by Security Token
Service asserting the Username, followed by invocation of JAAS-compliant Access
Manager Login Module with extra username-only assertion capability).
–Secure EJB access using the JAAS-compliant Access Manager Login Module
on (Host 2)
–Host the EJB Application on the JBoss server (Host 2)
–Access Manager (Host 1)
Remaining sections in this chapter describe how to complete this integration.
58.3 Preparing Your Environment for JBoss 6.x Integration
This section describes how to integrate JBoss Enterprise Application Platform (EAP)
6.x Application Server with Oracle Access Manager. It includes information regarding
the Access Manager Access SDK and JBoss Agent.
1. Check the latest support information on:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification
-100350.html
2. Host 1: Install Access Manager as described in Oracle Fusion Middleware Installation
Guide for Oracle Identity Management.
3. Host 2:
a. Install JBoss EAP 6.x Application Server, as described in your JBoss
installation guide.
b. Set JAVA_HOME environment variable.
c. Edit JBoss standalone.xml/domain.xml to change host from 127.0.0.1 to
0.0.0.0. For example:
JBoss_install_directory\standalone\configuration\standalone.xml
From
Preparing Your Environment for JBoss 6.x Integration
58-8 Administrator's Guide for Oracle Access Management
<wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
To
<wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
4. Host 2: install the Access Manager Access SDK, as described in the Oracle Fusion
Middleware Installation Guide for Oracle Identity and Access Management.
5. Host 2: create a Global module. For example:
a. Create a directory at
JBoss_install_
directory\modules\system\layers\base\mymodule\main
b. Create
module.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="mymodule">
<resources>
<resource-root path="j2eeagent.jar"/>
<resource-root path="oamasdk-api.jar"/>
<resource-root path="jbossweb-service.jar"/>
<resource-root path="jps-api.jar"/>
</resources>
<dependencies>
<module name="javax.servlet.api"/>
<module name ="javax.xml.bind.api"/>
<module name="org.jboss.logging"/>
<module name="javax.api"/>
<module name="org.jboss.as.web"/>
</dependencies>
</module>
6. Host 2: install the OAM JBoss Agent.
a. Download the JBoss Agent ZIP file and extract the files.
For supported JBoss EAP 6.x versions, the JBoss agent is supplied as JAR files
in patch 19440119. Download the referenced patch from My Oracle Support at
http://support.oracle.com/.
b. From the /agentconfig/oam_config.properties file, copy
oam-authenticatorvalve.jar and j2eeagent.jar to JBoss_install_
directory\modules\system\layers\base\mymodule\main
c. Download the JBossWeb jar from
http://www.java2s.com/Code/JarDownload/jbossweb/jbossweb-service.jar.
zip and copy it’s jbossweb-service.jar to JBoss_install_
directory\modules\system\layers\base\mymodule\main
7. Host 2: configure the Global module
a. Open jboss_install_directory/standalone/configuration/standalone.xml(for
standalone) or domain.xml (for multi structure)
b. Under “jboss:domain:ee” subsystem, add below line:
<global-modules>
<module name="mymodule" slot="main"/>
</global-modules>
8. Proceed to "Protecting JBoss-Specific Resources" and do the following procedures.
a. "Registering the JBoss Agent with Automatic Policy Creation"
Preparing Your Environment for JBoss 5.x Integration
Integrating JBoss with Access Manager 58-9
b. "Creating a Custom Policy for JBoss Resource Protection"
9. Proceed to "Protecting Web Applications with the JBoss Agent" and do the
following procedures.
a. "Creating Configuration Properties for the JBoss Agent"
b. "Mapping the Filter in the Application's web.xml File"
10. Configure the JBoss Login Module to use Access Manager policies.
a. Open jboss_install_directory/standalone/configuration/standalone.xml(for
standalone) or domain.xml (for multi structure)
b. Under the “jboss:domain:security” subsystem, add a new security-domain as
follows:
<security-domain name="oamrealm" cache-type="default">
<authentication>
<login-module code="oracle.security.am.agent.common.
jaas.login.OAMLoginModule" flag="required">
<module-option name="loginType" value="tokenBased"/>
<module-option name="configPath"
value="/scratch/lovagarw/jboss/config/"/>
<module-option name="publicAuthnResourceName" value="/Authen/Basic"/>
<module-option name="rolesParam" value="OAM_GROUPS"/>
<module-option name="publicAuthzResourceName"
value="/Authen/SSOToken"/>
</login-module>
</authentication>
</security-domain>
c. Deploy the application.
d. Start JBoss using the following command:
JBoss_install_dir\bin\standalone.bat
58.4 Preparing Your Environment for JBoss 5.x Integration
The following procedure describes how to prepare your environment for integrating
JBoss Application Server with Access Manager.
1. Check the latest support information on:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification
-100350.html
2. Host 1: Install Access Manager as described in Oracle Fusion Middleware
Installation Guide for Oracle Identity Management.
3. Host 2:
Note: ■Valve is not currently supported at the Global level.
■The JBoss agent codebase libraries are not updated during this
procedure.
■Role based authorization in EJB is not working in EAP when
trying to create the authentication token on the client side via
OAMLoginModule and trying to propagate the authentication
token to the JBoss server via the ClientLoginModule class.
Protecting JBoss-Specific Resources
58-10 Administrator's Guide for Oracle Access Management
a. Install JBoss 5.1.0 Application Server, as described in your JBoss installation
guide.
b. Edit JBoss server.xml to change <Engine name="jboss.web"
defaultHost="localhost"> to <Engine name="jboss.web"
defaultHost="0.0.0.0">. For example:
JBoss_install_directory\server\default\deploy\jbossweb.sar\server.xml
From
<Engine name="jboss.web" defaultHost="localhost">
To
<Engine name="jboss.web" defaultHost="0.0.0.0">
4. Host 2, Install the Access Manager Access SDK, as described in the Oracle Fusion
Middleware Installation Guide for Oracle Identity and Access Management.
5. Host 2, Install OAM JBoss Agent.
For supported JBoss EAP 5.x versions, the JBoss agent is supplied as JAR files in
controlled patch 14635540. Download the referenced patch from My Oracle
Support at http://support.oracle.com/.
a. Extract
oam-j2eeagent.zip
:
From
/agentconfig/oam_config.properties
file
b. Copy
oam-authenticatorvalve.jar
and
j2eeagent.jar
:
To
JBoss_install_directory\server\default\lib
6. Proceed to "Protecting JBoss-Specific Resources" and do the following procedures.
a. "Registering the JBoss Agent with Automatic Policy Creation"
b. "Creating a Custom Policy for JBoss Resource Protection"
58.5 Protecting JBoss-Specific Resources
This task is JBoss specific and is required for all JBoss integration use cases: protecting
applications, Web Services, or EJBs. The following sections describe how to create a
JBoss Agent registration (which includes defining protected resources) and configure
authorization policies for use with the JBoss Agent.
■Registering the JBoss Agent with Automatic Policy Creation
■Creating a Custom Policy for JBoss Resource Protection
58.5.1 Registering the JBoss Agent with Automatic Policy Creation
For this task, you can use either the Oracle Access Management Console as described
in this section, or remote registration as described elsewhere in the Oracle Fusion
Middleware Administrator's Guide for Oracle Access Management.
For communication between Access Manager and the JBoss Agent, you can use Open,
Simple, or Cert Security Mode. Configuring the JBoss Agent to use Simple or Cert
mode signals the Java ASDK to operate in the same mode. During registration, a new
file system directory is created for the agent on the Oracle Access Management
Protecting JBoss-Specific Resources
Integrating JBoss with Access Manager 58-11
Console host (AdminServer). After registration, you copy artifacts to the Agent
directory path:
■ObAccessClient.xml
■password.xml (Simple or Cert mode only)
■oamclient-keystore.jks - see "Setting Up The Keystore" in Oracle Fusion
Middleware Developer's Guide for Oracle Access Management.
In the following procedure you will create a fresh registration for a 10g OAM Agent.
Replace variables with values for your environment. This example uses Cert mode.
Your deployment will be different.
1. Go to the Oracle Access Management Console (host 1) and log in using
Administrator credentials. For example:
https://host1:port/oamconsole
User: adminuserID
Password ********
2. Click Application Security at the top of the window.
3. In the Launch Pad tab, click SSO Agent Registration in the Quick Start Wizards
section.
4. Select WebGate as the agent type and click Next.
5. Enter the following (and required details) to register this OAM Agent. For
example:
■Name: JBoss
■Vers ion: 10g
■Security: Cert (See Oracle Fusion Middleware Developer's Guide for Oracle
Access Management)
■User-defined Parameter:
logoutRedirectUrl=http://OAM_Server.domain.com:14100/oam/server/logout
6. Protected Resource List: Click the Add (+) button in this table and enter the
resources you want protected by the default Authentication and Authorization
policies:
/Authen/Basic
/Authen/SSOToken
7. Auto Create Policies: Check to create fresh policies and an Application Domain.
8. Click Apply to submit the registration.
9. Check the Confirmation window for the location of generated artifacts and then
close the window.
10. In the navigation tree, confirm the Agent name is listed.
11. Copy ObAccessClient.xml from the AdminServer to the JBoss Agent installation
directory path:
From:
$WLS_HOME/middleware/user_projects/domains/base_
domain/output/AGENTNAME
To:
D:\agentconfig
Protecting JBoss-Specific Resources
58-12 Administrator's Guide for Oracle Access Management
12. Proceed with "Creating a Custom Policy for JBoss Resource Protection".
58.5.2 Creating a Custom Policy for JBoss Resource Protection
In this task, you create a custom Authorization Policy to protect JBoss Agent-specific
resources and add responses that return the user groups as header variables. For
example, name the response
OAM_GROUPS
(with value
$user.groups
).
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, click Application Domains in the Access Manager section.
3. Search for the JBoss domain and open it for editing.
4. Authorization Policies:
a. Click the Authorization Policies node and click the Create (+) button.
b. In the Name field of the Summary tab, enter a unique name. For example:
Custom Authorization Policy
5. Add Resources: JBoss Agent-specific resources were defined during agent
registration.
a. Click the Resources tab on the Authorization Policy page.
b. Click the Add (+) button.
c. Click the Search button.
d. Choose a URL from the list, then click Add Selected:
/Authen/Basic
e. Repeat Steps a through d to add:
/Authen/SSOToken
f. Click Apply
6. Add Responses: Click the Responses tab, click the Add (+) button and:
■In the Name field, enter a unique name for this response:
OAM_GROUPS
.
■From the Type list, choose a response type (Header).
■In the Valu e field, enter a value for this response. For example:
$user.groups
7. Click Apply to save changes and close the Confirmation window.
8. Proceed to the proper topic for your deployment.
■Protecting Web Applications with the JBoss Agent
■Configuring the Login Module to Secure EJBs
■Configuring the Login Module to Secure Web Service Access
Note: For this custom authorization policy, the success and failure
redirect URLs are not needed because the single purpose of this policy
is to provide responses for an authorized user. If redirect URLs are
provided, no redirection occurs with the processing logic of the JBoss
Agent or Login Module.
Protecting Web Applications with the JBoss Agent
Integrating JBoss with Access Manager 58-13
58.6 Protecting Web Applications with the JBoss Agent
This section provides the following tasks required to protect Web Applications with
the JBoss Agent. Before beginning this section, deploy the application as usual.
■Creating Configuration Properties for the JBoss Agent
■Configuring the Authentication Valve
■Mapping the Filter in the Application's web.xml File
■Configuring the JBoss Login Module to Use Access Manager Policies
58.6.1 Creating Configuration Properties for the JBoss Agent
In this task, you copy Jboss Agent registration artifacts from the AdminServer to the
JBoss host and create a filter configuration properties file that is referenced later.
The JBoss Agent requires a configuration file (oam_config.properties) that defines a
number of critical properties. These include the file system path to the agent's
registration artifact (
ObAccessClient.xml
), the security domain defined in the JBoss
server's login configuration file, parameters and values that return to the JBoss Agent
during authentication, and an optional attribute to check for the presence of
authToken
in the request. Use this procedure to create a configuration properties file for the JBoss
Agent.
1. Create a JBoss Agent configuration file named oam_config.properties using the
following sample as a guide:
##Path of the folder containing the ObAccessClient.xml
configPath=D:\\agentconfig
##Name of the security domain as configured in JBoss's login-config.xml
realmName=oamrealm
##Optional. If not specified then defaults to /Authen/Basic
##publicAuthnResourceName=/Authen/Basic
##Optional. If not specified then defaults to http
##publicAuthnResourceType=http
##Optional. If not specified then defaults to GET
##publicAuthnResourceOperation=GET
##Optional. If not specified then defaults to /Authen/SSOToken
##publicAuthzResourceName=/Authen/SSOToken
##Optional. If not specified then defaults to http
##publicAuthzResourceType=http
##Optional. If not specified then defaults to GET
##publicAuthzResourceOperation=GET
rolesParam=OAM_GROUPS
##Optional. This attribute is responsible to check whether the credential in
##the subject / callback handler is an authn token. Defaults to authnToken.
Note: The JBoss Agent relies on the 11g Java ASDK which operates
in the same mode as the registered JBoss Agent.
Protecting Web Applications with the JBoss Agent
58-14 Administrator's Guide for Oracle Access Management
authToken=authToken
####################################
##### OAM logout related properties #####
####################################
##Host name of the OAM 11g Server
##oamHost=abchost.us.example.com
##Managed server port number of the OAM 11g Server
##oamPort=Port_value
2. Save oam_config.properties on the JBoss host:
/agentconfig/oam_config.properties
3. Proceed to "Configuring the Authentication Valve".
58.6.2 Configuring the Authentication Valve
This procedure must be performed to configure the Authentication Valve. There are
two options. Choose the one that is best suited to your environment:
■Adding the Authentication Valve to context.xml: This global configuration causes
the Authentication Valve to intercept all requests to the JBoss Agent.
■Adding the Authentication Valve to the Application's Deployment: Rather than
adding the Authentication Valve to context.xml for global use, you can add a
context.xml as part of the application's deployment. This configuration affects only
the concerned application (the Authentication Valve intercepts requests coming
only to this specific application).
58.6.2.1 Adding the Authentication Valve to context.xml
1. Locate and open for editing the JBoss Agent context.xml file in:
JBoss_install_dir\server\default\deploy\jbossweb.sar\context.xml
2. Add the following Valve entry and save the file:
<Valve
className="oracle.security.am.agent.common.authenticator.OAMAuthenticatorValve"
configFile="<full_path_to_oamagent_config_properties_file> " />
3. Proceed to "Mapping the Filter in the Application's web.xml File."
58.6.2.2 Adding the Authentication Valve to the Application's Deployment
1. Create a fresh context.xml file and store it under WEB-INF with web.xml:
JBoss_install_dir\server\default\deploy\jbossweb.sar\context.xml
2. Add the following Valve entry:
<?xml version="1.0" encoding="UTF-8"?>
<Context privileged="true">
Note: This procedure is not needed if you are Preparing Your
Environment for JBoss 6.x Integration as the Valve is not currently
supported at the Global level.
Protecting Web Applications with the JBoss Agent
Integrating JBoss with Access Manager 58-15
<Valve
className="oracle.security.am.agent.common.authenticator.OAMAuthenticatorValve"
configFile="<full_path_to_oamagent_config_properties_file> " />
</Context>
3. Redeploy the application.
4. Proceed to "Mapping the Filter in the Application's web.xml File."
58.6.3 Mapping the Filter in the Application's web.xml File
In this procedure, you add filter mapping for this integration to the application's
web.xml. You also add the name of the filter's configuration properties file.
1. Locate the web.xml file in the application EAR file:
my_app/WEB-INF/web.xml
2. Add the following filter mapping to the application's web.xml. For example:
<filter>
<filter-name>OAMFilterAgent</filter-name>
<filter-class>
oracle.security.am.agent.common.filter.OAMAuthenticationFilter
</filter-class>
<init-param>
<param-name>configFile</param-name>
<param-value>D:/oam_config.properties</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>OAMFilterAgent</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
3. Save the file.
4. Proceed to "Configuring the JBoss Login Module to Use Access Manager Policies."
58.6.4 Configuring the JBoss Login Module to Use Access Manager Policies
This procedure describes the required login module entry for JBoss to use Access
Manager policies. After you add filter mapping to web.xml, you redeploy the
application and start the JBoss Server.
1. Locate and open the login-config.xml file:
JBoss_install_dir\server\default\conf\login-config.xml
2. Add a new entry for the login module, as follows:
<application-policy name="oamrealm">
<authentication>
<login-module
Note: Starting JBoss Server using -b 0.0.0.0 allows the user to access
the server by the host name rather than
localhost / 127.0.0.1
.
Without this parameter, JBoss Server can be accessed using
localhost
/ 127.0.0.1
as well as the host name.
Configuring JBoss Server to Access a Host Name (not localhost)
58-16 Administrator's Guide for Oracle Access Management
code="oracle.security.am.agent.common.jaas.login.OAMLoginModule"
flag="required">
<module-option name="loginType">tokenBased</module-option>
<module-option name="configPath">D:/agentconfig</module-option>
<module-option>
<module-option
name="publicAuthnResourceName">/Authen/Basic</module-option>
<module-option name="rolesParam">OAM_GROUPS</module-option>
<module-option
name="publicAuthzResourceName">/Authen/SSOToken</module-option>
</login-module>
</authentication>
</application-policy>
The name of
application-policy
in this entry should have the same value as that
defined for the
realmname
property in
oam_config.properties
.
3. Deploy the application.
4. Start JBoss as follows using the following command:
JBoss_install_dir\bin\run –b 0.0.0.0
See "Configuring JBoss Server to Access a Host Name (not localhost)."
58.7 Configuring JBoss Server to Access a Host Name (not localhost)
This procedure is optional. Perform this only to access the JBoss Server using the host
name (rather than localhost/127.0.0.1).
1. On the JBoss Server host, locate the server.xml file in the following path:
JBoss_install_dir\server\default\deploy\jbossweb.sar\server.xml
2. Edit server.xml to change the default host, as follows:
From:
<Engine name="jboss.web" defaultHost="localhost">
To:
<Engine name="jboss.web" defaultHost="defaultHost="0.0.0.0">
3. Save server.xml.
58.8 Configuring the Login Module to Secure EJBs
This task involves both server-side and client-side configuration as documented in
following sections.
Note: This procedure is not used when "Preparing Your
Environment for JBoss 6.x Integration."
Note: Starting JBoss Server using -b 0.0.0.0 allows the user to access
the server using host name rather than localhost / 127.0.0.1.
Otherwise, JBoss Server can be accessed using localhost / 127.0.0.1 as
well as host name.
Configuring the Login Module to Secure EJBs
Integrating JBoss with Access Manager 58-17
■Configuring the Server to Secure EJBs
■Configuring the Client Side for Login Module to Secure EJBs
58.8.1 Configuring the Server to Secure EJBs
On the server side, you must add the security domain annotation to the EJB and add
descriptors to jboss.xml. You also add a new entry to the JBoss server configuration file
for the Login Module.
Securing EJBs, Web applications or a Web Service based on roles requires additional
configuration in login-config.xml as follows:
<module-option name="rolesParam">OAM_GROUPS</module-option>
Here OAM_GROUPS is the response configured when "Creating a Custom Policy for
JBoss Resource Protection" on page 58-12.
You can use either the agent configured in previous steps or a new agent.
1. Copy ObAccessClient.xml as follows (one or the other):
■From: $WLS_HOME/middleware/user_projects/domains/base_
domain/output/agent_name.
■To: A directory on the JBoss host.
2. Add the
@SecurityDomain("oamrealm")
annotation to the EJB. For example, if the
EJB class is DemoEJB the following should be added at the code level:
import org.jboss.security.annotation.SecurityDomain;
@SecurityDomain("oamrealm")
public class DemoEJB{ ... }
The
application-policy
defined as the value of
@SecurityDomain
(in this
example,
oamrealm
) should have the same value as that defined for the
realmname
property in
oam_config.properties
.
3. Option: Add the following descriptor to the
jboss.xml
file to define the security
domain.
META-INF/jboss.xml
<jboss>
<security-domain>java:/jaas/myother</security-domain>
</jboss>
The application-policy name defined in this descriptor (myother) should have the
same value as the realmname property defined in oam_config.properties.
Note: These procedures are not used when Preparing Your
Environment for JBoss 6.x Integration.
Note: To use a new agent you must copy the ObAccessClient.xml
from the /agent directory on the JBoss host to another directory.
Configuring the Login Module to Secure EJBs
58-18 Administrator's Guide for Oracle Access Management
4. JBoss Server Login Configuration: Add an entry for the Login Module class name,
which must be part of the login mechanism:
JBoss_install_dir\server\default\conf\login-config.xml
<application-policy name="oamrealm">
<authentication>
<login-module
code="oracle.security.am.agent.common.jaas.login.OAMLoginModule"
flag="required">
<module-option name="loginType">tokenBased</module-option>
<module-option name="configPath">D:/agentconfig</module-option>
<module-option name="rolesParam">OAM_GROUPS</module-option>
<module-option
name="publicAuthnResourceName">/Authen/Basic</module-option>
<module-option
name="publicAuthzResourceName">/Authen/SSOToken</module-option>
</login-module>
</authentication>
</application-policy>
5. Deploy the application.
6. Start JBoss using the following command:
JBoss_install_dir\bin\run –b 0.0.0.0
See "Configuring JBoss Server to Access a Host Name (not localhost)."
58.8.2 Configuring the Client Side for Login Module to Secure EJBs
This procedure describes how to create a client-login configuration file.
1. Copy ObAccessClient.xml as follows (one or the other):
■New Agent: From $MW_HOME/middleware/user_projects/domains/base_
domain/output/agent_name to a folder on the Agent host.
■Existing Agent: From its location on the JBoss host to another directory on the
Agent host.
2. On the client host, create a client-login configuration text file as follows:
oamauth {
oracle.security.am.agent.common.jaas.login.OAMLoginModule required
loginType="usernamePassword"
configPath="D:/agentconfig"
publicAuthzResourceName="/Authen/Basic"
publicAuthzResourceName="/Authen/SSOToken";
Note: The name associated with the security domain annotation
should be specified in the Login Module to be used, as described in
Step 4. See Also: Configuring the JBoss Login Module to Use Access
Manager Policies on page 58-15.
Note: The
name
value in the
application-policy
element should
match the
realmname
property value defined in
oam_
config.properties
.
Configuring the Login Module to Secure Web Service Access
Integrating JBoss with Access Manager 58-19
};
3. Add the following to your entry to configure the login module to propagate
identity to the EJB Container:
propagate {
org.jboss.security.ClientLoginModule required
restore-login-identity="true";
};
4. Save the file.
5. Rich Client: Add the following to the client code before invoking the EJB from the
Client side:
System.setProperty("java.security.auth.login.config", authFile);
MyCallbackHandler handler = new MyCallbackHandler(<USERNAME>,<PASSWORD>);
LoginContext lc = new LoginContext("oamauth", handler);
lc.login();
//Fetch the private credentials of type String.class
Set<String> set = lc.getSubject().getPrivateCredentials(String.class);
//Set the SSO Token in callback handler along with the username
handler = new MyCallbackHandler(<USERNAME>, set.iterator().next());
LoginContext lc2 = new LoginContext("propagate", handler);
lc2.login();
58.9 Configuring the Login Module to Secure Web Service Access
The Web Service Provider may provide for one of the various mechanisms to intercept
and handle the incoming web service SOAP message in order to enforce security on
the web service invocation.
This task involves both the server-side and client-side configuration as documented in
the following sections.
■Configuring the Server to Secure Web Services Access
■Configuring the Client to Secure Web Services Access
58.9.1 Configuring the Server to Secure Web Services Access
Configuring the Server to Secure Web Services Access involves copying Agent
registration artifacts, and adding the Access Manager JAAS-compliant Login Module
for Web Service security to the JBoss Server login-configuration file.
Note: Perform Step 5 while invoking EJBs from a Rich Client to
ensure that Access Manager performs authentication (using the Pure
Java ASDK) and then propagates the credentials to the EJB
Application Server.
Note: You can use either the agent configured in previous steps or a
new agent. To use a new agent you must copy the ObAccessClient.xml
from the /agent directory on the JBoss host, to another directory on
this host.
Configuring the Login Module to Secure Web Service Access
58-20 Administrator's Guide for Oracle Access Management
No specific details are provided for configuring or deploying a Web Service because
any of several frameworks can be used to create a Web Service. The provider of the
Web Services deployed on the JBoss Container should adhere to the following
guidelines in general:
■Include functionality to look for specific headers injected by the client order to
retrieve the OAM SSO token.
■Use the OAM JAAS Login Module to validate the OAM SSO token
■If any EJB Session Beans are exposed as Web Services, the JBoss-specific JAAS
Login Module
ClientLoginModule
must be used to propagate the OAM token to
the EJB container.
Use the following procedure to configure the server to secure Web Services access.
1. Copy ObAccessClient.xml as follows (one or the other):
■Existing Agent: From its location on the JBoss host to another directory on the
Agent host.
■New Agent: From $MW_HOME/middleware/user_projects/domains/base_
domain/output/agent_name to another directory on the Agent host.
2. Register the SOAP Handler with the Web Service (ideally using the .wsdd file).
The .wsdd file is generated when the WS stubs are created (and is located inside
the application's WEB-INF folder).
3. Edit the JBoss Server login-configuration file to add an entry for the Access
Manager JAAS-compliant Login Module for Web Service security, as follows:
JBoss_install_dir\server\default\conf\login-config.xml
<application-policy name="WSRealm">
<authentication>
<login-module
code="oracle.security.am.agent.common.jaas.login.OAMLoginModule"
flag="required">
<module-option name="loginType">tokenBased</module-option>
<module-option name="configPath">D:/agentconfig</module-option>
<module-option name="rolesParam">OAM_GROUPS</module-option>
<module-option
name="publicAuthnResourceName">/Authen/Basic</module-option>
<module-option
name="publicAuthzResourceName">/Authen/SSOToken</module-option>
</login-module>
</authentication>
</application-policy>
4. Save the JBoss Server login configuration file.
5. Deploy the application.
6. Start JBoss using the following command:
JBoss_install_dir\bin\run –b 0.0.0.0
See "Configuring JBoss Server to Access a Host Name (not localhost)."
7. Proceed to "Configuring the Client to Secure Web Services Access."
Validating Your Configuration
Integrating JBoss with Access Manager 58-21
58.9.2 Configuring the Client to Secure Web Services Access
In this task, you configure user authentication with the OAM Server and then create a
security header element, containing the SSO token, for the SOAP message.
1. On the WS-client: Perform user authentication with OAM Server and then create
a security header element, containing the SSO token, for the SOAP message.
2. Invoke the Web service, as usual.
3. Proceed with "Configuring Logging for the JBoss Agent and Login Module".
58.10 Configuring Logging for the JBoss Agent and Login Module
The JBoss Agent and the Login Module are both equipped with logging messages at
various log levels. To log these messages, you must edit the jboss-log4j.xml file as
described in this procedure.
1. Locate the jobss-log4j.xml file in the following path:
$JBOSS_HOME/server/default/conf/jboss-log4j.xml
2. Open the file in an editor and add the following information:
<appender name="J2EEAGENT"
class="org.jboss.logging.appender.DailyRollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.log.dir}/j2eeagent.log"/>
<param name="Append" value="true"/>
<param name="DatePattern" value="'.'yyyy-MM-dd"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] (%t) %m%n"/>
</layout>
</appender>
<category name="oracle.security.am.agent.common">
<appender-ref ref="J2EEAGENT"/>
</category>
<root>
...
<appender-ref ref="J2EEAGENT"/>
</root>
3. Save the file.
58.11 Validating Your Configuration
There is no specific mechanism to validate your configuration. However, you can
manually determine whether the configuration is correctly functioning by doing the
following and recognizing the response.
1. Authorized User: Invoke the Web Service manually by providing the SSO token
generated for the user who is authorized to invoke the Web Service.
Note: Ideally, this step is performed before invoking a Web Service
method, which means that this code must be added in the client code
while invoking the Web Service.
Validating Your Configuration
58-22 Administrator's Guide for Oracle Access Management
■Success: The authorized user is granted access.
■Failure: The authorized user is denied access.
■Error: The configuration is incorrect. Review the OAM Server logs for the
entries generated by the Login Module.
2. Unauthorized User: Invoke the Web Service manually and provide the SSO token
for a non-authorized user.
■Success: The unauthorized user is denied access.
■Failure: The unauthorized user is granted access.
■Error: If any error occurs, the configuration is incorrect. Review the OAM
Server logs for the entries generated by the Login Module.
59
Integrating Microsoft SharePoint Server with Access Manager 59-1
59
Integrating Microsoft SharePoint Server with
Access Manager
This chapter explains how to integrate Access Manager with a 10g WebGate and
Microsoft SharePoint Server. It covers the following topics:
■What is Supported in This Release?
■Introduction to Integrating With the SharePoint Server
■Integration Requirements
■Preparing for Integration With SharePoint Server
■Integrating With Microsoft SharePoint Server
■Setting Up Microsoft Windows Impersonation
■Completing the SharePoint Server Integration
■Integrating With Microsoft SharePoint Server Configured With LDAP Membership
Provider
■Configuring Single Sign-On for Office Documents
■Configuring Single Sign-off for Microsoft SharePoint Server
■Setting Up Access Manager and Windows Native Authentication
■Synchronizing User Profiles Between Directories
■Testing Your Integration
■Troubleshooting
59.1 What is Supported in This Release?
Support for integration between Access Manager and SharePoint enables the following
functionality:
Note: Access Manager with a 10g WebGate supports both Microsoft
SharePoint Server 2010 and Microsoft SharePoint Server 2013. Other
versions of Microsoft SharePoint Server are not supported in this
release.
Unless explicitly stated, all details in this chapter apply equally to
Access Manager integration with Microsoft SharePoint Server using
the OAM impersonation plug-in, and Microsoft SharePoint Server
configured with the LDAP Membership Provider.
Introduction to Integrating With the SharePoint Server
59-2 Administrator's Guide for Oracle Access Management
■When a user accesses SharePoint before SSO login with Access Manager, the user
is prompted for Access Manager SSO login credentials.
■When a user with a valid Access Manager login session wants to access SharePoint
documents, he must be established with SharePoint (logged in and authenticated
with SharePoint). Once the Access Manager session is established, it is also
respected by SharePoint for integration with Access Manager and SharePoint
using LDAP Membership Provider, OAM WNA, and impersonation. Based on
authentication status, SharePoint either allows or denies access to documents
stored in SharePoint.
■When a user opens an Office document from SharePoint using a browser, the SSO
session should persist into the MS Office program so that access to the document
through the MS Office program is maintained. See "Configuring Single Sign-On
for Office Documents" on page 59-32.
■Full feature parity with SharePoint integration with Access Manager 10g is
provided to ease upgrades.
59.2 Introduction to Integrating With the SharePoint Server
SharePoint Server is a Microsoft-proprietary secure and scalable enterprise portal
server that builds on Windows Server Microsoft Internet Information Services (IIS) and
Windows SharePoint Services (WSS). SharePoint Server is typically associated with
Web content and document management systems. SharePoint Server works with
Microsoft IIS web server to produce sites intended for collaboration, file sharing, web
databases, social networking and web publishing. In addition to WSS functionality,
SharePoint Server incorporates additional features such as News and Topics as well as
personal and public views for My Site, and so on.
Microsoft SharePoint Server enhances control over content, business processes, and
information sharing. Microsoft SharePoint Server provides centralized access and
control over documents, files, Web content, and e-mail, and enables users to submit
files to portals for collaborative work.
SharePoint server farms can host web sites, portals, intranets, extranets, Internet sites,
web content management systems, search engine, wikis, blogs, social networking,
business intelligence, workflow as well as providing a framework for web application
development.
When integrated with Microsoft SharePoint Server, Access Manager handles user
authentication through an ISAPI filter and an ISAPI Module. This enables single
sign-on between Access Manager and SharePoint Server.
SharePoint Server supports the following authentication methods:
■Form Based Authentication
■Impersonation Based Authentication
■Windows Authentication: Used only for the configuration where the information
about the users is stored in Active Directory server
The integrations in this chapter provide single sign-on to Microsoft SharePoint Server
resources and all other Access Manager protected resources. For more information,
see:
Note: 11g WebGates are not supported on the IIS Web server. Only
the WebGate 10g WebGate for IIS can be used for this integration.
Introduction to Integrating With the SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-3
■About Windows Impersonation
■About Form Based Authentication With This Integration
■About Authentication With Windows Impersonation and SharePoint Server
Integration
■About Access Manager and Windows Native Authentication
59.2.1 About Windows Impersonation
Unless explicitly stated, the integrations described in this chapter rely on Windows
impersonation.
Windows impersonation enables a trusted user in the Windows server domain to
assume the identity of any user requesting a target resource in Microsoft SharePoint
Server. This trusted impersonator maintains the identity context of the user while
accessing the resource on behalf of the user.
Impersonation is transparent to the user. Access appears to take place as if the
SharePoint resource were a resource within the Access System domain.
59.2.2 About Form Based Authentication With This Integration
You can integrate Access Manager with SharePoint Server using any of the three
authentication methods. Given common use of LDAP servers (Sun Directory Server
and Active Directory for instance), your integration can include any LDAP server.
Form-based authentication in SharePoint Server is claims-aware. When a user enters
credentials on the Forms login page of SharePoint Relying Party (RP), these are passed
to the SharePoint Security Token Service (STS). SharePoint STS authenticates the users
against its membership provider and generates the SAML token, which is passed to
SharePoint RP. SharePoint RP validates the SAML token and generates the FedAuth
cookie. The user is then allowed to access the SharePoint RP site.
With form-based authentication, the WebGate is configured as an ISAPI filter. The
form login page of SharePoint RP is customized such that the user is not challenged to
enter the credentials by the SharePoint RP. Also, the membership provider is
customized such that it just validates the ObSSOCookie set by the WebGate to
authenticate the user.
The following overview outlines the authentication flow for this integration using
form-based authentication.
Process overview: Request processing with form-based authentication
1. The user requests access to an SharePoint Server RP site.
Note: Windows impersonation is not used when integrating
Microsoft SharePoint Server configured with the LDAP Membership
Provider.
Note: The WebGate only supports Form Based Authentication using
the HTTP validation method (
OAMHttp
validation mode). The ASDK
validation method (
OAMsdk
validation mode) is not supported for
Form Based Authentication.
Introduction to Integrating With the SharePoint Server
59-4 Administrator's Guide for Oracle Access Management
2. The WebGate protecting the site intercepts the request, determines if the resource
is protected, and challenges the user.
3. The user enters their OAM credentials. Next the OAM WebGate server verifies the
credentials from LDAP and authenticates the user.
The WebGate generates the OAM native SSO cookie (ObSSOCookie), which
enables single sign-on and sets the User ID header variable (to the user name) in
the HTTP request and redirects the user to the SharePoint RP site.
4. The SharePoint RP custom login page is invoked, which sets the user name to the
user ID passed in the header variable, and sets the password to the ObSSOCookie
value. The login page also automatically submits these credentials to the
SharePoint RP site.
5. The SharePoint RP site passes the credentials to SharePoint STS, which invokes the
custom membership provider to validate the user credentials.
6. The custom membership provider gets the ObSSOCookie value (passed as a
password) and sends it as part of the HTTP request to a resource protected by the
WebGate to validate the ObSSOCookie.
7. If the ObSSOCookie is valid, SharePoint STS generates the SAML token and passes
it to SharePoint RP.
8. SharePoint RP validates the SAML token and generates the FedAuth cookie. The
user is then allowed to access the SharePoint RP site.
59.2.3 About Authentication With Windows Impersonation and SharePoint Server
Integration
As described earlier, Windows impersonation enables a trusted user in the Windows
server domain to assume the identity of any user requesting a target resource in
SharePoint Portal Server. This trusted impersonator maintains the identity context of
the user while accessing the resource on behalf of the user. Impersonation is
transparent to the user. Access appears to take place as if the SharePoint resource were
a resource within the OAM Server domain. Windows based integration with
SharePoint Server 2010 and 2013 is the same as the supported integration with
SharePoint 2007.
The next overview identifies the authentication processing flow with SharePoint
Server and Windows impersonation enabled.
Process overview: Integration Authentication with Windows Impersonation
1. The user requests access to a SharePoint Portal Server resource.
2. The WebGate ISAPI filter protecting SharePoint Portal Server intercepts the
request, determines whether the target resource is protected, and if it is, challenges
the user for authentication credentials.
3. If the user supplies credentials and the OAM Server validates them, the WebGate
sets an ObSSOCookie in the user's browser, which enables single sign-on. The
Note: With the SharePoint 2007 integration, the Access Manager
ISAPI extension (
IISImpersonationExtension.dll
) was used.
Because the internal architecture of event handing changed with
SharePoint 2010, Access Manager has changed the ISAPI extension to
an HTTP module.
Introduction to Integrating With the SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-5
WebGate also sets an HTTP header variable named "impersonate," whose value is
set to one of the following:
■the authenticated user's LDAP
uid
■
samaccountname
, if the user account exists in Active Directory
4. The Access Manager HTTP module
IISImpersonationModule.dll
checks for the
Authorization Success Action header variable named
impersonate
.
5. When the header variable exists, the Oracle ISAPI module obtains a Kerberos
ticket for the user.
This Service for User to Self (S4U2Self) impersonation token enables the
designated trusted user to assume the identity of the requesting user and obtain
access to the target resource through IIS and the SharePoint Portal Server.
59.2.4 About Access Manager and Windows Native Authentication
Access Manager provides support for Windows Native Authentication (WNA). Your
environment may include:
■Windows 2008/R2 or 2012/R2 server
■Internet Information services (IIS) 7.x or 8.x
■Active Directory
If the user's directory server has, for example, an NT Logon ID, or if the user name
is the same everywhere, then a user is able to authenticate into any directory
server. The most common authentication mechanism on Windows Server 2008 is
Kerberos.
The use of WNA by Access Manager is seamless. The user does not notice any
difference between a typical authentication and WNA when they log on to their
desktop, open an Internet Explorer (IE) browser, request a protected web resource, and
complete single sign-on.
Process overview: Using WNA for authentication
1. The user logs in to the desktop computer, and local authentication is completed
using the Windows Domain Administrator authentication scheme.
2. The user opens an Internet Explorer (IE) browser and requests an Access
System-protected Web resource.
3. The browser notes the local authentication and sends a Kerberos token to the IIS
Web server.
4. The WebGate installed on the IIS Web server sends the Kerberos token to the OAM
11g sever. The OAM 11g Server negotiates the Kerberos token with the KDC (Key
distribution center).
5. Access Manager sends authentication success information to the WebGate.
6. The WebGate creates an ObSSOCookie and sends it back to the browser.
7. Access Manager authorization and other processes proceed as usual.
Note: Ensure that Internet Explorer’s security settings for the
Internet and (or) intranet security zones are adjusted properly to allow
automatic logon.
Integration Requirements
59-6 Administrator's Guide for Oracle Access Management
The maximum session time-out period configured for the WebGate is applicable to
the generated ObSSOCookie.
59.3 Integration Requirements
Unless explicitly stated, this section introduces components required for integrations
described in this chapter. It includes the following topics:
■Confirming Requirements
■Required Access Manager Components
■Required Microsoft Components
59.3.1 Confirming Requirements
References to specific versions and platforms are for demonstration purposes. For the
latest Access Manager certification information, see the certification matrix on Oracle
Technology Network at:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
59.3.2 Required Access Manager Components
Access Manager provides access and security functions, including Web-based single
sign-on, policy management, reporting, and auditing. When integrated with Microsoft
SharePoint Server, Access Manager handles user authentication through an ISAPI filter
and an ISAPI Module, which enables single sign-on between the two products.
The components in Table 59–1 are required to integrate with Microsoft SharePoint
Server (or Microsoft SharePoint Server configured with LDAP Membership Provider.)
Table 59–1 Component Requirements
Component Description
10g WebGate The ISAPI version 10g WebGate must reside on the same computer
as the SharePoint Server.
Within the context of this integration, this WebGate is an ISAPI
filter that intercepts HTTP requests for Web resources and forwards
them to the OAM Server to authenticate the user who made the
request. If authentication is successful, the WebGate creates an
ObSSOCookie and sends it to the user's browser, thus facilitating
single sign-on. The WebGate also sets impersonate as a HeaderVar
action for this user session.
For LDAP Membership Provider Scenario: See "Integrating With
Microsoft SharePoint Server Configured With LDAP Membership
Provider" on page 59-23.
IISImpersonationModule.dll
This IIS-native module is installed with the WebGate. The
IISImpersonationModule.dll
module determines whether the
Authorization Success Action HeaderVar has been set to
impersonate and, if it has, the DLL file creates a Kerberos S4U2Self
ticket that enables the special trusted user in the SharePoint Server
Active Directory to impersonate the user who originally made the
request.
After a WebGate installation, you must configure
IISImpersonationModule.dll
manually to enable impersonation
and this integration.
For LDAP Membership Provider Scenario: Do not configure
IISImpersonationModule.dll
.
Integration Requirements
Integrating Microsoft SharePoint Server with Access Manager 59-7
59.3.3 Required Microsoft Components
Minimum requirements dictate a 64-bit, four cores processor. However, references to
specific versions and platforms are for demonstration purposes. For the latest Access
Manager certification information, see the following Microsoft library location for
Microsoft SharePoint Server:
https://technet.microsoft.com/en-us/library/cc262485.aspx
The SharePoint multi-purpose platform allows for managing and provisioning of
intranet portals, extranets, and Web sites; document management and file
management; collaboration spaces; social networking tools; enterprise search and
intelligence tooling; process and information integration; and third-party developed
solutions.
Table 59–2 describes the other components required for this integration.
Directory Server Access Manager can be connected to any supported directory
server including, but not limited to, LDAP and Active Directory.
Access Manager can even connect to the same instance of Active
Directory used by SharePoint Server.
In any case, the directory is not required on the same machine as
SharePoint Server and the protecting WebGate.
OAM Server The integration also requires installation of the OAM Server with
which the WebGate protecting your SharePoint Server installation
is configured to inter-operate.
Except for the WebGate protecting SharePoint Server, your
components do not need to reside on the machine hosting
SharePoint Server.
See Also: "Preparing for Integration With SharePoint Server" on
page 59-8.
Note: Minimum requirements dictate a 64-bit, four cores processor.
However, references to specific versions and platforms are for
demonstration purposes. For the latest Access Manager certification
information, see Oracle Technology Network at:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-c
ertification-100350.html
See Also: The following library location for Microsoft SharePoint
Server and access to applicable software:
http://technet.microsoft.com/en-us/library/cc262485.aspx
Table 59–2 Microsoft Requirements for this Integration
Component Description
Custom Login Page for
SharePoint site
When the user tries to access a SharePoint site configured to use Form
Based Authentication, the user is redirected to a login page where the
user enters his or her credentials (user name and password). The
custom login page passes the credentials to the SharePoint site.
Table 59–1 (Cont.) Component Requirements
Component Description
Preparing for Integration With SharePoint Server
59-8 Administrator's Guide for Oracle Access Management
59.4 Preparing for Integration With SharePoint Server
Tasks in the following procedure are required for all integration scenarios described in
this chapter.
After installing and testing Microsoft components, perform steps here to install Access
Manager for your integration. This task applies to both integration scenarios in this
chapter. To avoid repetition, information here is not repeated elsewhere.
The ISAPI 10g WebGate must be installed on the same computer as the SharePoint
Server. Other components in this integration can reside on the same host as the
WebGate or any other computer in your deployment (Solaris, Linux, or Windows
platforms). A different host can be set up for Active Directory or some other directory
service. If both Access Manager and SharePoint Server are set up for different
instances of Active Directory, both instances must belong to the same Active Directory
domain.
SharePoint site You create the SharePoint site using the SharePoint Central
Administration application. The site is configured to use Form Based
Authentication as the authentication method by following the steps
mentioned in
http://technet.microsoft.com/en-us/library/ee806890.aspx
.
The SharePoint site passes the user credentials to the SharePoint STS
that generates SAML token upon successful ObSSOCookie validation
by the custom membership provider. The SharePoint site also
generates FedAuth cookie upon receiving the SAML token from
SharePoint STS. The SharePoint site passes the FedAuth cookie to the
user so that he/she can access the SharePoint site.
SharePoint Security Token Service
(STS)
The SharePoint site passes the user credentials (user name and
password) to SharePoint STS, which invokes the custom membership
provider and passes the credentials to it. Once the custom
membership provider validates the ObSSOCookie passed to it, the
SharePoint STS generates the SAML token for the user that is passed
to the SharePoint Relying Party (RP).
Custom Membership Provider for
SharePoint STS
The SharePoint STS invokes the membership provider (configured
with Form Based Authentication). STS passes the user credentials and
the URL for the IIS resource (configured in
web.config
on the
SharePoint site) to the custom membership provider for cookie
validation.
The membership provider is customized such that it returns success if
the ObSSOCookie value passed to it is valid.
The custom membership provider library
(
OAMCustomMembershipProvider.dll
) is packaged and installed with
the 10g WebGate for IIS Web server. You must deploy the library in the
global assembly cache of the SharePoint Server host.
The
CustomMembershipProvider
class is derived from
LdapMembershipProvider
class present in the
Microsoft.Office.Server.Security
namespace.
IIS resource for Cookie validation Configure the URL for the IIS resource in the SharePoint site’s
web.config
file.
For the HTTP validation method, the WebGate intercepts the request
sent by the custom membership provider, extracts the ObSSOCookie
from the request, and validates it. If the cookie is valid, then the
request is redirected to the IIS resource, which returns the response
with a 200 (OK) status code to the custom membership provider.
Otherwise, a 403 (Forbidden) error code is returned to the custom
membership provider.
Table 59–2 (Cont.) Microsoft Requirements for this Integration
Component Description
Preparing for Integration With SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-9
Prerequisites
Install and test Microsoft components described in "Required Microsoft Components"
on page 59-7.
To prepare for integration with SharePoint Server
1. Install Oracle Identity Management and Access Manager as described in the Oracle
Fusion Middleware Installation Guide for Oracle Identity Management.
2. Register a 10g WebGate for IIS Web server with Access Manager:
a. Log in to the Oracle Access Management Console. For example:
http://
host:port
/oamconsole
.
b. Click Application Security at the top of the window.
c. In the Launch Pad tab, click SSO Agent Registration in the Quick Start
Wizards section.
d. Select WebGate as the agent type and click Next.
e. Set the agent version to 10g and enter required details (those with an *):
Name
SharePoint user name and password
Security mode (Agent host must match OAM Server)
Auto Create Policies (Checked)
f. Protected Resource List: In this table, enter individual resource URLs to be
protected by this OAM Agent.
g. Public Resource List: In this table, enter individual resource URLs to be public
(not protected).
h. Click Apply to submit the registration, check the Confirmation window for
the location of generated artifacts, then close the window.
3. Proceed as follows:
■Install a fresh WebGate: Continue with steps 6, 7, and 8.
■Existing WebGate on SharePoint Host: Skip to "Integrating With Microsoft
SharePoint Server" on page 59-10.
4. Locate and download the 64-bit ISAPI WebGate installer as follows:
a. Go to Oracle Fusion Middleware 11gR1 Software Downloads at:
https://www.oracle.com/technology/software/products/middleware/htdocs/fmw_
11_download.html
b. Click Accept License Agreement, at the top of the page.
c. From the Access Manager Webgates (10.1.4.3.0) row, click the download link
for the desired platform and follow on-screen instructions.
Note: Do not specify a Base URL.
Note: Only 64-bit ISAPI WebGates are supported as described in
"Integrating With Microsoft SharePoint Server Configured With LDAP
Membership Provider" on page 59-23.
Integrating With Microsoft SharePoint Server
59-10 Administrator's Guide for Oracle Access Management
d. Store the WebGate installer in the same directory as any 10g (10.1.4.3) Access
System Language Packs you want to install.
5. Launch the WebGate installer for your platform, installation mode, and Web
server.
Follow these steps:
a. Follow on-screen prompts.
b. Provide Administrator credentials for the Web server.
c. Language Pack—Choose a Default Locale and any other Locales to install,
then click Next.
d. WebGate installation begins (
IISImpersonationModule.dll
will be installed in
WebGate_install_dir
\access\Oblix\apps\Webgate\bin\
).
6. Before updating the Web server configuration, copy WebGate artifacts from the
Admin Server to the computer hosting the WebGate.
a. On the computer hosting the Oracle Access Management Console
(AdminServer), locate and copy ObAccessClient.xml (and any certificate
artifacts):
$DOMAIN_HOME
/output/
$Agent_Name
/
ObAccessClient.xml
password.xml
(if needed)
aaa_key.pem
(your private key generated by openSSL)
aaa_cert.pem
(signed certificates in PEM format)
b. On the OAM Agent host, add the artifacts to the WebGate path. For example:
WebGate_install_dir
/access/oblix/lib/ObAccessClient.xml
WebGate_install_dir
/access/oblix/config
c. Restart the WebGate Web server.
d. (Optional.) Restart the OAM Server that is hosting this Agent. This step is
recommended but not required.
7. Proceed as needed to complete this integration within your environment:
■Integrating With Microsoft SharePoint Server
■Integrating With Microsoft SharePoint Server Configured With LDAP
Membership Provider
59.5 Integrating With Microsoft SharePoint Server
The following overview outlines the tasks that you must perform for this integration
and the topics where you will find the steps and details.
The custom membership provider library (
OAMCustomMembershipProvider.dll
) is
packaged and installed with the 10g WebGate for IIS Web Server. You must deploy the
library in the global assembly cache of the computer hosting SharePoint Server as
outlined next.
Task overview: Integrating with Microsoft SharePoint Server includes
1. Performing prerequisite tasks:
■Installing "Required Microsoft Components" on page 59-7.
Integrating With Microsoft SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-11
■"Preparing for Integration With SharePoint Server" on page 59-8
2. Creating a new Web application (or site application) in SharePoint Server is
described in following topics:
■"Creating a New Web Application in Microsoft SharePoint Server" on
page 59-11
■Creating a New Site Collection for Microsoft SharePoint Server on page 59-13
3. "Setting Up Microsoft Windows Impersonation" on page 59-14 (not used with
LDAP Membership Provider).
4. "Completing the SharePoint Server Integration" on page 59-22.
5. "Configuring Single Sign-off for Microsoft SharePoint Server" on page 59-33.
6. "Synchronizing User Profiles Between Directories" on page 59-37.
7. "Testing Your Integration" on page 59-37.
59.5.1 Creating a New Web Application in Microsoft SharePoint Server
You perform this task when integrating with Microsoft SharePoint Server, with or
without LDAP Membership Provider.
Prerequisites
Installing Microsoft components. See "Required Microsoft Components" on page 59-7.
To create a new Web application in Microsoft SharePoint Server
1. On the host where SharePoint Server is installed, open the Central Administration
home page: Start, All Programs, SharePoint Products, SharePoint, Central
Administration.
2. From the Central Administration home page, click Application Management.
3. From the Application Management page, Web Applications section, click Manage
Web Applications.
4. In the top-left corner, click the New button to create a new web application.
5. Configure the items in Table 59–3 on the Create New Web Application page:
Table 59–3 Create Web Application Options for Microsoft SharePoint Server
Section What You Configure in This Section
Authentication In this section you select either Claim Based Authentication or Classic
Mode Authentication, as appropriate.
Integrating With Microsoft SharePoint Server
59-12 Administrator's Guide for Oracle Access Management
IIS Web Site In this section you configure the following settings for your new Web
application, as follows:
■To choose an existing Web site, click Use an Existing Web Site...
■To create a new site, click Create.
■In the Port field, enter the port number you want to use to access
the Web application.
For a new Web site, this field contains a default port number. For
an exiting site, this field contains the currently configured port
number.
■In the optional Host Header field, enter the URL for accessing the
Web application.
■In the Path field, enter the path to the directory that contains the
site on the server.
For a new Web site, this field contains a default path. For an
exiting site, this field contains the current path.
Security
Configuration
In this section you configure authentication and encryption for your
Web application, as follows:
■In the Authentication Provider section, select
Negotiate(Kerberos) or NTLM, as appropriate.
■In the Allow Anonymous section, choose Yes or No.
A value of Yes allows anonymous access to the Web site by using
a computer-specific anonymous access account. The account name
is IUSR_computername.
■In the Secure Sockets Layer (SSL) section, choose Yes or No.
If you choose to enable SSL for the Web site, you must configure
SSL by requesting and installing a certificate.
Public URL Enter the URL for the domain name for all sites that users will access
in this Web application. This URL domain will be used in all links
shown on pages in the Web application. By default, the box is
populated with the current server name and port. The Zone field is
automatically set to Default for a new Web application and cannot be
changed from this page.
Application Pool In the Application Pool section, choose whether to use an existing
application pool or create a new application pool for this Web
application, as follows:
■To use an existing application pool, select Use Existing
Application Pool, then select the application pool you wish to use
from the drop-down menu.
■To create a new application pool, select Create a New Application
Pool, and in the Application Pool Name field, type the name of
the new application pool, or keep the default name.
In the section Select a Security Account for This Application Pool,
select Predefined to use an existing application pool security
account, then select the security account from the drop-down
menu. To use a security account that is not currently being used
for an existing application pool, select Configurable, enter the user
name of the account you want to use in the User Name field, and
enter the password for the account in the Password field.
Table 59–3 (Cont.) Create Web Application Options for Microsoft SharePoint Server
Section What You Configure in This Section
Integrating With Microsoft SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-13
6. Click OK to create the new Web application, or click Cancel to cancel the process
and return to the Application Management page.
7. Proceed with "Creating a New Site Collection for Microsoft SharePoint Server".
59.5.2 Creating a New Site Collection for Microsoft SharePoint Server
You perform this task when integrating with Microsoft SharePoint Server, with or
without LDAP Membership Provider.
To create a new site collection for Microsoft SharePoint Server
1. From the Application Management page, Site Collection section, click Create Site
Collections.
2. On the Create Site Collection page, in the Web Application section, either select a
Web application to host the site collection (from the Web Application drop-down
list), or create a new Web application to host the site collection, as follows:
Database Name and
Authentication
In this section, choose the database server, database name, and
authentication method for your new Web application.
In the Database Name field, enter the name of the database or use the
default entry. In the Database Authentication field, choose whether to
use Windows authentication (recommended) or SQL authentication, as
follows:
■If you want to use Windows authentication, leave this option
selected.
■If you want to use SQL authentication, select SQL authentication.
In the Account field, type the name of the account that you want
the Web application to use to authenticate to the SQL Server
database, then type the password in the Password field.
Failover Server You can optionally choose to specify a fail-over database server to
configure a Fail-over Server.
Service Application
Connections
You can use the default value or choose custom value and optionally
select the services you want your web application to connect to.
Table 59–4 Create a Web Application to Host a Site Collection for SharePoint Server
Section What You Configure in This Section
Quota Template You can decide to use predefined quota template to limit
resources used for this site collection or use "No quota" as
appropriate.
Title and Description Enter a title and description for the site collection
Web Site Address Select a URL type, and specify a URL for the site collection.
Template Select a template from the tabbed template control.
Primary Site Collection
Administrator
Enter the user account name for the user you want to be the
primary Administrator for the site collection.
You can also browse for the user account by clicking the book
icon to the right of the text box. You can verify the user account
by clicking the check names icon to the right of the text box.
Table 59–3 (Cont.) Create Web Application Options for Microsoft SharePoint Server
Section What You Configure in This Section
Setting Up Microsoft Windows Impersonation
59-14 Administrator's Guide for Oracle Access Management
3. Refer to the following topics as you finish this integration:
■"Setting Up Microsoft Windows Impersonation" on page 59-14
■"Completing the SharePoint Server Integration" on page 59-22
■"Configuring Single Sign-off for Microsoft SharePoint Server" on page 59-33
■"Synchronizing User Profiles Between Directories" on page 59-37
■"Testing Your Integration" on page 59-37
59.6 Setting Up Microsoft Windows Impersonation
If you want to use a directory server other than Active Directory, use LDAP
Membership provider. The OAMCustomMembership provider leverages the
functionality of LDAP Membership provider.
This section describes how to set up impersonation, whether for SharePoint Server
integration or for use by some other application.
Task overview: Setting up impersonation
1. Create a trusted user account for only impersonation in the Active Directory
connected to SharePoint Server, as described in "Creating Trusted User Accounts"
on page 59-15.
2. Give the trusted user the special right to act as part of the operating system, as
described in "Assigning Rights to the Trusted User" on page 59-15.
3. Bind the trusted user to the WebGate by supplying the authentication credentials
for the trusted user, as described in "Binding the Trusted User to Your WebGate"
on page 59-16.
4. Add a header variable named IMPERSONATE to the Authorization Success
Action in the Application Domain for impersonation, as described in "Adding an
Impersonation Response to an Authorization Policy" on page 59-17.
5. Configure IIS by adding the
IISImpersonationModule.dll
to your IIS
configuration, as described in "Adding an Impersonation DLL to IIS" on
page 59-18.
6. Test impersonation, as described in "Testing Impersonation" on page 59-20.
Secondary Site Collection
Administrator (optional)
Enter the user account for the user that you want to be the
secondary Administrator for the site collection.
You can also browse for the user account by clicking the book
icon to the right of the text box. You can verify the user account
by clicking the Check Names icon to the right of the text box.
See Also: "Task overview: Integrating with Microsoft SharePoint
Server Configured with LDAP Membership Provider" on page 59-24
Note: Skip this section if you are integrating Microsoft SharePoint
Server configured with LDAP Membership Provider. Windows
impersonation is not used with the LDAP Membership Provider.
Table 59–4 (Cont.) Create a Web Application to Host a Site Collection for SharePoint
Section What You Configure in This Section
Setting Up Microsoft Windows Impersonation
Integrating Microsoft SharePoint Server with Access Manager 59-15
59.6.1 Creating Trusted User Accounts
This special user should not be used for anything other than impersonation.
The example in the following procedure uses Impersonator as the New Object - User.
Your environment will be different.
To create a trusted user account
1. Perform the following steps on the computer hosting your SharePoint Server
installation:
■Windows 2008: Select Start, Programs, Administrative tools, Active Directory
Users and Computers.
2. In the Active Directory Users and Computers window, right-click Users on the tree
in the left pane, then select New, User.
3. In the First name field of the pane entitled New Object - User, enter an
easy-to-remember name such as Impersonator.
4. Copy this same string to the User logon name field, then click Next.
5. In succeeding panels, you will be asked to choose a password and then retype it to
confirm.
Figure 59–1 Setting up a Trusted User Account for Windows Impersonation
59.6.2 Assigning Rights to the Trusted User
You need to give the trusted user the right to act as part of the operating system.
To give appropriate rights to the trusted user
1. Perform steps for your environment:
Note: Oracle recommends that you chose a very complex password,
because your trusted user is being given very powerful permissions.
Also, be sure to check the box marked Password Never Expires. Since
the impersonation module should be the only entity that ever sees the
trusted user account, it would be very difficult for an outside agency
to discover that the password has expired.
Setting Up Microsoft Windows Impersonation
59-16 Administrator's Guide for Oracle Access Management
■Windows 2008: Select Start, Programs, Administrative tools, Local Security
Policy.
2. On the tree in the left pane, click the plus icon (+) next to Local Policies.
3. Click User Rights Assignment on the tree in the left pane.
4. Double-click Act as part of the operating system in the right pane.
5. Click Add User or Group.
6. In the Add User or Group panel, type the User logon name of the trusted user
(SPPSImpersonator in our example) in the User and group names text entry box,
then click OK to register the change.
Figure 59–2 Configuring Rights for the Trusted User in Windows Impersonation
59.6.3 Binding the Trusted User to Your WebGate
You need to bind the trusted user to the 10g WebGate that communicates with Access
Manager by supplying the authentication credentials for the trusted user, as follows.
The following procedure presumes that you have not yet registered a 10g WebGate
with Access Manager. Values in the following procedure are provided as an example
only. Your environment will be different.
To bind your trusted user to your WebGate
1. Go to the Oracle Access Management Console.
For example:
http://hostname:port/oamconsole
where hostname is the fully-qualified DNS name of the computer hosting the
Oracle Access Management Console; port is the listening port configured for the
OAM Server; oamconsole leads to the Oracle Access Management Console.
2. Click Application Security at the top of the window.
3. In the Launch Pad tab, click SSO Agent Registration in the Quick Start Wizards
section.
4. Select WebGate as the agent type and click Next..
Setting Up Microsoft Windows Impersonation
Integrating Microsoft SharePoint Server with Access Manager 59-17
5. Set the version to 10g and enter required details (those with an *) to register this
WebGate.
6. Protected Resource List: In this table, enter individual resource URLs to be
protected by this OAM Agent, as shown in Table 14–9.
7. Public Resource List: In this table, enter individual resource URLs to be public
(not protected), as shown in Table 14–9.
8. Auto Create Policies: Check to create fresh policies (or clear and use the same host
identifier as another WebGate to share policies (Table 14–9)).
9. Click Apply to submit the registration.
10. Check the Confirmation window for the location of generated artifacts, then close
the window.
11. In the navigation tree, open the Agent page.
12. SharePoint Requirements: Enter trusted user credentials in the Sharepoint
Impersonator fields and click Apply.
13. Copy the artifacts as follows (or install the WebGate and then copy these artifacts):
a. On the Oracle Access Management Console host, locate the updated OAM
Agent ObAccessClient.xml configuration file (and any certificate artifacts). For
example:
$DOMAIN_HOME/output/$Agent_Name/ObAccessClient.xml
b. On the computer hosting the agent, copy the artifacts. For example
10g WebGate/AccessClient: $WebGate_install_dir/oblix/lib/
ObAccessClient.xml
c. Proceed to "Adding an Impersonation Response to an Authorization Policy".
59.6.4 Adding an Impersonation Response to an Authorization Policy
An Application Domain and basic policies to protect your SharePoint resources was
created when you registered the WebGate with Access Manager. Now you must add
an Authorization Success Action (Response) with a return type of Header, set the
name to
IMPERSONATE
, with the Response value of $user.userid: "samaccountname" for a
single-domain Active Directory installation or "userPrincipalName" for a
multi-domain Active Directory forest.
To add an impersonation response to your Authorization Policy
1. Click Application Security at the top of the Console window.
2. In the Launch Pad tab, click Application Domains in the Access Manager section.
3. Search for the desired domain and open it for editing.
4. Click the Authorization Policies tab and open the desired policy for editing.
"Desired domain" refers to the Application Domain created specifically for
impersonation (Impersonation for example). "Desired policy" is your default policy
created during agent registration. By default, no policy Responses exist until you
create them.
5. On the Policy page, click the Responses tab, click the Add (+) button, and:
■From the Type list, choose Header.
Setting Up Microsoft Windows Impersonation
59-18 Administrator's Guide for Oracle Access Management
■In the Name field, enter a unique name for this response:
IMPERSONATE
■In the Value field, enter a value for this Response. For example: $user.userid.
6. Click Add to save the Response, which is used for the second WebGate request
(for authorization).
59.6.5 Adding an Impersonation DLL to IIS
You are ready to configure IIS Web server for this integration by registering and
configuring the IISImpersonationModule.dll across all sites including central
administration and web services.
Alternatively, if you have multiple Web sites, where some are integrated with Access
Manager while others are not, you might want to enable impersonation only for those
Web sites that are integrated with Access Manager. To do this, you must configure the
Native Module only at those sites that require integration. See:
■To configure and register ImpersonationModule to IIS
■To configure site level Native Modules for Web sites
To configure and register ImpersonationModule to IIS
1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
2. In the left pane of IIS 7, click the hostname.
3. In the middle pane, under the IIS header, double click Modules.
4. In the right pane, click Configure Native Modules and click Register.
5. In the window, provide a module Name (for example, Oracle Impersonation
Module).
6. In the Path field, type the full path to IISImpersonationModule.dll.
By default, the path is:
WebGate_install_dir\access\oblix\apps\Webgate\bin\IISImpersonation
Where WebGate_install_dir is the directory of your WebGate installation.
7. Click OK to register the module.
8. Check the name of the newly created module and click OK to apply the module
across the Web sites.
Note: If any spaces exist in the path (for example,
C:\Program Files\Oracle\...
) surround the entire string with
double quotes (" ").
Setting Up Microsoft Windows Impersonation
Integrating Microsoft SharePoint Server with Access Manager 59-19
Figure 59–3 Registering the Impersonation Module
To configure site level Native Modules for Web sites
1. Click the plus icon (+) icon to left of Sites.
2. Click the site where you want to enable Impersonation.
3. In the Middle pane, under IIS, double click Modules.
4. In the right pane, click Configure Native Modules and select the Impersonation
Module registered earlier.
5. Click OK.
Setting Up Microsoft Windows Impersonation
59-20 Administrator's Guide for Oracle Access Management
6. Proceed with:
■Testing Impersonation
■Completing the SharePoint Server Integration
59.6.6 Testing Impersonation
You can test to ensure that impersonation is working properly in the following ways
before you complete the integration:
■Outside the SharePoint Server context or test single sign-on, as described in
"Creating an IIS Virtual Site Not Protected by SharePoint Server" on page 59-20
■Using the Event Viewer, as described in "Testing Impersonation Using the Event
Viewer" on page 59-21
■Using a Web page, as described in "Testing Impersonation using a Web Page" on
page 59-22
■Using negative testing as described in "Negative Testing for Impersonation" on
page 59-22
59.6.6.1 Creating an IIS Virtual Site Not Protected by SharePoint Server
To test the impersonation feature outside the SharePoint Server context or to test single
sign-on, you will need a target Web page on an IIS virtual Web site that is not
protected by SharePoint Server. You create such a virtual Web site by completing the
following task.
To create an IIS virtual site not protected by SharePoint Server
1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
See Also: "Completing the SharePoint Server Integration" after
confirming impersonation configuration is working properly
Setting Up Microsoft Windows Impersonation
Integrating Microsoft SharePoint Server with Access Manager 59-21
2. Click the plus icon (+) to the left of the local computer icon on the tree in the left
pane.
3. Right-click Web Sites on the tree in the left pane, then navigate to New, Web Site
on the menu.
4. Respond to the prompts by the Web site creation wizard.
5. After you create the virtual site, you must protect it with policies in an Application
Domain.
59.6.6.2 Testing Impersonation Using the Event Viewer
When you complete impersonation testing using the Windows 2003 Event Viewer, you
must configure the event viewer before conducting the actual test.
To test impersonation through the Event Viewer
1. Select Start Menu, Event Viewer.
2. In the left pane, right-click Security, then click Properties.
3. Click the Filter tab on the Security property sheet.
4. Verify that all Event Types are checked, and the Event Source and Category lists
are set to All, then click OK to dismiss the property sheet.
Your Event Viewer is now configured to display information about the HeaderVar
associated with a resource request.
Figure 59–4 Verifying Event Viewer Settings
5. Create a new IIS virtual server (virtual site).
6. Place a target Web page anywhere in the tree on the virtual site.
7. Point your browser at the Web page.
If impersonation is working correctly, the Event Viewer will report the success of the
access attempt.
Completing the SharePoint Server Integration
59-22 Administrator's Guide for Oracle Access Management
59.6.6.3 Testing Impersonation using a Web Page
You can also test impersonation using a dynamic test page, such as an .asp page or a
Perl script, that can return and display information about the request.
To test impersonation through a Web page that displays server variables
1. Create an .asp page or Perl script that will display the parameters AUTH_USER
and IMPERSONATE, which can resemble the sample page presented in the
following listing:
Example 59–1 Sample .ASP Page Code
<TABLE border=1>
<TR>
<TD>Variable</TD>
<TD>&nbsp&nbsp</TD>
<TD>Value</TD></TR>
<%for each servervar in request.servervariables%>
<TR>
<TD><%=servervar%></TD>
<TD>&nbsp&nbsp</TD>
<TD><%=request.servervariables(servervar)%>&nbsp</TD>
</TR>
2. Create an IIS virtual site, or use the one you created for the previous task.
3. Place an .asp page or Perl script (such as the sample in the preceding listing)
anywhere in the tree of the new virtual site.
4. Point your browser at the page, which should appear, with both AUTH_USER and
IMPERSONATE set to the name of the user making the request.
59.6.6.4 Negative Testing for Impersonation
To conduct negative testing for impersonation, you need to unbind the trusted user
from the WebGate, as explained in the following procedure.
To unbind the trusted user from your WebGate
1. In the Oracle Access Management Console, locate the WebGate.
2. Open the desired WebGate registration page and remove the credentials for the
trusted user.
3. Click Apply to save the change.
4. Restart the IIS server and in a browser window, go to a protected code page
(previously accessible to the trusted user).
5. Confirm that you receive an message page should appear. Values for AUTH_USER
and IMPERSONATE are necessary for impersonation credentials to be bound to a
WebGate.
6. Restore the trusted user to the WebGate registration page.
59.7 Completing the SharePoint Server Integration
You need to complete several procedures to set up an Access Manager with SharePoint
Server integration.
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
Integrating Microsoft SharePoint Server with Access Manager 59-23
Task overview: Completing the SharePoint Server integration
1. Set up IIS security, as described in "Configuring IIS Security" on page 59-23.
2. Test the integration, as described in "Testing the SharePoint Server Integration" on
page 59-37.
59.7.1 Configuring IIS Security
Be sure to configure IIS Security before you continue.
To configure IIS Security for the SharePoint Server integration
1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
2. Click the plus icon (+) to the left of the local computer icon on the tree in the left
pane.
3. Click Web Sites on the tree in the left pane.
4. In the center pane, double-click on Authentication under IIS.
5. Ensure that Anonymous Authentication is enabled and Windows Authentication
is disabled.
Figure 59–5 Impersonation Authentication
59.8 Integrating With Microsoft SharePoint Server Configured With LDAP
Membership Provider
In this scenario, Access Manager gets integrated with SharePoint Server using
SharePoint Security Token Service (STS). This includes the ISAPI WebGate installation
on IIS, as well as Access Manager configuration and steps needed to achieve the
HeaderVar integration.
The following overview introduces the tasks that you must perform for this
integration, including prerequisites, and where to find the information you need for
each task.
Note: Skip this section if you are integrating with SharePoint Server
configured with LDAP Membership Provider.
Note: Only 64-bit ISAPI WebGates are supported for this integration.
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
59-24 Administrator's Guide for Oracle Access Management
Task overview: Integrating with Microsoft SharePoint Server Configured with
LDAP Membership Provider
1. Preparing for this integration:
a. Install "Required Microsoft Components", as described on page 59-7.
b. Create a SharePoint Web site, as described in "Creating a New Web
Application in Microsoft SharePoint Server" on page 59-11.
c. Configure the SharePoint site collection, as described in "Creating a New Site
Collection for Microsoft SharePoint Server" on page 59-13.
d. Configure the created Web site with LDAP directory using Claim-Based
Authentication type (which uses the LDAP Membership Provider), as
described in your SharePoint documentation.
e. Ensure that users who are present in the LDAP directory can log in to the
SharePoint Web site and get proper roles.
f. Test the configuration to ensure that users who are present in the LDAP
directory can log in to the SharePoint Web site and get proper roles, as
described in your SharePoint documentation.
2. Perform all tasks described in "Installing Access Manager for Microsoft SharePoint
Server Configured With LDAP Membership Provider" on page 59-25.
This task includes installing a 10g WebGate for IIS and configuring a
WebGate.dll
for the individual SharePoint Web site.
3. Add an authentication scheme for this integration, as described in "Configuring an
Authentication Scheme for Use With LDAP Membership Provider" on page 59-26.
4. Update the Application Domain that protects the SharePoint Web Site, as
described in "Updating the Application Domain Protecting the SharePoint Web
Site" on page 59-27.
5. In the new Application Domain, create an authorization rule for this integration,
as described in "Creating an Authorization Response for Header Variable SP_SSO_
UID" on page 59-28.
6. Perform all steps in "Creating an Authorization Response for the
OAMAuthCookie" on page 59-29.
7. Perform all steps in "Configuring and Deploying
OAMCustomMembershipProvider" on page 59-29.
8. Synchronize directory servers, if needed, as described in "Ensuring Directory
Servers are Synchronized" on page 59-32.
9. Configure single-sign-on for office documents as described in "Configuring Single
Sign-On for Office Documents" on page 59-32.
10. Configure single sign-off, as described in "Configuring Single Sign-off for
Microsoft SharePoint Server" on page 59-33.
11. Finish by testing your integration to ensure it operates without problem, as
described in "Testing the Integration" on page 59-32.
59.8.1 About Integrating With Microsoft SharePoint Server Configured With LDAP
Membership Provider
The previous scenario, "Integrating With Microsoft SharePoint Server" on page 59-10,
describes how to use Windows authentication. In that scenario, authentication and
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
Integrating Microsoft SharePoint Server with Access Manager 59-25
authorization are performed for users residing in Active Directory. Access Manager
used Windows impersonation for integration.
For the integration described in this section, support for the LDAP Membership
Provider is achieved by using a HeaderVar-based integration. The ISAPI WebGate
filter intercepts HTTP requests for Web resources and works with the OAM Server to
authenticate the user who made the request. When authentication is successful,
WebGate creates an ObSSOCookie and sends it to the user's browser to facilitate single
sign-on (SSO). The WebGate also sets
SP_SSO_UID
as a
HeaderVar
action for this user
session. The Oracle Custom Membership provider in SharePoint validates the
ObSSOCookie using the HTTP validation method, whereby the Access Manager
Custom Membership Provider makes an HTTP/HTTPS request to a protected
resource. Access Manager then validates and compares the user login returned on
Authorization success with
SP_SSO_UID
.
Requirements: This integration requires that Microsoft SharePoint Server:
■Must be integrated with the LDAP Membership Provider
■Must not use Windows authentication
■Must not have
IISImpersonationModule.dll
configured at the Web site using
Claim Based Authentication
59.8.2 Installing Access Manager for Microsoft SharePoint Server Configured With
LDAP Membership Provider
This procedure describes how to prepare your installation for integration with
Microsoft SharePoint Server Configured with LDAP Membership Provider.
Prerequisites
Perform Step 1 of the previous "Task overview: Integrating with Microsoft SharePoint
Server Configured with LDAP Membership Provider" on page 59-24.
To prepare your deployment for integration that includes LDAP Membership
Provider
1. Install Oracle Identity Management and Access Manager.
2. Provision and install an ISAPI WebGate.
3. Configure
Webgate.dll
at the SharePoint Web site that you want to protect. For
example:
a. Start the Internet Information Services (IIS) Manager: Click Start, Programs,
Administrative Tools, Internet Information Services (IIS) Manager
b. Under Web Sites, double click the name of the SharePoint Web site to protect.
c. In the Middle pane, double click ISAPI Filters and click Add in the right pane.
d. Enter the filter name as
Oracle WebGate
.
e. Enter the following path to the
Webgate.dll
file.
WebGate_install_dir/access/oblix/apps/Webgate/bin/Webgate.dll
See Also: "Introduction to Integrating With the SharePoint Server"
on page 59-2 for a look at processing differences between this
integration and the other integrations described in this chapter.
See Also: "Integration Requirements" on page 59-6
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
59-26 Administrator's Guide for Oracle Access Management
f. Save and apply these changes.
g. Double click Authentication in the middle pane.
h. Verify that the following Internet Information Services settings are correct:
Anonymous Authentication and Forms Authentication is enabled, and
Windows Authentication is disabled.
i. Save and Apply these changes.
4. Go to the Web sites level to protect and create an /access application that points to
the newly installed WebGate_install_dir. For instance:
a. Under Web Sites, right-click the name of the Web site to be protected.
b. Select Add application named with the alias "access" that points to the
appropriate WebGate_install_dir\access.
c. Under Access Permissions, check Read, Run Scripts, and Execute.
d. Save and apply these changes.
5. Proceed to "Configuring an Authentication Scheme for Use With LDAP
Membership Provider".
59.8.3 Configuring an Authentication Scheme for Use With LDAP Membership Provider
When your integration includes the LDAP Membership Provider, only three Access
Manager authentication methods are supported, as described in this procedure.
To configure an authentication scheme for SharePoint with LDAP Membership
Provider
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, select Create Authentication Scheme from the Create (+)
drop-down menu the Access Manager section.
3. On the Authentication Scheme page, fill in the:
Name: Enter a unique name for this scheme. For example: SharePoint w/LDAP-MP
Description: Optional
4. Authentication Level: Choose a level of security for the scheme.
5. Choose a Challenge Method:
Basic Authentication for SharePoint Web site root (/)
Form Authentication with Challenge Redirect for SharePoint Web site root (/)
Client Certificate Authentication for SharePoint Web site root (/)
6. Challenge Redirect: Enter your challenge redirect value, if required.
7. Choose an Authentication Module from those listed.
8. Challenge Parameters: Enter your challenge parameter values, if required.
Note: For Claim-based Authentication to work with Access
Manager, Windows Authentication for the SharePoint Site must be
disabled.
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
Integrating Microsoft SharePoint Server with Access Manager 59-27
9. Challenge URL: The URL the credential collector will redirect to for credential
collection.
10. Click Apply to submit the new scheme, review details in the Confirmation
window.
11. Optional: Click the Set as Default button to automatically use this with new
Application Domains, then close the Confirmation window.
12. In the navigation tree, confirm the new scheme is listed, and then close the page.
13. Proceed with "Updating the Application Domain Protecting the SharePoint Web
Site".
59.8.4 Updating the Application Domain Protecting the SharePoint Web Site
This Application Domain was created when you provisioned the IIS WebGate to
protect the Microsoft SharePoint Server Web site for the integration scenario with
LDAP Membership Provider.
Within an Application Domain, resource definitions exist as a flat collection of objects.
Each resource is defined as a specific type, and the URL prefix that identifies a
document or entity stored on a server and available for access by a large audience. The
location is specified using an existing shared Host Identifier.
You need to use the authentication scheme that you created earlier. To validate the
ObSSOCookie, you must create another policy for a resource protected by a WebGate;
for example: /ValidateCookie. This resource should be deployed on a Web server
protected by a WebGate and you should be able to access it after providing correct
Access Manager credentials:
http(s)://
host:port
/
ValidateCookie
This example uses SharePoint w/LDAP-MP as the Application Domain name. Your
environment will be different.
To update the Application Domain protecting the root SharePoint Web site
1. From the Oracle Access Management Console, open the SharePoint w/LDAP-MP
Application Domain.
2. Open the Resources tab, then click the New Resource button.
3. On the Resource Definition page, select or enter your details for a single resource
and click Apply:
Type: http
Note: If the SharePoint resource is protected with an Access Manager
client-cert authentication scheme, you might need to add to the PATH
environment variable
C:\Program Files\Microsoft Office
Servers\14.0\Bin;C:\Program Files\Common Files\Microsoft
Shared\Web Server Extensions\14\BIN
.
Note: For this integration, leave empty the URL Prefix. Do not enter
a region to be appended to the URL prefix.
Note: Step 4 includes an alternative Authentication Scheme to
protect the SharePoint Web site with a Form authentication scheme.
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
59-28 Administrator's Guide for Oracle Access Management
Description (optional): Protecting SharePoint Website
Host Identifier: Select the host identifier that you added earlier.
Resource URL: Enter /ValidateCookie.
Protection Level: Protected
Authentication Policy (if level is Protected)
Authorization Policy (if level is Protected and Authentication Policy is chosen)
4. In the Protected Resource Policy for Authentication, add a defined resource:
■Click the Resources tab on the Authentication Policy page.
■Click the Add button on the Resources tab.
■Locate and select the desired resource definition, then click Add Selected.
■Click Apply to add the resources.
■Repeat to add more resources.
5. Click the Responses tab, then click its Add button and:
■In the Name field, enter a unique name for this response (SP_SSO_UID).
■From the Type list, choose Header.
■In the Valu e field, enter a value for this response. For example: $user.userid.
■Click Apply.
6. Add a Policy: Add a policy for a resource used with the HTTP validation method,
If selected.
7. Before you enable this Application Domain, proceed to "Creating an Authorization
Response for Header Variable SP_SSO_UID"
59.8.5 Creating an Authorization Response for Header Variable SP_SSO_UID
This topic describes how to add an Authorization Response for the integration
configured with LDAP Membership Provider. For this integration, you add the
following Header Variable to the Application Domain as Responses for Authorization
success:
Type = Header
Name = SP_SSO_UID
Return Attribute = $user.userid
In this case:
■ The Return Attribute is the login attribute used in Login
■ This authorization rule protects the root SharePoint Web site "/ "
To create an authorization response for SharePoint with LDAP Membership
Provider
1. From the Oracle Access Management Console, open the SharePoint w/LDAP-MP
Authorization Policy: ProtectedResourcePolicy.
2. Click the Authorization Policy Responses tab, then click its Add button:
■In the Name field, enter a unique name for this response (SharePoint
w/LDAP-MP).
■From the Type list, choose Header.
■In the Valu e field, enter a value for this response. For example: $user.userid.
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
Integrating Microsoft SharePoint Server with Access Manager 59-29
■Click Apply.
■Repeat as needed.
3. Proceed to "Creating an Authorization Response for the OAMAuthCookie".
59.8.6 Creating an Authorization Response for the OAMAuthCookie
Here, you add the following Header Variable named
OAMAuthCookie
to the
Application Domain as Responses under Authorization success:
Type = Cookie
Name = OAMAuthCookie
Return Attribute = $user.userid
To create a Application Domain to protect the validation URL
1. From the Oracle Access Management Console, open the SharePoint w/LDAP-MP
Authorization Policy: Protected Resource Policy:
2. Click the Responses tab, then click its Add button and:
Redirection URL: Not required for this integration
Return
Type = Cookie
Name = OAMAuthCookie
Return Attribute = $user.userid
■In the Name field, enter a unique name for this response (OAMAuthCookie).
■From the Type list, choose Cookie.
■In the Valu e field, enter a value for this response. For example: $user.userid.
■Click Apply to submit the response, then close the confirmation window.
■Repeat as needed.
3. Proceed to "Configuring and Deploying OAMCustomMembershipProvider."
59.8.7 Configuring and Deploying OAMCustomMembershipProvider
You perform the following configuration steps in SharePoint to use the Access
Manager Authentication Module to authenticate and authorize the user.
To configure SharePoint to use OAM authentication Module
1. Go to the physical location of the SharePoint Web site directory. For example:
C:\Inetpub\wwwroot\wss\VirtualDirectories\SharePoint website Name
2. From the folder_forms, copy the file
Default.aspx
as
Default.ORIG.aspx
.
3. Open
Default.aspx
, search for
</asp:login>
, add the following after the line, and
then save the file:
<asp:HiddenField EnableViewState="false" ID="loginTracker" runat="server"
Note: You can specify a default login page bundled in this file:
WebGate_install_dir
\access\oblix\apps\Webgate\
OAMCustomMembershipProvider\samples\Sample.Default.aspx
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
59-30 Administrator's Guide for Oracle Access Management
Value="autoLogin" />
<%bool autoLogin = loginTracker.Value == "autoLogin";%>
<script runat="server">
void Page_Load()
{
signInControl.LoginError += new EventHandler(OnLoginError);
NameValueCollection headers = Request.ServerVariables;
NameValueCollection queryString = Request.QueryString;
string loginasanotheruser = queryString.Get("loginasanotheruser");
string username = Request.ServerVariables.Get("HTTP_SP_SSO_UID");
HttpCookie ObSSOCookie = Request.Cookies["ObSSOCookie"];
bool isOAMCredsPresent = username != null && username.Length > 0 &&
ObSSOCookie != null && ObSSOCookie.Value != null;
bool signInAsDifferentUser = loginasanotheruser != null &&
loginasanotheruser.Contains("true");
if (isOAMCredsPresent)
{
//Handling For UTF-8 Encoding in HeaderName
if (username.StartsWith("=?UTF-8?B?") && username.EndsWith("?="))
{
username = username.Substring("=?UTF-8?B?".Length,
username.Length - 12);
byte[] decodedBytes = Convert.FromBase64String(username);
username = Encoding.UTF8.GetString(decodedBytes);
}
}
if (isOAMCredsPresent && loginTracker.Value == "autoLogin" &&
!signInAsDifferentUser)
{
bool
status=Microsoft.SharePoint.IdentityModel.SPClaimsUtility.AuthenticateFormsUser
(new
Uri(SPContext.Current.Site.Url),username,"ObSSOCookie:"+ObSSOCookie.Value);
if(status){
if (Context.Request.QueryString.Keys.Count > 1)
{
Response.Redirect(Context.Request.QueryString["Source"].ToString());
}
else
Response.Redirect(Context.Request.QueryString["ReturnUrl"].ToString());
}
else{
loginTracker.Value =
}
}
else
{
// DO NOTHING
}
}
void OnLoginError(object sender, EventArgs e)
Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider
Integrating Microsoft SharePoint Server with Access Manager 59-31
{
loginTracker.Value = "";
}
</script>
4. Go to IIS Manager and click the Plus icon (+) before Sites.
5. Click on the plus icon (+) before SharePoint Web Services.
6. Right -click SecurityTokenServiceApplication, then click Explore.
7. Create a backup copy of
Web.config
as
Web.config.ORIG
, then open
Web.config
.
8. In the membership provider entries for enabling the LDAP membership provider
go to <membership>, <providers>, type, and then modify the type value as
follows:
type = "Oracle.CustomMembershipProvider, OAMCustomMembershipProvider,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=52e6b93f6f0427a1
9. Add the following attribute at the end of the entry in Step 8
ValidationMode="OAMHttp"
to indicate the ObSSOCookie validation method.
<add name="membership"
type = "Oracle.CustomMembershipProvider,
OAMCustomMembershipProvider, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=52e6b93f6f0427a1"
server="HOST1.COM"
port="389"
useSSL="false"
userDNAttribute="distinguishedName"
userNameAttribute="sAMAccountName"
userContainer="cn=users,dc=bored,dc=com"
userObjectClass="person"
userFilter="(&amp;(ObjectClass=person))"
scope="Subtree"
otherRequiredUserAttributes="sn,givenname,cn"
ValidationURL="http(s)://host:port/ValidateCookie.html"
OAMAuthUser="OAMAuthCookie
ValidationMode="OAMHttp"
/>
10. Save the file.
11. Using command prompt go to the following directory:
C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin\gacutil.exe
12. Type:
gacutil -l OAMCustomMembershipProvider
13. Confirm that no results are returned.
14. Type the following.
Note: The resource configured for
ValidationURL
must be present
on the Web server. Also, the value of the
OAMAuthUser
parameter
should be configured as the authorization return action as described
in Step 6.
Configuring Single Sign-On for Office Documents
59-32 Administrator's Guide for Oracle Access Management
gacutil -i <Webgate_install_
dir>\access\oblix\apps\Webgate\OAMCustomMembershipProvider\OAMCustomMembershipP
rovider.dll
15. Type:
gacutil -l OAMCustomMembershipProvider
16. Confirm that one result is returned.
17. Restart the SharePoint Web site.
18. Proceed as follows:
■Enabling Logging for CustomMemberShipProvider
■Ensuring Directory Servers are Synchronized
■Configuring Single Sign-off for Microsoft SharePoint Server
59.8.8 Enabling Logging for CustomMemberShipProvider
If you want to enable logs for the Oracle Custom Membership Provider, you must
configure the
DebugFile
parameter in the configuration file for the Oracle Custom
Membership Provider. For example: a sample entry for the
DebugFile=
Location_of_
logs_file":
type = "Oracle.CustomMembershipProvider, OAMCustomMembershipProvider,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=52e6b93f6f0427a1"
DebugFile="c:\Debug.txt"
59.8.9 Ensuring Directory Servers are Synchronized
Users in the directory server configured for Access Manager should be synchronized
with the directory server used by SharePoint if these are different. This is the same task
that you perform for other integration scenarios in this chapter. When your SharePoint
integration includes an LDAP Membership Provider, however, you can use a directory
server that supports LDAP commands.
59.8.10 Testing the Integration
This is similar to the task you perform for other integration scenarios in this chapter.
There are no differences when configured with LDAP Membership Provider.
59.9 Configuring Single Sign-On for Office Documents
Single sign-on for Office documents can be achieved by setting a persistent cookie in
the authentication scheme. To do this using OAM 11g, you need to set
ssoCookie=max-age
in the authentication scheme. This creates a persistent cookie
which lasts for more than one session.
See Also: "Synchronizing User Profiles Between Directories" on
page 59-37
See Also: "Testing the SharePoint Server Integration" on page 59-37
Note: For integration based on Windows Native Authentication, you
do not need to set the persistent cookie parameter.
Configuring Single Sign-off for Microsoft SharePoint Server
Integrating Microsoft SharePoint Server with Access Manager 59-33
1. Log in to the Oracle Access Management Console.
2. Find the Authentication Scheme being used and open the page.
3. In the Challenge Parameter, add:
ssoCookie=max-age=1000000
Where,
time-in-seconds
represents the time interval when the cookie expires. For
example,
ssoCookie=max-age=3600
sets the cookie to expire in 1 hour (3600
seconds).
4. Save the change.
5. Configure centralized logout for the 10g or 11g WebGate.
59.10 Configuring Single Sign-off for Microsoft SharePoint Server
Manual Logout occurs when the user clicks the Logout button from SharePoint Server.
You can also configure the SharePoint Server logout URL in Access Manager so that
when a user clicks the Logout button from SharePoint Server site, Access Manager
logout is also triggered.
Cookie time-out occurs when the overall user session is controlled by ObSSOCookie.
Consider the following use-case:
■FedAuth cookie time-out and ObSSOCookie is still valid: The user won't be
challenged again because the ObSSOCookie is present. A new FedAuth cookie is
generated (using the same flow described earlier).
■ObSSOCookie time-out and FedAuth Cookie is still valid: Since each request is
intercepted by the WebGate, the user is challenged for credentials again.
Access Manager provides single logout (also known as global or centralized log out)
for user sessions. With Access Manager, single logout refers to the process of
terminating an active user session.
This topic describes how to configure single sign-off for integration with SharePoint.
Single sign-off kills the user session.
■Configuring a Custom Logout URL in SharePoint Server
■Configuring Logout in SharePoint Server With Impersonation
59.10.1 Configuring a Custom Logout URL in SharePoint Server
To configure a Custom Logout URL in SharePoint Server
1. From the generated artifacts for WebGate, add
logout.html
to the SharePoint
Server Site
2. Locate
C:\Program Files\Common Files\Microsoft Shared\Web Server
Extensions\14\TEMPLATE\CONTROLTEMPLATES
.
3. In
\CONTROLTEMPLATES
, change the
welcome.ascx
by adding the following tag. For
example:
<SharePoint:MenuItemTemplate runat="server" id="ID_OverrideLogout" Text="Custom
Note: Closing the browser window after sign-off is always
recommended, for security.
Setting Up Access Manager and Windows Native Authentication
59-34 Administrator's Guide for Oracle Access Management
Logout"
ClientOnClickNavigateUrl="/logout.html?end_url=_layouts/SignOut.aspx"
Description="My Custom Logout"
MenuGroupId="200"
Sequence="100"
UseShortId="true" />
4. Click Save.
5. Protect the two URLs /_layouts/SignOut.aspx and /_
layouts/closeConnection.aspx in an Application Domain using Anonymous
authentication.
6. Proceed to Configuring Logout in SharePoint Server With Impersonation.
59.10.2 Configuring Logout in SharePoint Server With Impersonation
You can skip this procedure if you do not have Impersonation configured.
To configure Logout in SharePoint Server with Impersonation
1. Copy
signout.aspx
from
C:\Program Files\Common Files\Microsoft
Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS
) to
MySignout.aspx
in the
same path.
2. In
MySignout.aspx
, below (
<asp:content
contentplaceholderid="PlaceHolderAdditionalPageHead" runat="server">
)
add the following script details:
<script runat="server">
private void Page_Load(object sender, System.EventArgs e)
{
Response.Status = "302 Moved Temporarily";
Response.AddHeader("Location", "/logout.html?end_url=/_layouts/SignOut.aspx");
}
</script>
3. Save.
4. Use this URL
_layouts/Mysignout.aspx
as custom logout URL for SharePoint
Server in the case of Impersonation.
5. Proceed with "Testing Your Integration".
59.11 Setting Up Access Manager and Windows Native Authentication
This section provides the following topics:
■Setting Up Access Manager WNA
■Setting Up WNA With SharePoint Server
■Installing Access Manager for WNA and SharePoint Server
■Testing Your WNA Implementation
59.11.1 Setting Up Access Manager WNA
Configure Access Manager to use Windows Native Authentication.
Setting Up Access Manager and Windows Native Authentication
Integrating Microsoft SharePoint Server with Access Manager 59-35
59.11.2 Setting Up WNA With SharePoint Server
The following overview outlines the tasks that must be performed to set up WNA
with Access Manager and the SharePoint Server.
Task overview: Setting up WNA with SharePoint Server
1. Complete the following prerequisite tasks:
■Perform tasks in "Required Microsoft Components" on page 59-7.
■Create a SharePoint Web site, as described in "Creating a New Web
Application in Microsoft SharePoint Server" on page 59-11.
■Configure the SharePoint site collection, as described in "Creating a New Site
Collection for Microsoft SharePoint Server".
■Test the configuration to ensure that users who are present in the directory
server can log in to the SharePoint Web site and get proper roles, as described
in your SharePoint documentation.
2. Install Access Manager as described in "Installing Access Manager for WNA and
SharePoint Server" on page 59-35.
This step includes installing the WebGate for IIS and configuring
Webgate.dll
for
the individual SharePoint Web site.
3. Configure the Active Directory authentication provider, as follows:
a. Login to the WebLogic Console.
b. Go to Security Realm and click the realm being used.
c. Go to the Provider tab provider, click New.
d. Enter the provider name, select the Type ActiveDirectoryAuthenticator, click
OK.
e. Select the newly created Provider, change Control Flag to Sufficient, and Save.
f. Go to Provider Specific tab, enter details for your Active Directory, and save
these.
4. Perform "Testing Your WNA Implementation" on page 59-37.
59.11.3 Installing Access Manager for WNA and SharePoint Server
You perform this task after you perform all prerequisites described in step 1 of the
"Task overview: Setting up WNA with SharePoint Server". Installing most Access
Manager components for this integration scenario is the same as for any other
situation.
Installing the IIS WebGate is similar to installing any other WebGate. The WebGate
should be installed with the IIS v7 Web server; later it can be configured at the specific
SharePoint Web site level to be protected. For IIS, the WebGate must be configured at
the "web sites" level. For Microsoft SharePoint Server, you must configure the WebGate
for the specific SharePoint Web site level to be protected.
To install Access Manager for WNA and SharePoint Server
1. Install Access Manager as described in the Oracle Fusion Middleware Installation
Guide for Oracle Identity and Access Management.
2. Install the ISAPI WebGate as follows:
■Installing WebGates
Setting Up Access Manager and Windows Native Authentication
59-36 Administrator's Guide for Oracle Access Management
■Installing Web components for the IIS Web server
Next, you configure
Webgate.dll
at the SharePoint Web site that yo want to
protect. Configuring
Webgate.dll
at the "Website level" protects all Web sites
on the IIS Web server. However, configuring
Webgate.dll
at the "SharePoint
Website" protects only the expected Web site.
3. Configure
Webgate.dll
at the SharePoint Web site that you want to protect. For
example:
a. Start the Internet Information Services (IIS) Manager: Click Start, Programs,
Administrative Tools, Internet Information Services (IIS) Manager.
b. Select the hostname from the Connections pane.
c. From the host name Home pane, double-click ISAPI Filters, look for any
Webgate.dll
; if it is present, select it and click Remove from the Action pane.
d. In the Connection pane, under Sites, click the name of the Web Site for which
you want to configure a WebGate filter.
e. In the Home pane, double-click ISAPI Filters.
f. In the Actions pane, click Add…
g. In the Filter name text box of the Add ISAPI Filter dialog box, type WebGate
as the name of the ISAPI filter.
h. In the Executable box, type the file system path of the WebGate ISAPI filter
file or click the ellipsis button (...) to go to the folder that contains the
Webgate.dll
ISAPI filter file, and then click OK.
WebGate_install_dir\access\oblix\apps\Webgate\bin\Webgate.dll
4. Creating a Virtual Directory
a. Expand the Sites pane and select the Web Site for which you just configured
the ISAPI filter (
Webgate.dll
).
b. On the Action pane, click View Virtual Directories and then select Add
Virtual Directory.
c. In the Alias field, specify access and the physical path to the WebGate \access
folder (or click the ellipsis button (...), go to the \access folder, then click OK).
WebGate_install_dir\access\
5. Set permissions on the Virtual Directory:
a. Select the "access" virtual directory created in Step 3.
b. From the access Home pane, double click Handler Mappings; from the Action
pane, select Edit Feature Permissions….
c. Select Read, Script, and Execute, then click OK
6. Configure Access Manager to use Windows Native Authentication.
7. Configure Microsoft SharePoint Server Authentication to Classic Mode
Authentication while creating a new Web Application in Microsoft SharePoint. In
the Authentication Provider section, select Negotiate(Kerberos).
8. Go to IIS newly created SharePoint site and:
a. Open Authentication, Windows Authentication, Advance Settings.
b. Select Enable Kernel mode authentication.
Testing Your Integration
Integrating Microsoft SharePoint Server with Access Manager 59-37
c. Select providers, delete NTLM provider.
d. Add Negotiate:Kerberos and move it to the top level.
e. Restart IIS.
9. Proceed to "Testing Your WNA Implementation".
59.11.4 Testing Your WNA Implementation
Use the following steps to confirm your WNA implementation is working properly.
To test your WNA implementation
1. Log in to the machine as the Windows domain user (or AD user or AD user
account).
The login account must also be a user of Access Manager.
2. Enter the URL of the protected resource.
59.12 Synchronizing User Profiles Between Directories
Unless explicitly stated, this task should be performed for all integration scenarios in
this chapter.
You need to synchronize user profiles between the SharePoint Server directory and the
Access Manager directory:
■Uploading user data—If your Access Manager installation is configured for any
directory server other than SharePoint Active Directory, you must load the user
profiles that reside on the other directory server to SharePoint Active Directory.
Proceed to "Testing Your Integration"
59.13 Testing Your Integration
After you complete the tasks to enable integration, you should test to verify that
integration is working.
This section contains the following topics:
■Testing the SharePoint Server Integration
■Testing Single Sign-On for the SharePoint Server Integration
59.13.1 Testing the SharePoint Server Integration
You can verify that a user can access SharePoint Server resources through Access
Manager authentication and SharePoint Server authorization.
To test your SharePoint Server integration
1. Navigate to any SharePoint Server Web page using your browser.
You are challenged for your credentials.
2. Log in by supplying the necessary credentials.
Note: When your integration includes LDAP Membership Provider,
you can use any directory server that supports LDAP commands.
Troubleshooting
59-38 Administrator's Guide for Oracle Access Management
3. Verify that the page you requested is visible.
4. Optional: Check the Event Viewer to confirm that the access request was
successful.
59.13.2 Testing Single Sign-On for the SharePoint Server Integration
You can also test single sign-on by demonstrating that a user who has just supplied
credentials and accessed an SharePoint Server resource can (before the ObSSOCookie
expires) access a non-SharePoint Server resource without having to supply credentials
a second time. For example, use a resource defined in the Policy Manager.
When single sign-on is working, you should be granted access to the page without
having to supply credentials a second time.
To test single sign-on for your SharePoint Server integration
1. Create and protect a new virtual site with a Application Domain (or use one you
have already created.
2. Place a Web page anywhere in the tree of this virtual site.
3. Using a browser, navigate to the page in the new virtual site.
If you have already passed authentication, you should be granted access to the
page without having to supply credentials a second time.
59.14 Troubleshooting
■Internet Explorer File Downloads Over SSL Might Not Work
59.14.1 Internet Explorer File Downloads Over SSL Might Not Work
This issue may occur if the server sends a
Cache-control:no-store
header or sends a
Cache-control:no-cache
header. The WebGate provides configuration parameters to
control setting these headers. Following are the parameters and their default value:
CachePragmaHeader
no-cache
CacheControlHeader
no-cache
You can modify the WebGate configuration not to set these headers at all (the values
for these parameters would be kept blank). By this, it would mean that Access
Manager will not control the caching behavior.
60
Integrating Access Manager with Outlook Web Application 60-1
60
Integrating Access Manager with Outlook Web
Application
In a Windows environment, after a user authenticates, the authenticating application
can impersonate that user's identity. The primary purpose of impersonation is to
trigger access checks against a client's identity.
This chapter focuses on how to enable impersonation in Access Manager to override
impersonation enabled with IIS. The following topics are provided:
■What is New in This Release?
■Introduction to Integration with Outlook Web Application
■Enabling Impersonation With a Header Variable
■Setting Up Impersonation for Outlook Web Application (OWA)
■Setting Up Access Manager WNA for Outlook Web Application
60.1 What is New in This Release?
Support for integration between Access Manager and Outlook Web Application
(OWA) 2010.
This chapter illustrates:
■Enabling Impersonation With a Header Variable
■Setting Up Impersonation for Outlook Web Application (OWA)
■Setting Up Access Manager WNA for Outlook Web Application
60.2 Introduction to Integration with Outlook Web Application
This section provides the following information to introduce the integration described
in this chapter:
■About Impersonation Provided by Microsoft Windows
■About Access Manager 11g Support for Windows Impersonation
■About Single Sign-On for Authenticated Access Manager Users into Exchange
■About Confirming Requirements
Introduction to Integration with Outlook Web Application
60-2 Administrator's Guide for Oracle Access Management
60.2.1 About Impersonation Provided by Microsoft Windows
When running in a client's security context, a service can to an extent become a client.
After the user authenticates, the service can take on that user's identity through
impersonation. One of the service's threads uses an access token, known as an
impersonation token, to obtain access to objects the client can access. The access token
is a protected object that represents the client's credentials.
The impersonation token identifies the client, the client's groups, and the client's
privileges. The information in the token is used during access checks when the thread
requests access to resources on the client's behalf. When the server is impersonating
the client, any operations performed by the server are performed using the client's
credentials.
Impersonation ensures that the server can or cannot do exactly what the client can or
cannot do. Access to resources can be restricted or expanded, depending on what the
client has permission to do. Impersonation requires the participation of both the client
and the server. The client must indicate its willingness to let the server use its identity,
and the server must explicitly assume the client's identity programmatically.
When impersonation concludes, the thread uses the primary token to operate using
the service's own security context rather than the client's. The primary token describes
the security context of the user account associated with the process (the person who
started the application).
Services run under their own accounts and act as users in their own right. For
example, system services that are installed with the operating system run under the
Local System account. You can configure other services to run under the Local System
account, or separate accounts on the local system or in Active Directory.
The IIS Web server provides impersonation capabilities. However, the OAM Server
overrides IIS authentication, authorization, and impersonation functions. For more
information, see "About Access Manager 11g Support for Windows Impersonation" in
the next section.
60.2.2 About Access Manager 11g Support for Windows Impersonation
You can enable support for Windows impersonation to provide additional access
control for protected applications. You bind a trusted user to a Webgate and protect the
application with a application domain that includes an impersonation action in the
authorization rule. During the authorization process, the protected application creates
an impersonation token.
For more information, see, "Enabling Impersonation With a Header Variable." It
provides prerequisites and details about implementing impersonation using header
variables.
60.2.3 About Single Sign-On for Authenticated Access Manager Users into Exchange
This is also supported using the Windows Impersonation feature. Outlook Web Access
(OWA) provides Web access to Exchange mail services and may be configured on
either of the following:
■An IIS Web server that does not reside on the same host as the Exchange server,
which is also known as a front-end server
■An IIS Web server running on the same host as the Exchange server, which is also
known as the back-end server
Enabling Impersonation With a Header Variable
Integrating Access Manager with Outlook Web Application 60-3
In a front-end server configuration, the front-end OWA server authenticates the user,
determines the back-end Exchange server that hosts the user's mailbox, then proxies
the request to the appropriate back-end Exchange server. No additional credential
information is passed. No delegation is performed. Setting up Impersonation on the
back-end Exchange server ensures that the Exchange server does not need to request
credentials before granting access.
For more information, see "Setting Up Impersonation for Outlook Web Application
(OWA)."
60.2.4 About Confirming Requirements
The example in this chapter illustrates setting up the impersonation feature for the
OAM Server to Microsoft Exchange Server 2013 integration. The principles are the
same regardless of your application.
Any references to specific versions and platforms in this chapter are for demonstration
purposes. For the latest Access Manager certification information, see Oracle
Technology Network at:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
60.3 Enabling Impersonation With a Header Variable
Enabling impersonation with a header variable involves completing the procedures in
the following sections.
1. Reviewing all Requirements for Impersonation with a Header Variable
2. Creating an Impersonator as a Trusted User
3. Assigning Rights to the Trusted User
4. Binding the Trusted User to Your WebGate
5. Adding an Impersonation Response to An Application Domain
6. Adding an Impersonation DLL to IIS
7. Testing Impersonation
60.3.1 Requirements for Impersonation with a Header Variable
Prepare the environment and confirm that it is operating properly before
implementing Windows impersonation with the OAM Server.
Table 60–1 identifies the Access Manager platform requirements when you enable
impersonation using a header variable.
See Also: "Setting Up Impersonation for Outlook Web Application
(OWA)" on page 60-10.
Table 60–1 Requirements for Impersonation with a Header Variable
Item Platform
11g WebGate (and
Impersonation dll)
Microsoft IIS 7.x and Windows Server 2008 and 2013
Enabling Impersonation With a Header Variable
60-4 Administrator's Guide for Oracle Access Management
60.3.2 Creating an Impersonator as a Trusted User
Whether you enable impersonation using a HeaderVar or user profile attribute, the
return value must be a trusted user in Active Directory. This special user should not be
used for anything other than impersonation. The example in the following procedure
uses SPPSImpersonator as the New Object - User. With OWAImpersonator as
SPPSImpersonator denotes SharePoint impersonation specifically. Your environment
will be different.
1. Perform the steps for your environment on the computer hosting your Microsoft
Exchange Server 2013 installation:
■Windows 2008 or 2012: Select Start, Programs, Administrative tools, Active
Directory Users and Computers.
2. In the Active Directory Users and Computers window, right-click Users on the tree
in the left pane, then select New; User.
3. In the First name field of the pane entitled New Object - User, enter an
easy-to-remember name such as SPPSImpersonator.
4. Copy this same string to the User logon name field, then click Next.
5. In succeeding panels, you are asked to choose a password and then retype it to
confirm.
Impersonation dll Webgate_install_
dir\webgate\iis\lib\IISImpersonationModule.dll
■Must be installed as an IIS Module.
■May be installed at any level of the Web site tree.
Kerberos Key Distribution
Center (KDC) and Active
Directory
Windows Server 2008 and 2013
Client and Server machines ■Both must be in the same Windows Server 2008 domain
with a trust relationship.
■A bi-directional trust path is required because the service,
acting on the client's behalf, must request tickets from the
client's domain.
Security context Must have Act as operating system privileges.
Note: IWAM_Machine is not recommended
Mutual authentication is
required
Mutual authentication is supported remotely.
Note: Oracle recommends that you choose a very complex
password, because your trusted user is being given very powerful
permissions. Also, be sure to check the box marked Password Never
Expires. Since the impersonation module should be the only entity
that ever sees the trusted user account, it would be very difficult for
an outside agency to discover that the password has expired.
Table 60–1 (Cont.) Requirements for Impersonation with a Header Variable
Item Platform
Enabling Impersonation With a Header Variable
Integrating Access Manager with Outlook Web Application 60-5
Figure 60–1 Setting up a Trusted User Account for Windows Impersonation
60.3.3 Assigning Rights to the Trusted User
Follow this procedure to give the trusted user the right to act as part of the operating
system
1. Perform the appropriate step for your environment:
■Windows 2008: Select Start > Programs > Administrative tools > Local
Security Policy.
You must modify the group policy object that applies to the computer where
the Webgate is installed.
2. On the tree in the left pane, click the plus icon (+) next to Local Policies.
3. Click User Rights Assignment on the tree in the left pane.
4. Double-click "Act as part of the operating system" in the right pane.
5. Click Add User or Group.
6. In the Add User or Group panel, type the User logon name of the trusted user
(Microsoft Exchange Server 2010 Impersonator in our example) in the User and
group names text entry box, then click OK to register the change.
Enabling Impersonation With a Header Variable
60-6 Administrator's Guide for Oracle Access Management
Figure 60–2 Configuring Rights for the Trusted User in Windows Impersonation
60.3.4 Binding the Trusted User to Your WebGate
You need to bind the trusted user to the WebGate by supplying the authentication
credentials for the trusted user, as described in this procedure. The procedure
presumes that you have registered an 11g WebGate with Access Manager. The values
in the procedure are provided as an example only. Your environment will be different.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, click Agents.
3. Find the desired 11g WebGate registration to modify for this integration:
■Find All Enabled: Select State All, click the Search button, click the desired
Webgate name in the results list.
4. On the WebGate registration page, enter the SharePoint username and password
for the trusted user account, which you created earlier.
5. Click Apply to commit the changes.
A bind has been created for the WebGate and the trusted user. The WebGate is
now ready to provide impersonation on demand. The demand is created by an
Authorization Success Action in the application domain created for
impersonation.
60.3.5 Adding an Impersonation Response to An Application Domain
You must create or configure an application domain to protect your OWA resources.
For this you must add Responses in Authorization Policies (Header type Responses),
as described in this procedure.
See Also: Chapter 15, "Registering and Managing OAM 11g Agents"
See Also: Chapter 25, "Managing Policies to Protect Resources and
Enable SSO" in the Oracle Fusion Middleware Administrator's Guide for
Oracle Access Management.
Enabling Impersonation With a Header Variable
Integrating Access Manager with Outlook Web Application 60-7
The procedure presumes that you have an application domain created for the 11g
WebGate you registered. The application domain in this example is
MyImpersonationDomain. Your environment will be different.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. Click Application Domains in the Access Manager section.
3. Search for and open the OWA Application Domain (the relevant application
domain for impersonation).
Navigate as follows:
Authorization Policies
Protected Resource Policy
Responses
4. Click the Add button, then Add Response.
Complete the form as follows:
■From the Type list, choose Header.
■In the Name field, type a unique name for this response. For example,
IMPERSONATE.
■In the Valu e field, type a value for this response. For example, $user.userid.
5. Click Add, then click Apply to submit the changes.
This Response is used for the second WebGate request (for authorization).
60.3.6 Adding an Impersonation DLL to IIS
You are ready to configure IIS by adding the
IISImpersonationModule.dll
to your IIS
configuration.
1. Select Start > Administrative Tools > Internet Information Services (IIS)
Manager.
2. In the left pane of IIS 7.x, click the hostname.
3. In the middle pane, under the "IIS" header, double click on "Modules".
4. In the right pane, click "Configure Native Modules" and click "Register".
5. In the window, provide a module Name (for example, Oracle Impersonation
Module).
6. In the Path field, type the full path to
IISImpersonationModule.dll
.
By default, the path is:
Webgate_install_dir\webgate\iis\lib\IISImpersonationModule.dll
Where Webgate_install_dir is the directory of your WebGate installation.
7. Click OK to register the module.
Note: If any spaces exist in the path (for example,
C:\Program
Files\Oracle\...
) surround the entire string with double quotes (" ").
Enabling Impersonation With a Header Variable
60-8 Administrator's Guide for Oracle Access Management
8. Check the name of the newly created module and click OK to apply the module
across the Web sites.
9. Remove the module from the Default site level (otherwise, it inherits when you
add it on the machine level).
10. Ensure that the
IISImpersonationModule.dll
file added in these steps is applied
only to "owa" and "ecp" applications and removed from the site level.
Go to OWA, double-click modules, Configure Native Modules, and check the
desired module (for example, Oracle Impersonation Module).
Go to (ecp): Double-click modules, Configure Native Modules, and check the
desired module (for example, Oracle Impersonation Module).
60.3.7 Testing Impersonation
You can test Impersonation in the following two ways:
■Testing Impersonation Using the Event Viewer
■Testing Impersonation using a Web Page
60.3.7.1 Creating an IIS Virtual Site
To test the impersonation feature outside the Microsoft OWA 2010 context or to test
single sign-on, you will need a target Web page on an IIS virtual Web site You create
such a virtual Web site by performing the following task.
1. Click Start > Administrative Tools > Internet Information Services (IIS)
Manager.
2. Click the plus icon (+) to the left of the local computer icon on the tree in the left
pane.
3. Right-click Web Sites on the tree in the left pane, then select New, then select Web
Site on the menu.
4. Respond to the prompts by the Web site creation wizard.
5. After you create the virtual site, you must protect it with an application domain, as
described elsewhere in this guide.
60.3.7.2 Testing Impersonation Using the Event Viewer
When you perform impersonation testing using the Windows 2008 Event Viewer, you
must configure the event viewer before conducting the actual test.
1. Select Start Menu > Event Viewer.
2. In the left pane, right-click Security, then click Properties.
3. Click the Filter tab on the Security property sheet.
4. Verify that all Event Types are checked and the Event Source and Category lists are
set to All, then click OK to dismiss the property sheet.
Your Event Viewer is now configured to display information about the headerVar
associated with a resource request.
Enabling Impersonation With a Header Variable
Integrating Access Manager with Outlook Web Application 60-9
Figure 60–3 Verifying Event Viewer Settings
5. Create a new IIS virtual server (virtual site).
6. Place a target Web page anywhere in the tree on the virtual site.
7. Point your browser at the Web page
If impersonation is working correctly, the Event Viewer will report the success of
the access attempt.
60.3.7.3 Testing Impersonation using a Web Page
You can also test impersonation using a dynamic test page, such as a
.asp
page or a
Perl script, that can return and display information about the request.
1. Create a
.asp
page or Perl script that will display the parameters AUTH_USER
and IMPERSONATE. It can resemble the sample page presented in the following
listing:
<TABLE border=1>
<TR>
<TD>Variable</TD>
<TD>&nbsp&nbsp</TD>
<TD>Value</TD></TR>
<%for each servervar in request.servervariables%>
<TR>
<TD><%=servervar%></TD>
<TD>&nbsp&nbsp</TD>
<TD><%=request.servervariables(servervar)%>&nbsp</TD>
</TR>
2. Create an IIS virtual site, or use the one you created for the previous task.
3. Place a
.asp
page or Perl script (such as the sample in the preceding listing)
anywhere in the tree of the new virtual site.
4. Point your browser at the page. The page should display, with both AUTH_USER
and IMPERSONATE set to the name of the user making the request.
Setting Up Impersonation for Outlook Web Application (OWA)
60-10 Administrator's Guide for Oracle Access Management
60.4 Setting Up Impersonation for Outlook Web Application (OWA)
In a distributed Exchange/OWA single sign-on environment, each server needs Access
Manager to impersonate the current user. When you enable Impersonation, you need
to include additional HTTP headers in the "Response" tab of the Authorization Policy
of your impersonation application domain.
The following solution has been tested in both standalone and distributed OWA
environments.
1. Install Access Manager 11g, as described in the Oracle Fusion Middleware Installation
Guide for Oracle Identity and Access Management.
2. Install a 11g WebGate on all OWA client servers, as described in the Oracle Fusion
Middleware Administrator's Guide for Oracle Access Management.
3. On the WebGate registration page, Disable IP Checking for Webgates on the
back-end server using the AccessGate (because the request comes from the
front-end server, not from the user's browser).
4. Ensure that OWA is not using Integrated Windows Authentication, as described in
"Prerequisites to Setting Impersonation for Outlook Web Application" on
page 60-10.
5. Create a trusted user account for only impersonation in the Active Directory, as
described in "Creating a Trusted User Account for Outlook Web Application" on
page 60-11.
6. Give the trusted user the special right to act as part of the operating system, as
described in "Assigning Rights to the Outlook Web Application Trusted User" on
page 60-11.
7. Bind the trusted user to the WebGate by supplying the authentication credentials
for the trusted user, as described in "Binding the Trusted Outlook Web Application
User to Your WebGate" on page 60-11.
8. Add a header variable named impersonate to the Authorization Policy Response
tab (in the impersonation application domain), as described in, as described in
"Adding an Impersonation Action to an Application Domain for Outlook Web
Application" on page 60-12.
9. Configure IIS by adding
IISImpersonationModule.dll
to your IIS configuration,
as described in "Adding an Impersonation dll to IIS" on page 60-13.
10. Test Impersonation, as described in "Testing Impersonation for Outlook Web
Application" on page 60-14.
60.4.1 Prerequisites to Setting Impersonation for Outlook Web Application
Before setting Impersonation for Outlook Web Application, ensure that OWA is not
using Integrated Windows (or any other) Authentication. If it is not, you can use the
following steps to set up OWA with Windows Authentication.
1. Open Exchange Management console.
2. Go to Server Configuration and click Client Access.
3. Select Outlook Web Access and click Properties.
4. In the Properties dialog box, click the Authentication tab.
See Also: "Enabling Impersonation With a Header Variable" on
page 60-3.
Setting Up Impersonation for Outlook Web Application (OWA)
Integrating Access Manager with Outlook Web Application 60-11
5. Clear (unselect) all the authentication methods.
6. Click Apply, and click OK.
7. Restart the IIS server.
8. Proceed with "Creating a Trusted User Account for Outlook Web Application."
60.4.2 Creating a Trusted User Account for Outlook Web Application
This special user should not be used for anything other than impersonation.
Oracle recommends that you chose a very complex password, because your trusted
user is being given very powerful permissions. Also, be sure to check the box marked
Password Never Expires. Since the impersonation module should be the only entity
that ever sees the trusted user account, it would be very difficult for an outside agency
to discover that the password has expired.
1. On the Windows 2008 machine, select Start; Programs; Administrative tools,
Active Directory Users and Computers.
2. In the Active Directory Users and Computers window, right-click Users on the tree
in the left pane, then select New; User.
3. In the First name field of the pane entitled New Object - User, enter an
easy-to-remember name such as OWAImpersonator.
4. Copy this same string to the User logon name field, then click Next.
5. In succeeding panels, you will be asked to choose a password and then retype it to
confirm.
6. Proceed to "Assigning Rights to the Outlook Web Application Trusted User" on
page 60-11.
60.4.3 Assigning Rights to the Outlook Web Application Trusted User
You need to give the trusted user the right to act as part of the operating system.
1. Select Control Panel, Administrative Tools; and click either the Domain Controller
Security Policy (if the computer is a domain controller) or Local Security Policy.
2. On the tree in the left pane, click the plus icon (+) next to Local Policies.
3. Click User Rights Assignment on the tree in the left pane.
4. Double-click "Act as part of the operating system" in the right pane.
5. Click Add User or Group.
6. In the Add User or Group panel, type the User logon name of the trusted user
(OWAImpersonator in our example) in the User and group names text entry box,
then click OK to register the change.
7. Proceed to "Binding the Trusted Outlook Web Application User to Your WebGate."
60.4.4 Binding the Trusted Outlook Web Application User to Your WebGate
You need to bind the trusted user to the WebGate by supplying the authentication
credentials for the trusted user, as described in the following procedure.
When the bind has been created for the WebGate and the trusted user, WebGate is
ready to provide impersonation on demand. The demand is created by a Response set
in the Authorization Policy of application domain created for impersonation.
Setting Up Impersonation for Outlook Web Application (OWA)
60-12 Administrator's Guide for Oracle Access Management
The following procedure presumes that you have registered a 11g WebGate
(ImpersonateAgent) with Access Manager. The values in the following procedure are
provided as an example only. Your environment will be different.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. in the Launch Pad tab, click Agents.
3. Find the desired 11g WebGate registration to modify for this integration. For
example: ImpersonateAgent.
■Find All Enabled: Select State All, click the Search button, click the desired
Webgate name in the results list.
4. Open the Webgate registration page and enter the SharePoint username and
password for the trusted user account, which you created earlier.
5. Click Apply to commit the changes.
A bind has been created for the Webgate and the trusted user. The Webgate is now
ready to provide impersonation on demand. The demand is created by an
Authorization Success Action in the application domain created for
impersonation.
60.4.5 Adding an Impersonation Action to an Application Domain for Outlook Web
Application
You must create or configure a application domain to protect your OWA resources
(/owa and /ecp only).
The Authorization policy must set several HTTP Header variables (Header type
Responses in the Authorization policy).
This procedure presumes that you have an existing application domain for the 11g
WebGate (ImpersonateAgent) you registered with Access Manager.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. Click Application Domains in the Access Manager section.
3. Search for and open the OWA2010 Application Domain (the relevant application
domain for impersonation).
Navigate as follows:
See Also: Chapter 15, "Registering and Managing OAM 11g Agents"
in the Oracle Fusion Middleware Administrator's Guide for Oracle Access
Management
Note: Ensure that
IISImpersonation Module.dll
is applied only to
"owa" and "ecp" applications in IIS7.x, and removed from the site
level.
See Also: The chapter on managing policies to protect resources and
enable SSO in the Oracle Fusion Middleware Administrator's Guide for
Oracle Access Management.
Setting Up Impersonation for Outlook Web Application (OWA)
Integrating Access Manager with Outlook Web Application 60-13
Authorization Policies
Protected Resource Policy
Responses
4. Click the Add button, then Add Response.
Complete the form as follows:
■From the Type list, choose Header.
■In the Name field, type a unique name for this response. For example,
IMPERSONATE.
■In the Valu e field, type a value for this response. For example, $user.userid.
5. Click Add, then click Apply to submit the changes.
6. Go to the next section, "Adding an Impersonation DLL to IIS."
This Response is used for the second Webgate request (for authorization).
60.4.6 Adding an Impersonation dll to IIS
You are ready to configure IIS by adding the
IISImpersonationModule.dll
to your IIS
configuration. You also need to set Enable Anonymous Access because this is required
for impersonation of a user.
1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
2. In the left pane of IIS 7.x, click the hostname.
3. In the middle pane, under the IIS header, double click on Modules.
4. In the right pane, click Configure Native Modules and click Register.
5. In the window, provide a module Name (for example, Oracle Impersonation
Module).
6. In the Path field, type the full path to
IISImpersonationModule.dll
.
By default, the path is:
Webgate_install_dir\webgate\iis\lib\IISImpersonationModule.dll
Where Webgate_install_dir is the directory of your WebGate installation.
7. Click OK to register the module.
8. Check the name of the newly created module and click OK to apply the module
across the Web sites.
60.4.7 Configuring IIS Security
Be sure to configure IIS Security before you continue. Figure 60–4 shows an example.
Note: If any spaces exist in the path (for example,
C:\Program
Files\Oracle\...
) surround the entire string with double quotes (" ").
Setting Up Impersonation for Outlook Web Application (OWA)
60-14 Administrator's Guide for Oracle Access Management
Figure 60–4 Impersonation Authentication
1. Select Start, Administrative Tools, Internet Information Services (IIS) Manager.
2. Click the plus icon (+) to the left of the local computer icon on the tree in the left
pane.
3. Click Web Sites on the tree in the left pane.
4. In the center pane, double-click Authentication under IIS.
5. Ensure that Anonymous Authentication is enabled and Windows Authentication
is disabled.
60.4.8 Testing Impersonation for Outlook Web Application
The following options are provided to test the Impersonation configuration for OWA.
■Testing Impersonation Using the Event Viewer
■Testing Impersonation using a Web Page
60.4.8.1 Testing Impersonation Using the Event Viewer
Use this procedure to test impersonation through the Event Viewer.
1. Select Start Menu; Event Viewer.
2. In the left pane, right-click Security, then click Properties.
3. Click the Filter tab on the Security property sheet.
4. Verify that all Event Types are checked, and the Event Source and Category lists
are set to All, then click OK to dismiss the property sheet.
5. Your Event Viewer is now configured to display information about the headerVar
associated with a resource request.
6. Create a new IIS virtual server (virtual site).
7. Place a target Web page anywhere in the tree on the virtual site.
8. From your browser, enter the URl to the Web page.
If impersonation is working correctly, the Event Viewer will report the success of
the access attempt.
Setting Up Access Manager WNA for Outlook Web Application
Integrating Access Manager with Outlook Web Application 60-15
60.4.8.2 Testing Impersonation using a Web Page
You can also test impersonation using a dynamic test page that can return and display
information about the request.
1. Create
a.asp
page or Perl script that will display the parameters
AUTH_USER
and
IMPERSONATE
.
It can resemble this sample page:
<TABLE border=1>
<TR>
<TD>Variable</TD>
<TD>&nbsp&nbsp</TD>
<TD>Value</TD></TR>
<%for each servervar in request.servervariables%>
<TR>
<TD><%=servervar%></TD>
<TD>&nbsp&nbsp</TD>
<TD><%=request.servervariables(servervar)%>&nbsp</TD>
</TR>
2. Create an IIS virtual site, or use the one you created for the previous task.
3. Place the
a.asp
page or Perl script (such as the sample in the preceding listing)
anywhere in the tree of the new virtual site.
4. Point your browser at the page, which should appear, with both
AUTH_USER
and
IMPERSONATE
set to the name of the user making the request.
60.4.8.3 Conducting Negative Testing for Impersonation
To conduct negative testing for impersonation, you need to unbind the trusted user
from the WebGate, as explained in the following procedure.
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, click Agents.
3. Search for the desired WebGate and open it for editing.
4. In the WebGate registration page, remove the credentials for the trusted user.
5. Click Apply to save the change.
6. Restart the IIS server and in a browser window, go to a protected code page
(previously accessible to the trusted user).
7. Confirm that you receive a message page. Values for
AUTH_USER
and
IMPERSONATE
are necessary for impersonation credentials to be bound to a Webgate.
8. Restore the trusted user to the WebGate registration page.
60.5 Setting Up Access Manager WNA for Outlook Web Application
Access Manager 11g can operate with Windows Native Authentication (WNA). This
section describes setting up Access Manager with Windows Native Authentication
(WNA) for Outlook Web Application (OWA).
Enabling WNA for the IIS Site front-ending OWA is described in the following
procedure. It presumes a fully-configured Microsoft Active Directory authentication
service is set up with user accounts to map Kerberos services, Service Principal Names
Setting Up Access Manager WNA for Outlook Web Application
60-16 Administrator's Guide for Oracle Access Management
(SPNs) for those accounts, and key tab files. For more information, see Oracle Fusion
Middleware Securing Oracle WebLogic Server 11g Release 1 (10.3.3) E13707-03.
You need to configure Access Manager to use Windows Native Authentication
(WNA), as described in Chapter 57, "Configuring Access Manager for Windows
Native Authentication."
1. Perform all prerequisite tasks.
2. Open IIS Authentication (OWA on the front-ending Site).
3. Enable Windows authentication.
4. Click on Provider.
5. Add Negotiate to Provider and move it to the top of the list.
6. Create a policy to protect OWA in IIS, as described in the Oracle Fusion Middleware
Administrator's Guide for Oracle Access Management.
61
Integrating Microsoft Forefront Threat Management Gateway 2010 with Access Manager 61-1
61
Integrating Microsoft Forefront Threat
Management Gateway 2010 with Access
Manager
This chapter describes how to configure communication between Access Manager and
Microsoft Forefront Threat Management Gateway (TMG) 2010. The following sections
are provided:
■What is New in This Release?
■Introduction to Integration with TMG Server 2010
■Creating a Forefront TMG Policy and Rules
■Installing and Configuring 10g Webgate for Forefront TMG Server
■Configuring the TMG 2010 Server for the ISAPI 10g Webgate
■Starting, Stopping, and Restarting the TMG Server
■Removing Access Manager Filters Before WebGate Uninstall on TMG Server
■Troubleshooting
61.1 What is New in This Release?
Support for integration between Access Manager and Microsoft Forefront Threat
Management Gateway (TMG) 2010.
Details in this chapter presume that you are familiar with Access Manager policies and
operation.
61.2 Introduction to Integration with TMG Server 2010
This section provides an overview of the tasks that, once performed, enable this
integration. Topics included are:
■About This Integration
■About Confirming Certification Requirements
61.2.1 About This Integration
Microsoft Forefront Threat Management Gateway (TMG) 2010 is the next generation of
the Internet Security and Acceleration (ISA) Server 2006. This chapter provides steps to
configure an open (non-secured) connection between the Forefront TMG Web server
and Access Manager. This communication is based on using a 10g Webgate for ISAPI.
Creating a Forefront TMG Policy and Rules
61-2 Administrator's Guide for Oracle Access Management
For details about using a secured connection, see your Forefront TMG Server
documentation.
You can have IIS Web server and Forefront TMG installed on same or on different
computer. In examples in ths chapter, both reside on same host.
The following overview outlines the tasks that you must perform and the topics where
you will find the steps to set up the ISAPI Webgate with the TMG Server within this
chapter.
Task overview: Installing and configuring the ISAPI Webgate on TMG Server
1. Getting the latest certification matrix as described in "About Confirming
Certification Requirements".
2. "Creating a Forefront TMG Policy and Rules"
3. "Installing and Configuring 10g Webgate for Forefront TMG Server"
4. "Configuring the TMG 2010 Server for the ISAPI 10g Webgate"
61.2.2 About Confirming Certification Requirements
Any references to specific versions and platforms in this chapter are for demonstration
purposes. For the latest certification information, see Oracle Technology Network at:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
61.3 Creating a Forefront TMG Policy and Rules
After you install Forefront TMG 2010, other computers cannot ping the computer
hosting Forefront because the default firewall policy denies all the traffic from and to
the host. This section provides the information you need for:
■Creating a Custom Policy for Forefront TMG
■Creating a Forefront TMG Firewall Policy Rule
■Verifying Forefront TMG Proxy Configuration
61.3.1 Creating a Custom Policy for Forefront TMG
Use the following procedure to create a custom Forefront firewall policy.
Prerequisites
Install Forefront TMG 2010 using documentation from your vendor.
To create a custom policy to over ride the default firewall policy
1. Open the Forefront TMG console: Start, Programs, Microsoft Forefront TMG,
Forefront TMG Management.
2. From the left pane, click Firewall Policy.
3. From the right pane, click Create Access Rule to create a custom policy,
4. Create a rule with the following attributes and values assigned:
■Name: Name for custom policy
■Action =Allow
■Protocol =All Outbound
Creating a Forefront TMG Policy and Rules
Integrating Microsoft Forefront Threat Management Gateway 2010 with Access Manager 61-3
■Malware Inspection = Don not enable Malware Inspection for this rule
■From =External,Internal,Local Host
■To= External,Internal,Local Host
■Condition =All Users
5. Click Next to create the Access Rule, then click Apply.
6. Restart Forefront TMG to have changes take affect:
■Stop Firewall Service use the command
net stop fwsrv
■Start Firewall Service use the command
net start fwsrv
7. Proceed to "Creating a Forefront TMG Firewall Policy Rule"
61.3.2 Creating a Forefront TMG Firewall Policy Rule
To protect the resource, you must create a firewall policy rule using the Forefront TMG
console as described in the following procedure.
When you create a listener for Authentication Preferences, be sure to check Allow
client authentication over HTTP and Require All users to authenticate. Otherwise, you
will not be able to access the published Web site using the TMG proxy.
Authentication Delegation is used by the TMG server to authenticate to the published
Web server.
To create a custom policy to override the default firewall policy
1. Open the Forefront TMG console: Start, Programs, Microsoft Forefront TMG,
Forefront TMG Management.
2. From the left pane, click Firewall Policy.
3. From the Tasks tab, click Publish Web Sites.
4. In the Web publishing rule name field, type a descriptive name for the rule, and
then click Next.
5. On the Select Rule Action page, confirm that the Allow option is selected, and then
click Next.
6. In the Publishing type, confirm that the Publish a single Web site or load balancer
option is selected, and then click Next.
Step 7 describes configuration with an open (non-secured) connection with the
Web server. If you are using a secured connection, see your Forefront TMG Server
documentation.
7. On the Server Connection Security page, click Use non-secured connections to
connect the published Web server or server farm, and then click Next.
8. Perform the following steps to set internal publishing details:
■In the Internal site name field, type the internally-accessible name of the
IIS/apache Web server host:
iis_host.us.example.com
, for example.
■Check the box beside Use a computer name or IP address to connect to the
published serve (or enter the IP address of the IIS Web server host).
Note: You can have IIS and Forefront TMG installed on the same (or
a different) computer. Here, both reside on same host.
Creating a Forefront TMG Policy and Rules
61-4 Administrator's Guide for Oracle Access Management
■Click Next.
9. Protecting Resources: Perform following steps to protect resources within a
particular folder in the Web site (or a single resource):
■Folder Containing Resources: In the Path field, type the folder name to display
the full path of the published Web site in the Web site field (Res/* for
example).
■Single Resource: Type the resource name (
test.html
for example).
■Click Next.
10. In the Accept requests for list:
■Click your domain name (for example:
myhost.example.com
).
■In the Public name field, type the publicly-accessible fully-qualified Web site
domain name of the host where Forefront TMG will be installed (for example:
myhost.example.com
).
■Click Next.
11. In the Web listener list, either click the Web listener to use for this Web publishing
rule, or create a new Web listener as follows:
■Click New, type a descriptive name for the new Web listener, and then click
Next.
■Click Do not require SSL secured connections with clients, and then click
Next.
■In the Listen for requests from these networks list, click the required networks
(External, Internal, and Localhost) then click Next.
■Click No on the message that appears.
■In the Select how clients will provide credentials to Forefront TMG Server list,
click No Authentication, and then click Next.
■On the Single Sign On Settings page, click Next, and then click Finish.
12. On the Select Web Listener page:
■Click Edit.
■Click connections tab.
■Provide any unused port for Enable HTTP connections on port attribute (This
will act as Forefront TMG port.)
■Click Apply; click Ok.
■Click Next.
■On the Single Sign On Settings page, click Next, and then click Finish.
Note: The folder must reside within htdocs/wwwroot of the
corresponding Web server.
Note: Listener can also be configured in SSL mode if required; see
your Forefront TMG documentation.
Creating a Forefront TMG Policy and Rules
Integrating Microsoft Forefront Threat Management Gateway 2010 with Access Manager 61-5
13. Authentication Delegation: Perform the following steps to choose the method used
by Forefront TMG to authenticate to the published Web server list.
■Click No Delegation, and Client Cannot Authenticate Directly.
■Click Next.
14. On the User Sets page:
■Choose All (the default user setting - All Users) to set the rule that applies to
requests from the user sets field.
■Click Next, and then click Finish.
15. Click Apply to update the firewall policy, and then click OK.
16. Double-click the recently created Firewall Policy.
17. Bridging:
■Open the Bridging tab.
■Provide suitable unused port for Redirect request to HTTP port attribute
(which will act as the IIS or Apache Web server port).
18. Click Apply to update the firewall policy, and then click OK.
19. IIS or Apache Web server.
20. Restart Forefront TMG to have changes take affect:
■Stop Firewall Service use the command net stop fwsrv
■Start Firewall Service use the command net start fwsrv
21. Double-click the rule just created:
■Open the Link Translation tab.
■Confirm that Apply Link Translation to this rule is checked.
■Click the Mapping button to see the mapping created between Forefront TMG
and IIS or Apache
22. Proceed to "Verifying Forefront TMG Proxy Configuration"
61.3.3 Verifying Forefront TMG Proxy Configuration
To validate the Forefront TMG proxy configuration, you can simply access the
protected resource using the TMG port, as described in the following procedure.
To verify Forefront TMG proxy configuration
1. Protected Single Resource: Enter the URL to the TMG host and port where the
protected resource resides. For example:
http://TMG_hostname:TMG_port/resource_name
2. Protected Folder: Enter the URL to the TMG host and port where the folder
containing the resource resides. For example:
http://TMG_hostname:TMG_port/folder-name/resource_name
3. Confirm there are no issues accessing the protected resource.
Installing and Configuring 10g Webgate for Forefront TMG Server
61-6 Administrator's Guide for Oracle Access Management
61.4 Installing and Configuring 10g Webgate for Forefront TMG Server
This section describes how to set up the 10g Webgate and register plug-ins as Web
filters.
Task overview: Configuring Webgateand Filters for TMG Server includes
1. Installing 10g Webgate with TMG Server
2. Changing /access Directory Permissions
3. Registering Access Manager Plug-ins as TMG Server Web Filters
4. Ordering the ISAPI Filters
5. Verifying Form-based Authentication
61.4.1 Installing 10g Webgate with TMG Server
When you install Webgate with the Forefront TMG Server, the destination for the
ISAPI Webgate installation (also known as the Webgate_install_dir) should be same as
that of the Microsoft Forefront TMG. For example, if Forefront TMG is installed in
C:\Program Files\Microsoft Forefront Threat Management Gateway
, the ISAPI
Webgate should also be installed there.
Task overview: Installing the ISAPI Webgate for Forefront TMG Server
1. Register a 10g ISAPI Webgate with Access Manager, as described in Chapter 30,
"Registering and Managing 10g WebGates with Access Manager 11g."
2. Install the ISAPI Webgate for TMG, as described in Section 30.7, "Locating and
Installing the Latest 10g WebGate for Access Manager 11g."
3. Proceed to the "Changing /access Directory Permissions" section.
61.4.2 Changing /access Directory Permissions
After finishing ISAPI Webgate installation and configuration for the Forefront TMG
Server, you must change permissions to the
\access
subdirectory. This subdirectory
was created in the Forefront TMG Server (also Webgate) installation directory. You
must add the user NETWORK SERVICE and grant full control to SYSTEM
ADMINISTRATOR.
This enables the Forefront TMG Server to establish a connection between the Webgate
and Access Server. Certain configuration files should be readable by system
administrators, which is why you grant SYSTEM ADMINISTRATOR full control.
To change permissions for the \access subdirectory
1. In the file system, right-click Webgate_install_dir
\access
, and select Properties.
2. In the Properties window, click the Security tab.
Note: During Webgate installation, select the TMG option.
Note: Webgate in Simple Mode: add user NETWORK SERVICE and
give Full Control for the
password.xml
file in TMG_install_
dir
\access\oblix\config\password.xml
.
Configuring the TMG 2010 Server for the ISAPI 10g Webgate
Integrating Microsoft Forefront Threat Management Gateway 2010 with Access Manager 61-7
3. Add user "NETWORK SERVICE" and then select "Allow" to give "Full Control".
4. For the "SYSTEM ADMINISTRATOR", select "Full Control".
5. Proceed to the "Configuring the TMG 2010 Server for the ISAPI 10g Webgate"
section.
61.5 Configuring the TMG 2010 Server for the ISAPI 10g Webgate
The following topics describe how to configure the TMG Server to operate with the
10g ISAPI Webgate for Access Manager.
Task overview: Configuring the TMG 2010 Server for the ISAPI 10g Webgate
1. Registering Access Manager Plug-ins as TMG Server Web Filters
2. Ordering the ISAPI Filters
3. Verifying Form-based Authentication.
61.5.1 Registering Access Manager Plug-ins as TMG Server Web Filters
After resetting ISAPI Webgate permissions, you need to register Access Manager
webgate.dll
and
postgate.dll
plug-ins as Web Filters within Forefront TMG Server.
Web filters screen all HTTP traffic that passes through the TMG Server host. Only
compliant requests are allowed to pass through.
The following procedure describes how to register Access Manager plug-ins in the
TMG Server.
To register Access Manager plug-ins as TMG Server Web filters
1. Locate the TMG Server installation directory, from which you will perform the
following tasks.
2. Run
net stop fwsrv
to stop the TMG Server.
3. Register the
webgate.dll
as an ISAPI Web filter by running:
regsvr32 TMG_install_dir\access\oblix\apps\webgate\bin\webgate.dll
4. Register the
postgate.dll
as an ISAPI Web filter by running:
regsvr32 TMG_install_dir\access\oblix\apps\webgate\bin\postgate.dll
5. Restart the TMG Server by running
net start fwsrv
.
6. Proceed to "Ordering the ISAPI Filters".
61.5.2 Ordering the ISAPI Filters
It is important to ensure that the Webgate ISAPI filters are included in the right order.
postgate.dll
should be loaded before
webgate.dll
.
Note: To undo the filter registration, you can use the following
procedure with the
/u
option in the
regsvr32
command. For example:
regsvr32 /u TMG_install_
dir\access\oblix\apps\webgate\bin\webgate.dll
Starting, Stopping, and Restarting the TMG Server
61-8 Administrator's Guide for Oracle Access Management
To order the Webgate ISAPI filters for TMG Server
1. From the Start menu, click All Programs, click Microsoft Forefront TMG, then
click Forefront TMG Management.
2. In the left pane, select System, then select Web Filters, to display your Web-filters.
3. Confirm the following .dll files appear.
For example:
postgate.dll
webgate.dll
4. Add any missing filters, if needed, then select a filter name and use the up and
down arrows to arrange the filter order as shown in Step 3.
5. Proceed with "Verifying Form-based Authentication".
61.5.3 Verifying Form-based Authentication
Here you ensure that the published Web site is accessible using the TMG proxy and
verify that form-based authentication is working.
TMG supports both Basic over LDAP and Form-based or Basic authentication. You can
choose the desired authentication scheme. TMG need access to
login.html
, which you
configure as described here.
To verify that form-based authentication is working
1. Store the login page at the docroot of the Web server protecting the resource so
that the TMG server can access the login page.
2. Ensure that the published Web site is accessible to the TMG proxy.
3. Open the Forefront TMG console: Start, Programs, Microsoft Forefront TMG,
Forefront TMG Management.
4. From the left pane, select the Firewall Policy.
5. On the right, under the Firewall Policy Rule, select the rule that was created to
protect the resource.
6. Go to the policy rule properties, select the Path tab, then add the
/login.html
and
click OK.
7. Click Apply to save changes and update the configuration.
8. Restart Forefront TMG to have changes take affect:
■Stop Firewall Service use the command net stop fwsrv
■Start Firewall Service use the command net start fwsrv
61.6 Starting, Stopping, and Restarting the TMG Server
When instructed to restart your TMG Server during Access Manager Web component
installation or setup, be sure to follow any instructions that appear on the screen. Also,
the
net
commands help to ensure that the Metabase does not become corrupted
following an installation. Consider the following commands, hich provide good ways
to stop and start the TMG Server:
■net stop fwsrv
■net start fwsrv
Troubleshooting
Integrating Microsoft Forefront Threat Management Gateway 2010 with Access Manager 61-9
For more information, see your TMG Server documentation.
61.7 Removing Access Manager Filters Before WebGate Uninstall on
TMG Server
If you plan to uninstall the Webgate that is configured to operate with the TMG Server,
you must first unregister the Access Manager filters manually, and then uninstall
Webgate.
To unregister filters before WebGate uninstall
1. Stop the TMG Server.
2. Run the following command to unregister
webgate.dll
. For example:
regsvr32 /u TMG_install_dir\access\oblix\apps\webgate\bin\webgate.dll
3. Run the following command to unregister
postgate.dll
. For example:
regsvr32 /u TMG_install_dir\access\oblix\apps\webgate\bin\postgate.dll
61.8 Troubleshooting
The error "Failed Connection Attempt" in TMG logs on accessing any Access Manager
protected resource does not affect functionality and can be ignored.
Troubleshooting
61-10 Administrator's Guide for Oracle Access Management
62
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-1
62
Integrating Access Manager with
SAP NetWeaver Enterprise Portal
This chapter describes the integration of Access Manager 11.1.2 with SAP NetWeaver
Enterprise Portal.
This chapter covers the following topics:
■What is Supported in This Release?
■Supported Versions and Platforms
■Integration Architecture
■Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
■Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
■Testing the Integration
■Troubleshooting the Integration
62.1 What is Supported in This Release?
Vers ions 7.0 .x and 7.4.x of SAP NetWeaver Enterprise Portal are supported in this
release.
Access Manager supports SAP NetWeaver Enterprise Portal v7.4.x with the following
caveats:
■Apache 2.2.x and 2.0.x (from Apache.org) are supported Web servers with this
release.
■MySAP is not certified.
Access Manager supports SAP NetWeaver Enterprise Portal v6.0 and v7.0.x with the
following caveats:
■Apache 2.0 (from Apache.org) is supported as a Web server with this release.
■MySAP is not certified.
62.2 Supported Versions and Platforms
Access Manager supports the versions and platforms described on the following site:
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-10
0350.html
Integration Architecture
62-2 Administrator's Guide for Oracle Access Management
62.3 Integration Architecture
The following diagram illustrates the integration between Access Manager and SAP
NetWeaver Enterprise Portal.
62.3.1 Process Overview: Integration with SAP NetWeaver Enterprise Portal
1. A user attempts to access content via the SAP NetWeaver Enterprise Portal.
For example, the user may enter the following URL to access an HR application
through a proxy server:
https://
host:port
/irj
2. The WebGate intercepts the request and queries the Access Server for the security
policy that determines if the resource is protected.
The security policy consists of an authentication scheme, authorization rules, and
allowed operations. Based on the authentication and authorization success or
failure, specified actions are performed.
The Access System security policy for the SAP
/irj
login URL is applicable to all
resources accessed using the
https://
host
:
port
/irj
URL.
Note that the SAP NetWeaver Enterprise Portal has its own authorization system
that can be configured to set user access to iViews.
3. If the resource is protected, the WebGate prompts the user for authentication
credentials.
The credentials that the WebGate requests depend on the authentication scheme
configured in the Access System, for example, Basic over LDAP or Form-based
authentication.
4. If the credentials are validated, the Access System authenticates the user and sets
an encrypted ObSSOCookie in the user's browser.
5. After authenticating, the authorization rules defined in the Access System are
applied based on the security policy.
Specific actions are performed based on the authorization rules. If the user is
authorized, access to the SAP Portal login (the requested content) is allowed. For
SAP Enterprise Portal header variable integration, the Access Server sets the
authenticated user ID in a header variable.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-3
If the user is not authenticated or authorized, he or she is denied access and
redirected to another URL, as determined by the administrator. For example, the
user may be redirected to an "invalid credentials" page.
6. For the integration with SAP NetWeaver Enterprise Portal, the proxy Web server
redirects the request to the SAP NetWeaver Enterprise Portal internal Web server
that contains the header variable details.
7. The SAP NetWeaver Enterprise Portal uses the header variable value to check the
mapping of the user ID against the configured data source in the portal.
Both the Access Manager and SAP NetWeaver Enterprise Portal data source must
contain the same user ID value.
Upon successful mapping, SAP NetWeaver Enterprise Portal allows the user to
access the requested resource.
SAP NetWeaver Enterprise Portal sends a response to the proxy, and the proxy
redirects to the client browser.
8. All interaction with the SAP Enterprise Portal takes place through the proxy
server.
62.4 Configuring Oracle Access Management and NetWeaver Enterprise
Portal 7.0.x
This section describes how to configure Access Manager and SAP NetWeaver
Enterprise Portal 7.0.x to work together.
This section contains the following tasks:
■Before You Begin
■Configuring the Apache HTTP Server as a Proxy
■Configuring SAP NetWeaver Enterprise Portal for External Authentication
■Adjusting the Login Module Stacks for using Header Variables
■Configuring Access Manager for SAP Enterprise Portal
62.4.1 Before You Begin
■Install SAP NetWeaver Enterprise Portal before completing the steps in this
section.
■Install the Apache HTTP Server by following the installation steps provided by
apache.org.
■Install and configure a WebGate on each Apache HTTP Server instance that
supports the proxy connection to the SAP Enterprise Portal instance. See Installing
Webgates for Oracle Access Manager for details.
■Install Access Manager before completing the steps in Section 62.4.5, "Configuring
Access Manager for SAP Enterprise Portal." See the Oracle Fusion Middleware
Installation Guide for Oracle Identity and Access Management for details.
■Synchronize the time on all servers where SAP NetWeaver Enterprise Portal and
Access Manager components are installed.
■Ensure that the users exist in the Access Manager LDAP directory as well as on the
SAP R3 system database.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
62-4 Administrator's Guide for Oracle Access Management
The user ID in Access Manager and the SAP database must be the same or be
mapped to each other. Any attribute in a user's profile can be configured as the
SAP ID and passed directly to SAP. Alternatively, SAP can be configured to map
the SAP ID to any user attribute that it receives from Access Manager.
■Verify that the Web browser is configured to allow cookies.
62.4.2 Configuring the Apache HTTP Server as a Proxy
The following procedure describes how to configure a proxy (Apache HTTP Server
2.0.x) to access SAP NetWeaver Enterprise Portal.
To configure Apache HTTP Server 2.0.x
1. Set up the Apache HTTP Server proxy in non-SSL mode or SSL mode, as described
in the Apache documentation.
If HTTPS communication is used with the SAP NetWeaver Enterprise Portal, use
SSL mode.
2. To enable the proxy to access the SAP NetWeaver Enterprise Portal, enter the
following in the
httpd.conf
configuration file:
For SAP NetWeaver Enterprise Portal 6:
ProxyRequests Off
ProxyPass /irj http://sap_host:port/irj
ProxyPassReverse /irj http://sap_host:port/irj
ProxyPreserveHost On
For SAP NetWeaver Enterprise Portal 7:
ProxyRequests Off
ProxyPass /webdynpro http://sap_host:port/irj
ProxyPassReverse /webdynpro http://sap_host:port/irj
ProxyPreserveHost On
Where sap_host is the name of the machine hosting the SAP NetWeaver Enterprise
Portal instance and port is the listen port for the SAP NetWeaver Enterprise Portal
instance. This set of directives specifies that all of the requests to this Web server of
the form
http://
apache_host:port
/irj
or
https://
apache_host:port
/irj
are
redirected to
http://
sap_host:port/irj or
https://
sap_host:port
/irj
.
3. Restart the proxy Web server.
4. Access the following URL:
Non-SSL—
http://apachehost:port/irj
Note: Oracle suggests reviewing the following topics prior to
integrating Access Manager with SAP NetWeaver Enterprise Portal.
■Chapter 5, "Managing Data Sources" to understand how to add
and configure data sources in Access Manager.
■Chapter 22, "Managing Authentication and Shared Policy
Components" to understand how to configure Form and Basic
mode authentication in Access Manager.
■Section C.4, "Configuring Cert Mode Communication for Access
Manager" to understand how to configure Cert mode for Access
Manager.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-5
SSL—
https://apachehost:port/irj
This request should be redirected to the SAP NetWeaver Enterprise Portal login.
5. Log in using the SAP NetWeaver Enterprise Portal administrator login ID.
The administrator should be able to perform the available administrative
functions.
6. Log in as a non-administrative user.
This user should be able to perform non-administrative functions.
62.4.3 Configuring SAP NetWeaver Enterprise Portal for External Authentication
The following steps describe enabling external authentication in SAP Enterprise Portal
using the
OB_USER
header variable.
For more information about configuring authentication schemes for SAP Enterprise
Portal, see the SAP documentation.
To configure the header variable
1. Stop the SAP J2EE dispatcher and server.
2. Browse to the following directory:
SAP_J2EE_engine_install_dir
\ume
3. Back up the file
authschemes.xml.bak
to another directory.
4. Rename
authschemes.xml.bak
to
authschemes.xml
.
5. Open
authschemes.xml
in an editor and change the reference of the default
authentication scheme to the authentication scheme header as follows:
<authscheme-refs>
<authscheme-ref name="default">
<authscheme>header</authscheme>
<authscheme>uidpwdlogon</authscheme>
</authscheme-ref>
</authscheme-refs>
6. In the authentication scheme header of
authschemes.xml
, specify the name of the
HTTP header variable where the Access System provides the user ID.
As described in "Configuring Access Manager for SAP Enterprise Portal" on
page 62-7, this is the
OB_USER
header variable. You configure this header variable
as follows:
<authscheme name="header">
<loginmodule>
<loginModuleName>
com.sap.security.core.logon.imp.HeaderVariableLoginModule
</loginModuleName>
<controlFlag>REQUISITE</controlFlag>
<options>Header=OB_USER</options>
</loginmodule>
<priority>5</priority>
<frontEndType>2</frontEndType>
<frontEndTarget>com.sap.portal.runtime.logon.header</frontEndTarget>
</authscheme>
The control flag value
REQUISITE
means the login module must succeed. If login
succeeds, authentication continues through the list of login modules. If it fails,
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
62-6 Administrator's Guide for Oracle Access Management
control immediately returns to the application and authentication does not
continue through the list of login modules.
7. Restart the portal server and J2EE engine.
The modified
authschemes.xml
file will be loaded into the Portal Content
Directory (PCD). SAP Enterprise Portal will rename it as
authschemes.xml.bak
.
To Configure Logout
1. To enable logout from a single sign-on session in both SAP Enterprise Portal and
Access Manager, configure a logout URL in SAP Enterprise Portal from the
administration interface.
The URL for the administration interface is as follows:
http://
SAP_host:port
/irj/
Where SAP_host is the name of the machine hosting the SAP Enterprise Portal and
port is the listen port for the portal.
2. From the administration interface, click System Administration, then System
Configuration, then UM Configuration, then Direct Editing.
3. Add the following lines to the end of the configuration file:
ume.logoff.redirect.url=http(s)://proxy_host:port/logout.html
ume.logoff.redirect.silent=false
Where http(s) is either
http
or
https
, proxy_host is the name of the proxy Web
server, and port is the listen port for the proxy.
4. Save the changes and log out.
62.4.4 Adjusting the Login Module Stacks for using Header Variables
Add the
HeaderVariableLoginModule
to the appropriate login module stack or
template and configure the options as described here.
To adjust the Login Module Stacks for using Header Variables
1. Run the Visual Administrator tool, in the following location:
SAPJ2EEEngine_install_dir
\j2ee\admin\go.bat
2. In the Visual Administrator, choose Security Provider.
3. Switch to edit mode by choosing the pencil icon.
4. Choose Policy Configurations, then Authentication.
5. For each template or application that is to support header variable authentication,
add the login module HeaderVariableLoginModule to the login module stack (see
Table 62–1.
Table 62–1 Login Module Stacks for using Header Variables
Login Modules Flag Options
EvaluateTicketLoginModule SUFFICIENT
{ume.configuration.active=true
HeaderVariableLoginModule OPTIONAL
{ume.configuration.active=true, Header=<header_name>}
CreateTicketLoginModule SUFFICIENT
{ume.configuration.active=true}
BasicPasswordLoginModule REQUISITE
{}
CreateTicketLoginModule OPTIONAL
{ume.configuration.active=true}
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-7
62.4.5 Configuring Access Manager for SAP Enterprise Portal
The following procedure describes configuration of the security policy in Access
Manager to protect log-ins to SAP NetWeaver Enterprise Portal.
To configure Access Manager for SAP NetWeaver Enterprise Portal
1. In to the Oracle Access Management Console, click Application Security at the
top of the window.
2. In the Launch Pad tab, select Create Application Domain from the Create (+)
drop-down menu in the Access Manager section.
The Create OAM 11g Webgate page opens.
3. Complete the form to create a WebGate for this integration. For example:
Name—SAP_AG
Vers io n - 11g
Host Identifier—Apache proxy host
Auto Create Policies—Enabled (checked)
Public Resource List—Add any public Resources to this list.
Apply—Click to create the WebGate.
4. Click the Authorization Policies tab, then click the Create Authorization Policy
button to open a fresh page (Chapter 25).
5. Summary Tab: Add your information to the Summary tab.
6. Click the Resources tab, click Add (+), and define the resources for the policies in
this application domain as follows:
Name: SAP EP Security Policy
Type: http
Host identifiers: Enter the proxy host URL prefix: /irj.
Description: SAP EP Login URL
7. Add Resources: The Resource must be defined in the Application Domain before
you can add the resource to a specific policy.
■Click the Resources tab on the Authorization Policy page.
■Click the Add button on the Resources tab.
■Click the Search button.
■Click a URL in the Results table, then click Add Selected.
■Repeat these steps to add more resources.
8. Click Apply to save changes and close the Confirmation window.
9. Responses: Add policy Responses, as described in "Adding and Managing Policy
Responses for SSO" on page 25-75.
10. Conditions: Add authorization conditions, as described in "Defining
Authorization Policy Conditions" on page 25-43.
11. Rules: Add authorization rules, as described in "Defining Authorization Policy
Rules" on page 25-60.
12. Close the page when you finish.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
62-8 Administrator's Guide for Oracle Access Management
62.5 Configuring Oracle Access Management and NetWeaver Enterprise
Portal 7.4.x
This section contains the following tasks.
■Before You Begin
■Configuring Access Manager for SAP NetWeaver Enterprise Portal 7.4.x
■Configuring Apache Web Server 2.0.x or 2.2.x
■Configuring SAP Enterprise Portal 7.4 for External Authentication
■Adjusting the Login Module Stacks for Using Header Variables
62.5.1 Before You Begin
■Install SAP NetWeaver Enterprise Portal version 7.4.x before completing the steps
in this section.
■Install Access Manager as described in the Oracle Fusion Middleware Installation
Guide for Oracle Identity and Access Management.
■Install Apache HTTP Server 2.0.x or 2.2.x by following the installation steps
provided by apache.org.
■Install and configure an 11g WebGate on each Apache HTTP Server instance that
supports the proxy connection to the SAP Enterprise Portal 7.4 instance. See
Installing Webgates for Oracle Access Manager for details.
■Synchronize the time on all servers where SAP NetWeaver Enterprise Portal and
Access Manager components are installed.
■Ensure that the users exist in the Access Manager LDAP directory as well as on the
SAP R3 system database.
The user ID in Access Manager and the SAP database must be the same or be
mapped to each other. Any attribute in a user's profile can be configured as the
SAP ID and passed directly to SAP. Alternatively, SAP can be configured to map
the SAP ID to any user attribute that it receives from Access Manager.
■Verify that your Web browser is configured to allow cookies.
62.5.2 Configuring Access Manager for SAP NetWeaver Enterprise Portal 7.4.x
Complete the following steps to configure the Access Manager security policy that
protects SAP NetWeaver Enterprise Portal log-ins.
Note: Oracle suggests reviewing the following topics prior to
integrating Access Manager with SAP NetWeaver Enterprise Portal.
■Chapter 5, "Managing Data Sources" to understand how to add
and configure data sources in Access Manager.
■Chapter 22, "Managing Authentication and Shared Policy
Components" to understand how to configure Form and Basic
mode authentication in Access Manager.
■Section C.4, "Configuring Cert Mode Communication for Access
Manager" to understand how to configure Cert mode for Access
Manager.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-9
1. In to the Oracle Access Management Console, click Application Security at the
top of the window.
2. In the Launch Pad tab, select Create Application Domain from the Create (+)
drop-down menu in the Access Manager section.
3. Complete the form to create a WebGate for this integration. For example:
Name—Type a meaningful name, for example, SAP_AG. Do not include spaces in
the name.
Vers io n - select 11g from the drop-down menu.
Access Client Password—Enter a password to be used during the installation of
the WebGate.
Security—Choose the type of communication that should occur between the
WebGate and the OAM server.
Click Apply.
A confirmation page opens.
4. At the bottom of the confirmation page, in the Server Lists section, associate the
WebGate with a defined Access Server.
Click Apply.
5. On the Launch Pad page, go to the Access Manager section and click Host
Identifiers.
Click Search, then click the WebGate in the search results.
Configure the host identifiers using the fully qualified proxy machine name and
port for the Apache proxy.
6. Click Application Domains and search for the application domain name that you
used to create the WebGate (for example, SAP_WG).
Click the application domain name in the search results to open it
a. Click the Resources tab and search for the resource that the WebGates should
protect. Select the resource in the search results then click the Create button.
Complete the form and click Apply.
Type - HTTP
Resource URL -
/irj
Protection Level - Protected
Authentication Policy - Protected Resource Policy
Authorization Policy - Protected Resource Policy
b. Click the Authentication Policies tab, then click Protected Resource Policy.
Choose the appropriate authentication scheme from the Authentication
Scheme drop-down that you want to configure for this particular domain. For
example, for a form-based authentication policy (FAAuthScheme), enter the
following:
Name - Protected Resource Policy
Authentication Scheme - FAAuthScheme
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
62-10 Administrator's Guide for Oracle Access Management
Click Apply to save your changes.
c. Click the Authorization Policies tab, then click Protected Resource Policy.
Click the Responses tab and add the following:
Type - Header
Name - OAM_REMOTE_USER
Val u e - Same account name
The other tabs in Authorization Policies include conditions and rules:
Condition - Creates a list of users and puts them in a group.
Rule - Allows or denies access to the group of users created in the conditions
tab.
Click Apply to save your changes.
7. If you configured a form-based authentication scheme, ensure that a
login.html
page is configured in the proxy server document root.
Also, ensure that a
logout.html
page is present on the proxy Web server
document root. You can create a custom logout page using HTML, a JSP file, or a
CGI protocol.
The default logout page (
logout.html
) is located here:
WebGate_install_dir/webgate/apache/oamsso/logout.html
Where:
WebGate_install_dir
is the directory where the WebGate is installed. Ensure that
the name of the logout page contains the string
logout
.
8. Ensure that the user ID that is returned by the
OAM_REMOTE_USER
header variable
exists in the user management data sources for SAP Enterprise 7.4.
9. On the Launch Pad page, go to the Access Manager section and click
Authentication Schemes.
Choose the authentication scheme to use. This is the scheme that you selected
inside the application domain of the WebGate.
62.5.3 Configuring Apache Web Server 2.0.x or 2.2.x
Follow these steps to configure a proxy to access SAP Enterprise Portal 7.4.
1. Set up the Apache proxy in non-SSL mode or in SSL mode. Refer to the Apache
documentation for details.
If HTTPS communication is used with the SAP Enterprise Portal 7.4, use SSL
mode.
2. To enable the proxy to the SAP Enterprise Portal 7.4, add the following to the
httpd.conf
file:
Note: Select either basic-over-LDAP or form-based authentication.
Oracle recommends that you use a form-based authentication scheme.
If you use the basic authentication scheme, also set the Challenge
Redirect field to another WebGate to ensure that the
ObSSOCookie
is
set.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-11
ProxyRequests Off
ProxyPass /http://sap_host:port/
ProxyPassReverse / http://sap_host:port//
ProxyPreserveHost On
Where:
sap_host
- The name of the machine hosting the SAP Enterprise Portal 7.4
instance
port
- The listening port for the SAP Enterprise Portal 7.4 instance.
This set of directives specifies that all requests to the Web server that take the form
http://apache_host:port/irj
or
https://apache_host:port/irj
are redirected
to
http://sap_host:port/irj
or
https://sap_host:port/irj
.
3. Uncomment the following proxy related modules:
■
LoadModule proxy_module modules/mod_proxy.so
■
LoadModule proxy_http_module modules/mod_proxy_http.so
4. Restart the proxy Web server.
5. Open a browser and access the following URL:
■Non-SSL:
http//apachehost
:
port/irj
■SSL:
https://apachehost:port/irj
This request should be redirected to the SAP Enterprise Portal 7.4 login ID.
6. Log in using the SAP Enterprise Portal 7.4 administrator login ID.
Verify that you can perform the provided administrative functions when logged in
as an administrator.
7. Log in as a non-administrative user.
Verify that you can perform the provided non-administrative functions when
logged in.
62.5.4 Configuring SAP Enterprise Portal 7.4 for External Authentication
Complete the following steps to enable external authentication in SAP Enterprise
Portal 7.4 using the OAM_REMOTE_USER header variable.
1. To enable logout from a single sign-on session in both SAP Enterprise Portal 7.4
and Access Manager, use the SAP NetWeaver Administrator interface to configure
a logout URL.
Set the SAP NetWeaver Portal Logoff URL (
ume.logoff.redirect.url
) to the
appropriate logout URL.
2. Open the config tool by running the
configtool.bat
file, which is located here:
SAP_J2EE_engine_install_dir\configtool
Note: See the SAP Enterprise Portal 7.4 Enterprise Postal Security Guide
for more information about configuring authentication schemes for
SAP Enterprise Portal.
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x
62-12 Administrator's Guide for Oracle Access Management
Prepare to edit the configuration by switching to configuration editor mode, and
choosing edit mode.
3. Edit the properties for the following workernode service:
com.sap.security.core.ume.service
Update the
ume.logoff.redirect.url
property and the
ume.logoff.redirect.silent
property with the logoff URL configured in step 1.
ume.logoff.redirect.url=http(s)://proxy_host:port/logout.html
ume.logoff.redirect.silent=false
Save your changes and close the config tool.
4. Stop the SAP J2EE dispatcher and server.
5. Again, open the config tool by running the
configtool.bat
file, which is located
here:
SAP_J2EE_engine_install_dir\configtool
Prepare to edit the configuration by switching to configuration editor mode, and
choosing edit mode.
6. Back up the
authschemes.xml
file (cluster_config > globals > clusternode_config >
workernode > services > com.sap.security.core.service > persistent).
7. Open
authschemes.xml
in an editor and change the reference of the default
authentication scheme to the authentication scheme header as follows:
<authscheme-refs>
<authscheme-ref name="default">
<authscheme>header</authscheme>
</authscheme-ref>
</authscheme-refs>
<authscheme-ref name="default"> ----------------> (for fall back)
<authscheme>uidpwdlogon</authscheme>
</authscheme-ref>
</authscheme-refs>
8. In
authschemes.xml
, go to the authentication scheme header and specify the name
of the HTTP header variable where the access system provides the user ID.
Configure this header variable as follows:
<authscheme name="header">
<loginmodule>
<loginModuleName>
com.sap.security.core.logon.imp.HeaderVariableLoginModule
</loginModuleName>
<controlFlag>REQUISITE</controlFlag>
<options>Header=OAM_REMOTE_USER</options>
</loginmodule>
<priority>5</priority>
<frontEndType>2</frontEndType>
<frontEndTarget>com.sap.portal.runtime.logon.header</frontEndTarget>
</authscheme>
The REQUISITE control flag value specifies that the login module must succeed. If
login succeeds, authentication continues through the list of login modules. If it
fails, control immediately returns to the application and authentication does not
continue through the list of login modules.
Testing the Integration
Integrating Access Manager with SAP NetWeaver Enterprise Portal 62-13
9. Save the XML to the same location.
10. Restart the portal server and J2EE engine.
The modified
authschemes.xml
file is loaded into the Portal Content Directory
(PCD). SAP Enterprise Portal 7.4 renames it as
authschemes.xml.bak
.
62.5.5 Adjusting the Login Module Stacks for Using Header Variables
Use the NetWeaver Admin console to add the
HeaderVariableLoginModule
to the
appropriate login module stack or template and configure the options as described
here. In the console, choose Configuration > Authentication and Single Sign-On.
Click Login Modules under the Authentication tab. Select the
HeaderVariableLoginModule
login module, choose ticket from the Login Module Use
tab, and add the login module
HeaderVariableLoginModule
to the login module stack
for each template or application that is to support header variable authentication.
62.6 Testing the Integration
Use the following procedures to test the integration.
Front-End Integration Test Procedure
Follow these steps to test the integration using a Web browser.
1. Open a protected URL. For example:
https://
host:port
/irj
Access Manager should prompt for authentication (either form based, or basic
authentication over LDAP, or Cert Mode authentication).
2. Enter the correct user credentials.
If the credentials are correct, you will be logged into the SAP NetWeaver
Enterprise Portal system.
Back-End Integration Test Procedure
To use these steps, download and install a plug-in for your Web browser that displays
the HTTP requests and responses that happen when your browser requests a resource.
Live HTTP Headers for Firefox, or ieHTTPHeaders for Internet Explorer are two such
plug-ins.
1. Open the plug-in and type a URL in your browser to request a protected resource,
for example:
https://
host:port
/irj
The plug-in window will be populated with the HTTP requests and responses.
2. Analyze the requests and responses and make sure that each request returns a
response without errors.
Once the user is authenticated you should see some sessions and cookies set in the
HTTP Header logs. The cookies that are set include the following:
Table 62–2 Login Module Stacks for using Header Variables
Login Modules Flag Options
EvaluateTicketLoginModule SUFFICIENT
{ume.configuration.active=true
HeaderVariableLoginModule OPTIONAL
{ume.configuration.active=true, Header=<header_name>}
CreateTicketLoginModule SUFFICIENT
{ume.configuration.active=true}
BasicPasswordLoginModule REQUISITE
{}
CreateTicketLoginModule OPTIONAL
{ume.configuration.active=true}
Troubleshooting the Integration
62-14 Administrator's Guide for Oracle Access Management
■ObSSOCookie
■JSESSIONID
■OAM_ID
■OAM_REQ
When the request reaches the SAP NetWeaver Enterprise Portal, you will receive
responses from the Enterprise Portal system in the header logs.
62.7 Troubleshooting the Integration
The following information is intended to help you troubleshoot issues with this
integration.
Problem: The browser has problems displaying the SAP 7.0.x administration interface
through the proxy server. You may receive an "object not found" error and related
JavaScript errors.
Solution: See the following SAP document for a list of supported browsers, "SAP
NetWeaver 7.0.x Product Availability Matrix."
63
Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal Using OpenSSO Policy Agent 2.2 63-1
63
Integrating Oracle Access Manager with
SAP NetWeaver Enterprise Portal Using
OpenSSO Policy Agent 2.2
This chapter describes how to use Sun Java System Access Manager / OpenSSO Policy
Agent 2.2 to integrate Oracle Access Manager 11.1.2 with SAP NetWeaver Enterprise
Portal 7.01.
This chapter covers the following topics:
■What is Supported in This Release?
■Registering the OpenSSO Agent
■Installing the OpenSSO Policy Agent 2.2 on SAP Enterprise Portal
■Deploying the Agent Software Delivery Archive
■Making a Class Loader Reference to the Login Module
■Modifying the SAP Enterprise Portal 7.0 / Web Application Server 7.0 Class Path
■Deploying and Starting the Agentapp.war File
■Using Telnet to Create a Reference Between agentapp and Library
AmSAPAgent2.2
■Adding the Login Module to the Stack
■Modifying the Login Module Stack
■Updating the ume.logoff.redirect.uri
■Configuring the AMAgent.properties File
■Testing the Integration
63.1 What is Supported in This Release?
Only SAP Netweaver Enterprise Portal 7.01 is supported by the OpenSSO Policy
Agent 2.2 in this release. MySAP is not certified.
Note: The following patch must be applied to the OpenSSO Policy
Agent 2.2:
PSE ID: OpenSSO.J2EE.PSE.2.2.18810674
SAP single sign-on will not work without this patch.
Registering the OpenSSO Agent
63-2 Administrator's Guide for Oracle Access Management
63.2 Registering the OpenSSO Agent
Before you begin, complete the following steps:
■Remotely register the agent so that the Agent Profile is created on the Oracle
Access Management side. Use the remote registration tool on the OAM server
located here:
<Middleware_Home>/Oracle_IDM1/oam/server/rreg
■Ensure that the fully-qualified domain name of the OAM server and the SAP
server are updated in the
hosts
file on both systems.
Always use the SAP and OAM server’s fully-qualified domain name while
installing or registering the agent and doing OAM configuration.
1. Open the appropriate XML request file for editing. The request file will provide
inputs for the registration.
Request files are located inside the input folder.
2. Modify the specific values to match your environment.
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights
reserved.
NAME: OpenSSORequest.xml - Template (with all options) for OpenSSO Agent
Registration Request file
DESCRIPTION: Modify with specific values and pass file as input to the
tool-->
<OpenSSORegRequest>
<serverAddress>http://OAMserver.example.com:7001</serverAddress>
<hostIdentifier>OPENSSO_HOSTID8</hostIdentifier>
<agentName>OPENSSO_SAP8</agentName>
<agentBaseUrl>http://SAPserver.example.com:50000</agentBaseUrl>
<applicationDomain>OPENSSO_APPDOMAIN</applicationDomain> //Modify this.
<autoCreatePolicy>true</autoCreatePolicy>
<agentType>J2EE</agentType>
<agentVersion>2.2</agentVersion> //Important: Make sure the version is 2.2.
<agentDebugDir></agentDebugDir>
<agentAuditDir></agentAuditDir>
<agentAuditFileName></agentAuditFileName>
<protectedAuthnScheme></protectedAuthnScheme>
</OpenSSORegRequest>
3. To register the agent, open a command prompt and run the following command
from the
bin
directory in the rreg tool:
oamreg.sh inband input/OpenSSORequest
The command outputs the
AMAgent.properties
file, which is located in the output
directory.
This registration creates a footprint in the
oam-config.xml
file for the OAM
domain, which is located here:
Note: For OpenSSO agent 2.2, there is only one output file
(
AMAgent.properties
), whereas for OpenSSO agent 3 there are two
output files (
OpenSSOAgentBootstrap.properties
and
OpenSSOAgentConfiguration.properties
).
Installing the OpenSSO Policy Agent 2.2 on SAP Enterprise Portal
Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal Using OpenSSO Policy Agent 2.2 63-3
<Middleware_home>/user_projects/domains/base_
domain1/config/fmwconfig/oam-config.xml
The registered agent is in an entry similar to the following:
<Setting Name="<Agent_Name>" Type="htf:map">
The registration process is now complete.
63.3 Installing the OpenSSO Policy Agent 2.2 on SAP Enterprise Portal
Complete the following steps to install the agent on the SAP container.
1. Extract the OpenSSO Policy agent and navigate to the
bin
folder.
2. Open a command prompt and type the following command to install the agent on
the SAP container.
agentadmin.sh - -install
The command will prompt you for values as needed. The following table
summarizes the requested inputs.
63.3.1 Post-Installation Steps
After installation, an agent instance is created on the SAP container. Inside this
directory is another instance of the
AMAgent.properties
file. (So there are two
Table 63–1
Request prompt Sample Input Description
SAP <SID> Directory <SAP_Server_
Instance>\JC00\j2ee\clu
ster\server0
Path to the SAP directory
Agent installed on
WebAS domain
false
Access Manager Services
host
OAMserver.example.com
OAM server fully-qualified domain name
Access Manager Services
Port
8003 Port where the OAM server is running
Access Manager Services
protocol
http
Access Manager Services
deployment URI
/opensso
OpenSSO proxy URL
Agent host name SAPserver.example.com
SAP server fully-qualified domain name
Application server
instance port number
50000 Port where the SAP EP server is running
Protocol for
Application Server
instance
http
Deployment URI for the
Agent Application
/agentapp
URI of the WAR file that we deploy
Encryption key
gSwxyctnKWkx8fBgbwj8
Mn5ziksjaUqi
Agent profile name
OPENSSO_SAP8 Agent profile name given during registration
Agent profile password
file name
/Policy_Agent/sap_v7_
agent/Info/p.txt
Deploying the Agent Software Delivery Archive
63-4 Administrator's Guide for Oracle Access Management
AMAgent.properties
files: one generated during remote registration, and one
generated just previously during the Agent installation.)
1. Compare the two properties files and consolidate them so that you have one
properties file that contains all of the information.
Be sure that all of the settings in the
AMAgent.properties
file matches the Agent
Profile entry in the
oam-config.xml
file on the OAM server.
2. In
oam-config.xml
, add the following entry under the
<Setting
Name="NamingData" Type="htf:map">
element:
<Setting Name="iplanet-am-platform-server-id"
Type="xsd:string">serverprotocol://serverhost:serverport</Setting>
63.4 Deploying the Agent Software Delivery Archive
1. Go to the
etc
folder in the agent to locate the
AmSAPAgent2.2.sda
archive. The
.sda
file is a library that you will deploy onto the SAP server using the Software
Deployment Manager (SDM).
2. Use the Software Deployment Manager
(
/usr/sap/SID/InstanceName/SDM/program/RemoteGui.sh
) to deploy the
AmSAPAgent2.2.sda
file. Refer to the SAP documentation for details.
Once the deployment is complete, verify that the library is deployed by viewing
the Undeployment tab. The
AmSAPAgent2.2
library should be listed.
You can also use the SAP Visual Administrator tool
(
/usr/sap/SID/InstanceName/j2ee/admin/go.sh
) to verify that the deployed
library, along with the SAP-dependent libraries, are available in the container.
63.5 Making a Class Loader Reference to the Login Module
Use the SAP Visual Administrator tool
(
/usr/sap/SID/InstanceName/j2ee/admin/go.sh
) to make a class loader reference for
the newly deployed library. Add the reference to the
LoginModuleClassLoader
by
adding the following key-value pair on the Properties tab on the Security Provider
configuration page (Server Instance > Services > Security Provider).
Note: Be sure to increment the version integer every time you
update the
oam-config.xml
file:
<Setting Name="Version" Type="xsd:integer">113</Setting>
Table 63–2
Key Value
LoginModuleClassLoader library: AmSAPAgent2.2
Using Telnet to Create a Reference Between agentapp and Library AmSAPAgent2.2
Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal Using OpenSSO Policy Agent 2.2 63-5
63.6 Modifying the SAP Enterprise Portal 7.0 / Web Application Server 7.0
Class Path
Open the SAP Config Tool
(
/usr/sap/SID/InstanceName/j2ee/configtool/configtool.sh
), navigate to
Cluster_data > Instance ID > Server instance, and on the General tab, add the
following paths to the Classpath field:
/Policy_Agent/sap_v7_agent/j2ee_agents/sap_v7_agent/<Agent_
Instance>/config
/Policy_Agent/sap_v7_agent/j2ee_agents/sap_v7_agent/locale
63.7 Deploying and Starting the Agentapp.war File
1. Open the SAP Deployment Manager (
deploy.sh
) and create a new project.
2. Go to an empty directory owned by the SAP instance user (j2eeadm) and type
agentapp for the address field.
Go to the Assembler tab and add the
agentapp.war
archive (right-click the
agentapp node and select Add Archive from the context menu).
Save the project.
Browse to the directory specified previously as owned by the SAP Instance user
(j2eeadm), type agentapp for the address field, and click OK.
Right-click the agentapp root node and select Make Ear from the context menu.
63.8 Using Telnet to Create a Reference Between agentapp and Library
AmSAPAgent2.2
1. Telnet to the SAP host (for example,
saphost.example.com 50008
) and log on as
an administrator.
2. Issue the following commands:
a.
$ jump 0
The system returns a message similar to the following:
You jumped on node 4503950.
b.
$ add deploy
c.
$ CHANGE_REF -m sap.com/agentapp library:AmSAPAgent2.2
The system returns the following message:
The reference between application sap.com/agentapp and
library:AmSAPAgent2.2 was made!
3. Stop and Start the SAP Enterprise Portal instance.
Note: You can also use the SAP Visual Administrator tool
(
/usr/sap/SID/InstanceName/j2ee/admin/go.sh
) to verify that the
references were made properly. Choose Server Instance > Services >
ClassLoader Viewer.
Adding the Login Module to the Stack
63-6 Administrator's Guide for Oracle Access Management
63.9 Adding the Login Module to the Stack
Before You Begin - Start the SAP Enterprise Portal instance if it is not running.
1. Start the SAP Visual Administrator tool and log in.
(
/usr/sap/SID/InstanceName/j2ee/admin/go.sh
).
2. Select the Security Provider service, click the User Management tab, and switch to
edit mode.
3. Click Manage Security Stores > Add Login Module.
Click OK when the dialog box opens.
4. In the Class Name field, type the following:
com.sun.identity.agents.sap.v70.AmSAPEP70LoginModule
5. In the Display Name field, type the following:
AmSAPEP70LoginModule
63.10 Modifying the Login Module Stack
1. Start the SAP Visual Administrator tool and log in.
(
/usr/sap/SID/InstanceName/j2ee/admin/go.sh
).
2. Select the Security Provider service, click the Policy Configurations tab, and
switch to edit mode.
3. In the Components list, select the ticket authentication template.
4. Delete all login modules except for the following:
■
com.sap.security.core.server.jaas.EvaluteTicketLoginModule
■
com.sap.security.core.server.jaas.CreateTicketLoginModule
5. Click Add New and select AmSAPEP70LoginModule from the list of modules.
6. Click Modify and move
AmSAPEP70LoginModule
between the two remaining login
modules.
The new ticket authentication template should match the values in the following
table.
63.11 Updating the ume.logoff.redirect.uri
1. Open the SAP Config Tool
(
/usr/sap/SID/InstanceName/j2ee/configtool/configtool.sh
) and switch to
edit mode.
2. Click the pencil and glasses button and choose cluster_data > server > cfg >
services.
The UME service property sheet opens.
Table 63–3 Ticket Authentication Values
Login Module Flag
EvaluateTicketLoginModule
SUFFICIENT
AmSAPEP70LoginModule
REQUISITE
CreateTicketLoginModule
OPTIONAL
Testing the Integration
Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal Using OpenSSO Policy Agent 2.2 63-7
3. Open the
com.sap.security.core.ume.service
property sheet and add the
following custom value to the
ume.logoff.redirect.uri
property.
http://OAM-Server-Hostname:OAM-Port/oam/server/logout
63.12 Configuring the AMAgent.properties File
Open the
AMAgent.properties
file for the Agent Instance and edit the following
properties:
1. In Debug Service Properties, update the complete path of the log location similar
to the following:
com.iplanet.services.debug.directory = /Policy_Agent/sap_v7_agent/j2ee_
agents/sap_v7_agent/Agent_003/logs/debug
2. In COMMON ATTRIBUTE FETCH PROCESSING PROPERTIES, set cookie
encode to false.
com.sun.identity.agents.config.attribute.cookie.encode = false
3. In COOKIE RESET PROCESSING PROPERTIES, edit the following properties:
com.sun.identity.agents.config.cookie.reset.enable = true
com.sun.identity.agents.config.cookie.reset.name[0] = MYSAPSSO2
com.sun.identity.agents.config.cookie.reset.domain[MYSAPSSO2] =
.corp.example.com
4. In URL DECODE SSO TOKEN FLAG, set decode to false:
com.sun.identity.agents.config.sso.decode = false
5. In FILTER OPERATION MODE, add or update the following property:
com.sun.identity.agents.config.filter.mode = SSO_ONLY
63.13 Testing the Integration
Users in the Oracle Access Management user store should also be in the SAP server. Be
sure to allow user access in OAM.
To verify that the integration is working properly, try the following:
1. Access the protected URL (for example,
/irj
).
You should be redirected to the Oracle Access Manager login form.
2. Enter a valid user name and password.
You should be authenticated and logged into the SAP server (
/irj
).
Note: The following properties in
AMAgent.properties
must match
the properties in
oam-config.xml
. If the properties do not match,
update the properties in
oam-config.xml
.
Be sure to increment the version integer every time you update the
oam-config.xml
file:
<Setting Name="Version" Type="xsd:integer">113</Setting>
Testing the Integration
63-8 Administrator's Guide for Oracle Access Management
Part XVI
Part XVI
Appendixes
Part XII provides information that is outside the scope of day-to-day administration
tasks with Oracle Access Management.
Part XII contains the following appendixes:
■Appendix A, "Integrating Oracle ADF Applications with Access Manager SSO"
■Appendix B, "Internationalization and Multibyte Data Support for 10g WebGates"
■Appendix C, "Securing Communication"
■Appendix D, "Reviewing Bundled, Generated, and Migrated Artifacts"
■Appendix E, "Troubleshooting"
A
Integrating Oracle ADF Applications with Access Manager SSO A-1
A
Integrating Oracle ADF Applications with
Access Manager SSO
The Oracle Application Developer Framework (ADF) and applications that are coded
to Oracle ADF standards interface with the OPSS SSO Framework. The Oracle
Platform Security Services (OPSS) single sign-on framework provides a way to
integrate applications in a domain with a single sign-on (SSO) solution.
You can integrate a Web application that uses Oracle ADF security and the OPSS SSO
Framework with an Access Manager SSO security provider for user authentication.
This chapter provides the following sections:
■Introducing Oracle Platform Security Services and Oracle Application Developer
Framework
■Integrating Access Manager With Web Applications Using Oracle ADF Security
and the OPSS SSO Framework
■Configuring Centralized Logout for Oracle ADF-Coded Applications
■Confirming Application-Driven Authentication During Runtime
A.1 Introducing Oracle Platform Security Services and Oracle Application
Developer Framework
This section provides the following topics:
■Oracle Platform Security Services Single Sign-on Framework
■Oracle Application Developer Framework
A.1.1 Oracle Platform Security Services Single Sign-on Framework
A single sign-on (SSO) solution must provide a standard way for applications to login
and logout users. After successful authentication, the SSO service is responsible to
redirect the user to the appropriate URL.
The Oracle Platform Security Services (OPSS) SSO Framework provides a way to
integrate applications in a domain with an SSO solution. Specifically, it provides
applications with a common set of APIs across SSO products to handle login, auto
login, and logout.
The Oracle Application Developer Framework (ADF) and applications that are coded
to Oracle ADF standards interface with the OPSS SSO Framework. For more
information about Oracle ADF, see "Oracle Application Developer Framework" on
page A-2.
Introducing Oracle Platform Security Services and Oracle Application Developer Framework
A-2 Administrator's Guide for Oracle Access Management
The Access Manager SSO solution is available out-of-the-box and provides the
following to applications that are coded to Oracle ADF standards and the OPSS SSO
Framework:
■Login (application-driven): Upon accessing a part of a secured artifact that
requires authentication, the application triggers authentication and redirects the
user to be authenticated by the appropriate solution.
■Auto login: A user who has initially accessed an application anonymously
registers an account with the application (Oracle Identity Manager, for instance);
upon a successful registration, the user is redirected to the authentication URL; the
user can also be automatically logged in without being prompted.
■Global logout: When a user logs out of one application, the logout propagates
across to any other application that is enabled by the solution.
A.1.2 Oracle Application Developer Framework
The Oracle Application Development Framework is an end-to-end application
framework that builds on Java EE standards and open-source technologies to simplify
and accelerate implementing service-oriented applications.
The development and run-time environment required to deploy and manage ADF
applications is similar in many ways to the environment required for other Java EE
applications.
The difference between a typical Java EE environment and an environment that
supports Oracle ADF applications is the availability of the Oracle ADF run-time
libraries:
■In Oracle Fusion Middleware 11g, an Oracle WebLogic Server domain, by default,
does not contain the Oracle ADF run-time libraries. However, you can optionally
configure or extend your domain to include the Java Run-time Files (JRF). The
Oracle ADF run-time libraries are included as part of the JRF component.
The Oracle WebLogic Server domain can be extended with the Java Run-time Files
(JRF) domain template, which includes the required Oracle ADF libraries, and
other important Oracle-specific technologies.
■In Oracle Application Server 10g, each instance of OC4J automatically provided
the Oracle ADF run-time libraries required to support Oracle ADF applications.
For information about the types of Java EE environments available in 10g and
instructions for upgrading those environments to Oracle Fusion Middleware 11g, refer
to the Oracle Fusion Middleware Upgrade Guide for Java EE.
Note: The OPSS SSO framework does not support multi-level
authentication.
See Also: Oracle Fusion Middleware Application Security Guide part
"Single Sign-On Configuration" for more information about choosing
an SSO solution, and the Access Manager solutions.
Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework
Integrating Oracle ADF Applications with Access Manager SSO A-3
A.2 Integrating Access Manager With Web Applications Using Oracle
ADF Security and the OPSS SSO Framework
This section describes how to integrate a Web application that uses Oracle ADF
security and the OPSS SSO Framework with an Access Manager SSO security provider
for user authentication.
Before the Web application can be run, you must configure the domain-level
jps-config.xml
file on the application's target Oracle WebLogic Server for the Access
Manager security provider.
The domain-level
jps-config.xml
file is in the following path and should not be
confused with the deployed application's jps-config.xml file:
$DOMAIN_HOME/config/fmwconfig/jps-config.xml
You can use an Oracle JRF WLST script to configure the domain-level jps-config.xml
file, either before or after the Web application is deployed. This Oracle JRF WLST
script is named as follows:
Linux: wlst.sh
Windows: wlst.cmd
The Oracle JRF WLST script is available in the following path if you are running
through JDev:
$JDEV_HOME/oracle_common/common/bin/
In a standalone JRF WebLogic installation, the path is:
$MW_HOME/oracle_common/wlst
Command Syntax
addOAMSSOProvider(loginuri, logouturi, autologinuri)
Run the addOAMSSOProvider command as in the following example.
cd $MW_HOME/oracle_common/common/bin
./wlst.sh
.......after running ./wlst.sh............
Welcome to WebLogic Server Administration Scripting Shell
Type help() for help on available commands
addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication",
logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
addOAMSSOProvider(loginuri="/testapp/adfAuthentication",
logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
wls:/offline> addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication",
Note: Do not confuse the domain-level
jps-config.xml
file with the
deployed application's jps-config.xml file.
Note: The Oracle JRF WLST script is required. When running WLST
for Oracle Java Required Files (JRF), do not use the WLST script under
$JDEV_HOME/wlserver_10.3/common/bin.
Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework
A-4 Administrator's Guide for Oracle Access Management
logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
Table A–1 defines the expected value for each argument.
The procedure to configure domain-level jps-config.xml for a Fusion Web application
with Oracle ADF Security enabled is part of a larger task. With the exception of the
command syntax, all tasks are the same for Access Manager 10g and 11g.
For more information, see:
■Sample SSO Configuration for Access Manager
■SSO Provider Configuration Details
A.2.1 Sample SSO Configuration for Access Manager
The SSO service configuration entered with the procedure described in Oracle Fusion
Middleware Application Security Guide for all tasks involving Access Manager SSO
providers and an OAM Configuration Example is written to the file
jps-config.xml
.
The data specified includes:
■A particular SSO service
■The auto-login and auto-logout URIs
■The authentication level
■The query parameters contained in the URLs returned by the selected SSO service
Table A–1 addOAMSSOProvider Command-line Arguments
Argument Definition
loginuri Specifies the URI of the login page
Note: For ADF security enabled applications,
"/<context-root>/adfAuthentication" should be provided for the 'loginuri'
parameter. Here is the flow:
1. User accesses a resource that has been protected by authorization policies
in OPSS, fox example.
2. If the user is not yet authenticated, ADF redirects the user to the URI
configured in 'loginuri'.
3. Access Manager, should have a policy to protect the value in 'loginuri': for
example, "/<context-root>/adfAuthentication.
4. When ADF redirects to this URI, Access Manager displays a Login Page
(depending on the authentication scheme configured in Access Manager
for this URI).
logouturi Specifies the URI of the logout page
Note: For ADF security enabled applications, logouturi should be configured
based on logout guidelines in Chapter 27. For the:
■11g WebGate the value of the logouturi should be sought from the 11g
WebGate Administrator.
■10g WebGate requires a logouturi value of "/oamsso/logout.html
autologinuri Specifies the URI of the autologin page.
See Also:
■Oracle Fusion Middleware Oracle WebLogic Scripting Tool
■Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference "Infrastructure Security Commands" chapter
Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework
Integrating Oracle ADF Applications with Access Manager SSO A-5
■The appropriate settings for token generation
The following fragment of a
jps-config.xml
file illustrates the configuration of an
Access Manager SSO provider. Some values are merely placeholders for actual content.
Your configuration should contain values for your implementation.
Example A–1 Sample SSO Configuration for Access Manager
<propertySets>
<propertySet name = "props.auth.url">
<property name = "login.url.BASIC" value = "http://host:port/oam_
login.cgi?level=BASIC"/>
<property name = "login.url.FORM" value = "http://host:port/oam_
login.cgi?level=FORM"/>
<property name = "login.url.DIGEST" value = "http://host:port/oam_
login.cgi?level= DIGEST"/>
<property name = "autologin.url" value = " http://host:port/obrar.cgi"/>
<property name = "logout.url" value = "http://host:port/logout.cgi"/>
<property name = "param.login.successurl" value = "successurl"/>
<property name = "param.login.cancelurl" value = "cancelurl"/>
<property name = "param.autologin.targeturl" value = "redirectto"/>
<property name = "param.autologin.token" value = "cookie"/>
<property name = "param.logout.targeturl" value = "targeturl"/>
</propertySet>
<propertySet name="props.auth.uri">
<property name="login.url.BASIC"
value="/${app.context}/adfAuthentication?level=BASIC" />
<property name="login.url.FORM"
value="/${app.context}/adfAuthentication?level=FORM" />
<property name="login.url.DIGEST"
value="/${app.context}/adfAuthentication?level=DIGEST" />
<property name="autologin.url" value="/obrar.cgi" />
<property name="logout.url" value="/${oamsso/logout.html" />
</propertySet>
<propertySet name = "props.auth.level">
<property name = "level.anonymous" value = "0"/>
<property name = "level.BASIC" value = "1"/>
<property name = "level.FORM" value = "2"/>
<property name = "level.DIGEST" value = "3"/>
</propertySet>
<propertySets>
<serviceProviders>
<serviceProvider name = "sso.provider"
class = "oracle.security.jps.internal.sso.SsoServiceProvider"
type = "SSO">
<description>SSO service provider</description>
</serviceProvider>
</serviceProviders>
<serviceInstances>
<serviceInstance name = "sso" provider = "sso.provider">
<propertySetRef ref = "props.auth.url"/>
<propertySetRef ref = "props.auth.level"/>
<property name = "default.auth.level" value = "2"/>
<property name = "token.type" value = "OAMSSOToken"/>
<property name = "token.provider.class" value =
See Also: "SSO Provider Configuration Details"
Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework
A-6 Administrator's Guide for Oracle Access Management
"oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl"/>
</serviceInstance>
</serviceInstances>
<jpsContexts default = "default">
<jpsContext name = "default">
<serviceInstanceRef ref = "sso"/>
</jpsContext>
</jpsContexts>
A.2.2 SSO Provider Configuration Details
Note the following important points:
■Any SSO provider must define the URI for at least the FORM login with the
property
login.url.FORM
. The value need not be a URL.
■If the application supports a self-registration page URI or URL, it must be
specified with the property
autologin.url
.
■If the SSO solution supports a global logout URI or URL, it must be specified with
the property
logout.url
. The OAM solution supports global logout.
■The following properties, illustrated in Example A–1, are optional:
–
param.login.successurl
–
param.login.cancelurl
–
param.autologin.targeturl
–
param.login.token
–
param.logout.targeturl
■The use of the variable
app.context
in URI specifications, in values within the
property set
props.auth.uri
for instance, is allowed for only ADF applications
when integrating with the Access Manager solution.
■The property set
props.auth.level
is required.
■The reference to
props.auth.url
is required.
■The property
sso.provider.class
within a service instance of the SSO provider is
the fully qualified name of the class implementing a specific SSO solution.
In the case of the OAM solution, the provided class name is
oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl
.
■The property name
default.auth.level
within a service instance of the SSO
provider must be set to "2", as illustrated in Example A–1.
■The property
token.type
within a service instance of the SSO provider is required.
This token type identifies the token set on the HTTP request by the SSO provider
upon a successful authentication; the SSO provider uses this token, after the first
time, to ensure that the user does not need to be reauthenticated and that his
sign-on is still valid. In the case of the OAM solution, the token type must be
OAMSSOToken
, as illustrated in Example A–1.
■The property
token.provider.class
within a service instance of the SSO provider
is the fully qualified name of the token class, and it is provider-specific.
Configuring Centralized Logout for Oracle ADF-Coded Applications
Integrating Oracle ADF Applications with Access Manager SSO A-7
■An application that implements a self-registration logic and wants to auto login a
user after successful self-registration, it must call the OPSS autoLogin API; in turn,
to allow this call, it must grant that application a code source permission named
CredentialMapping
with class
JpsPermission
.
The following fragment of the file
system-jazn-data.xml
illustrates the
specification of this permission to the application
MyApp
:
<grant>
<grantee>
<codesource>
<url>file:${domain.home}/servers/MyApp/-</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.JpsPermission</class>
<name>CredentialMapping</name>
</permission>
</permissions>
</grant>
A.3 Configuring Centralized Logout for Oracle ADF-Coded Applications
The Access Manager SSO solution is available for applications that are coded to Oracle
ADF standards and the OPSS SSO Framework. ADF-coded applications that are
configured to perform logout with Access Manager, redirect to the
/oamsso/logout.html resource.
IAMSuiteAgent intercepts and processes the request, cleans up the session, redirects to
the central logout page (done by the OAM Server) and redirects back to the end_url.
Task overview: Protecting ADF-coded applications with Access Manager
1. Review "About Centralized Logout Processing for Applications Coded to Oracle
ADF Standards".
2. Protect the ADF-coded application using either an:
■11g Webgate
■10g Webgate
3. Perform the single extra configuration step for ADF-coded applications: configure
the OAMSSOProvider as described in "Configuring Centralized Logout for
ADF-Coded Applications with Access Manager" on page A-8.
4. Perform logout configuration steps for your chosen Webgate version.
A.3.1 About Centralized Logout Processing for Applications Coded to Oracle ADF
Standards
ADF-coded applications refer to either applications that have been fully integrated
with ADF or those that simply use ADF Authentication Servlet to integrate with OPSS.
See Also: Oracle Fusion Middleware Application Security Guide
Note: For ADF applications, only one extra configuration step is
needed (to configure the OAMSSOProvider for OPSS).
Configuring Centralized Logout for Oracle ADF-Coded Applications
A-8 Administrator's Guide for Oracle Access Management
In this case, logout is initiated when an ADF application causes the invocation of the
logout URI. The following process overview outlines the Access Manager centralized
logout process for applications coded to Oracle ADF standards.
Process overview: Centralized logout for ADF applications with 10g Webgate
1. An ADF application causes the invocation of the following URI.
/<application context root>/adfAuthentication?logout=true&end_url=<any uri>
The
end_url
parameter specifies the URI to which the application returns control
following logout.
2. ADF invokes the configured OPSS SSO provider (OAM in this case) and delegates
the logout functionality to the configured logout URI by redirecting the request to
the logout URI. The
end_url
value is passed as a query string to the logout URI.
For example:
/oamsso/logout.html?end_url=<end_uri>
.
3. The logout URI is invoked on the Webgate front-ending the application.
4. 10g Webgate clears the ObSSOCookie for its domain and loads the logout.html
script.
5. If the
end_url
parameter does not include host:port, the logout.html script gets the
host:port of the local server and constructs the
end_url
parameter as a URL. For
example:
http://serverhost:port/oam/server/logout?end_url=http://my.site.com/
welcome.html
6. Logic in logout.html redirect to the OAM Server. For example:
http://myoamserverhost:port/oam/server/logout?end_url=http://my.site.com/
welcome.html
7. The OAM Server executes logout as follows:
a. Cleans up the session information associated with the user at the server side.
b. Validates the
end_url
and sends a page with callback URLs to the user's
browser.
c. From the callback page, a new request is initiated to a specific URI on each
Webgate. When this request reaches the specific Webgate in the specific
domain, the ObSSOCookie for that domain is cleared.
d. The user is redirected to the
end_url
in the logout script. However, if the
end_
url
parameter is not present, an appropriate message is sent by the OAM
Server.
A.3.2 Configuring Centralized Logout for ADF-Coded Applications with Access
Manager
The following procedure is similar to configuring logout for 10g Webgates, with
specific step for ADF-coded applications. The ADF-coded application must send the
end_url
value to identify where to redirect the user after logout processing. However,
Note: The Logout Callback URL is specified in the expanded (not
short) OAM Agent registration, as described in Table 15–3.
Configuring Centralized Logout for Oracle ADF-Coded Applications
Integrating Oracle ADF Applications with Access Manager SSO A-9
with ADF-coded applications, logout occurs when the application causes the following
URI to be invoked:
/<app context root>/adfAuthentication?logout=true&end_url=<any uri>
Some steps in this procedure require the WebLogic Scripting Tool (WLST): wlst.sh
(Linux) or wlst.cmd (Windows), which you must invoke from the WLST_install_dir.
To configure centralized logout for ADF-coded applications
1. Check with the Administrator to confirm the location of the logout.html script
configured with the agent, which you need in following steps.
2. Configure OPSS for OAM as the SSO provider to update jps-config.xml for the
WebLogic administration domain, as follows:
a. On the computer hosting the Oracle WebLogic Server and the Web application
using Oracle ADF security, locate the Oracle JRF WLST script. For example:
cd $ORACLE_HOME/oracle_common/common/bin
b. Connect to the computer hosting the Oracle WebLogic Server, enter the
Administrator ID and password, and the host and port of the WebLogic
AdminServer:
wls:/> /connect('admin_ID', 'admin_pw', 'hostname:port'
For example, the Oracle WebLogic Administration Server host could be
localhost
using port
7001
. However, your environment might be different.
c. Check with the Administrator to confirm the location of the logout.html script
configured with the agent.
In Step d, you must use the value provided by the Administrator. Here,
logouturi
value is the URI of the logout script /logout.html. The value could
either begin with "logout." (exceptions are logout.gif and logout.jpg) or it
could be any other value configured by the Administrator.
d. Enter the loginuri for ADF authentication and the logouturi (location of the
logout.html script configured with the agent); the host and port are not
needed.
wls:/>addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication",
logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
Here, loginuri=/${app.context}/adfAuthentication; logouturival is the URI of
the logout script /logout.html. The logouturl could either begin with "logout"
(exceptions are logout.gif and logout.jpg) or it could be any other value
configured by the Administrator.
3. Required: The ADF application must pass the end_url parameter indicating where
to redirect the user after logout, as follows:
Note: The Applcore f/w could facilitate triggering of the above URL
and the ADF application could leverage that.
See Also:
■"Using Custom WLST Commands" in the Oracle Fusion
Middleware WebLogic Scripting Tool Command Reference
Confirming Application-Driven Authentication During Runtime
A-10 Administrator's Guide for Oracle Access Management
If the
end_url
parameter does not include host:port, the logout.html script gets the
host:port of the local server and constructs the
end_url
parameter as a URL. For
example:
http://serverhost:port/oam/server/logout?end_url=http://serverhost:port/
welcome.html
4. 11g Webgate: Perform steps in "Configuring Centralized Logout for 11g
WebGates" on page 27-4.
5. 10g Webgate: Perform steps in "Configuring Centralized Logout for 10g WebGate
with 11g OAM Servers" on page 30-22.
A.4 Confirming Application-Driven Authentication During Runtime
As mentioned earlier in this chapter, it is the application that triggers authentication
and redirects the user to be authenticated by the appropriate solution. For instance,
when the application determines that a user is accessing a part of a secured artifact
that requires authentication application-driven authentication is triggered, in this case
using Access Manager SSO.
To confirm application-driven authentication during run time
1. Create the application based on the Oracle ADF framework.
2. Configure the Access Manager SSO Security provider, as described in "Integrating
Access Manager With Web Applications Using Oracle ADF Security and the OPSS
SSO Framework" on page A-3.
3. Access the protected field and confirm that the application triggers authentication.
See Also: "Scenario: Identity Propagation with the Access Manager
Token" on page 42-2 for details about setting up providers for Access
Manager Identity Assertion.
B
Internationalization and Multibyte Data Support for 10g WebGates B-1
B
Internationalization and Multibyte Data
Support for 10g WebGates
The information here might be of interest if you are using 10g WebGates:
■Introduction to Internationalization and Multibyte Data Support
B.1 Introduction to Internationalization and Multibyte Data Support
Access Manager provides multi-lingual applications and software products that can be
accessed and run anywhere simultaneously, without modification, while rendering
content in the native user's language and locale preferences.
A locale is the linguistic and cultural environment in which a system or program is
running; data associated with a locale provides support for formatting and parsing of
dates, times, numbers, currencies, and the like based on the linguistic and cultural
requirements that corresponds to a given language and country.
Oracle product globalization is a two part process that includes internationalization
and localization. Internationalization (sometimes shortened to "I18N", meaning "I -
eighteen letters -N") requires that software products and applications must be usable
on a computer running any supported operating system (in any supported language),
with non-US keyboards or other country-specific hardware. Oracle applications do not
have hard-coded dependencies on language strings, and inter-operate with non-US
versions of other products. Oracle applications can handle multibyte characters and
differences in a distributed environment, and also being able to detect the user's
desired locale. Access Manager meets these requirements and conforms to Unicode
Standard 4.0.
Localization includes translation of separated file text. In Oracle products, information
is presented in a manner that is consistent with the user's local cultural conventions,
including data formatting, collation, currency, date, time, and directionality of text
(right-to-left or left-to-right), as discussed next.
For more information, see:
■Languages For Localized Messages
■Bi-directional Language Support
■UTF-8 Encoding
B.1.1 Languages For Localized Messages
Translatable information can be categorized into two types: end-user information
(accessible to all users) and administrative information (for users with Administrator
privileges). When you install Oracle Access Manager 10.1.4 without a Language Pack,
Introduction to Internationalization and Multibyte Data Support
B-2 Administrator's Guide for Oracle Access Management
English is the default language for Administrators and end users. When you install
10.1.4 with Oracle-provided Language Packs, you can choose the language to be used
as the default for Administrative activities. Regardless of the default Administrator
language you choose during installation, English is always installed.
For end-users, the display of static application data is provided in the End Users
languages identified in Table B–1: error messages, and display names for tabs, panels,
and properties. Administrative information can be displayed in only the
Administrators languages listed in Table B–1. If administrative pages are requested in
any other language (by the browser setting), the language that was selected as the
default during product installation is used to display the pages.
Note: Messages added for minor releases (10g (10.1.4.2.0) and 10g
(10.1.4.3) as a result of new functionality might not be translated and
can appear in only English.
Table B–1 Languages for Localized Messages
Language Tag for Installation
Directory End User Information Administrators
en-us English English
ar-ar Arabic
pt-br Brazilian Portuguese Brazilian Portuguese
fr-ca Canadian French
cs-cs Czech
da-dk Danish
nl-nl Dutch
fi-fi Finnish
fr-fr French French
de-de German German
el-gr Greek
he-il Hebrew
hu-hu Hungarian
it-it Italian Italian
ja-jp Japanese Japanese
ko-kr Korean Korean
es-mx Latin American Spanish
no-no Norwegian
pl-pl Polish
pt-pt Portuguese
ro-ro Romanian
ru-ru Russian
zh-cn Simplified Chinese Simplified Chinese
sk-sk Slovak
Introduction to Internationalization and Multibyte Data Support
Internationalization and Multibyte Data Support for 10g WebGates B-3
B.1.2 Bi-directional Language Support
Most Western languages are written left to right (LTR), from the top of the page to the
bottom. East Asian languages are usually written top to bottom, from the right side of
the page to the left (RTL)—although exceptions are frequently made for technical
books translated from Western languages.
Some languages, such as Hebrew and Arabic, are written and read predominantly
from right to left. Numbers reverse direction in Arabic and Hebrew. While the text is
written right to left, numbers within the sentence are written left to right with the most
significant digit on the left, as in European and other LTR languages.
When LTR languages are mixed in with RTL languages, the complete document or
content is considered bi-directional. Access Manager can support bi-directional
languages. If the browser on the host computer is configured to use any bi-directional
language, then Access Manager handles it properly.
To provide support for multiple languages and bi-directional languages, Access
Manager 10.1.4 supports the Unicode standard for encoding.
B.1.3 UTF-8 Encoding
UTF-8 encoding and support is provided automatically, whether you have a new
10.1.4 installation or upgrade an older installation to Access Manager. You do not need
to make any changes to your environment. As with previous releases, data in the
directory server is stored with UTF-8 encoding.
es-es Spanish/Spain Spanish
sv-sv Swedish
th-th Thai
zh-tw Traditional Chinese Traditional Chinese
tr-tr Turkish
Note: No administrative languages require bi-directional support.
Note: Writing direction does not affect the encoding of a character.
Regardless of the writing direction, Oracle stores data in logical
order—the order used by someone typing a language—rather than the
order in which it is presented on the screen.
Note: All of your directory data is UTF-8 format. Access Manager
does not support a mix of data types in the directory.
Table B–1 (Cont.) Languages for Localized Messages
Language Tag for Installation
Directory End User Information Administrators
Introduction to Internationalization and Multibyte Data Support
B-4 Administrator's Guide for Oracle Access Management
C
Securing Communication C-1
C
Securing Communication
This appendix provides the information and steps required to ensure that OAM
Servers and clients (OAM Agents) can communicate securely across the Access
Protocol channel. This chapter provides the following details:
■Prerequisites
■Securing Communication Between OAM Servers and WebGates
■Generating Client Keystores for OAM Tester in Cert Mode
■Configuring Cert Mode Communication for Access Manager
■Configuring Simple Mode Communication with Access Manager
C.1 Prerequisites
If OAM Server mode is Cert mode, agents must use Cert mode. During agent
registration, at least one OAM Server instance must be running in the same mode as
the agent. After agent registration, you can change the mode of the OAM Server.
C.2 Securing Communication Between OAM Servers and WebGates
Securing communication between OAM Servers and clients (WebGates) means
defining the transport security mode for the NAP (also known as the OAP) channel
within the component registration page. The security level for the channel is specified
as either:
■Open: Un-encrypted communication
In Open mode, there is no authentication or encryption between the WebGate and
OAM Server. The WebGate does not ask for proof of the OAM Server's identity
and the OAM Server accepts connections from all WebGates. Use Open mode if
communication security is not an issue in your deployment.
■Simple: Encrypted communication through the Secure Sockets Layer (SSL)
protocol with a public key certificate issued by Oracle.
See Also:
■"About Communication Between OAM Servers and WebGates" on
page 6-4
■Oracle Fusion Middleware Administrator's Guide for details
about the SSL automation tool, managing ports for WebLogic
Server, Oracle HTTP Server, and Oracle Fusion Middleware
Securing Communication Between OAM Servers and WebGates
C-2 Administrator's Guide for Oracle Access Management
Use Simple mode if you have some security concerns, such as not wanting to
transmit passwords as plain text, but you do not manage your own Certificate
Authority (CA). In this case, OAM Servers and WebGates use the same certificates,
issued and signed by Oracle CA. For more information, see "About Simple Mode,
Encryption, and Keys" on page C-14.
■Cert: Encrypted communication through SSL with a public key certificate issued
by a trusted third-party certificate authority (CA).
Use Cert mode if you want different certificates on OAM Servers and WebGates
and you have access to a trusted third-party CA. In this mode, you must encrypt
the private key using the DES algorithm. Access Manager components use X.509
digital certificates in PEM format only. PEM refers to Privacy Enhanced Mail,
which requires a passphrase. The PEM (Privacy Enhanced Mail) format is
preferred for private keys, digital certificates, and trusted certificate authorities
(CAs). The preferred keystore format is the JKS (Java KeyStore) format. For more
information, see "About Cert Mode Encryption and Files" on page C-6.
Figure C–1 illustrates the communication channels used by OAM Servers and
WebGates during user authentication and authorization. Logically the request is to the
Access Manager credential collector. However, when you have a Web server proxy in
front of the WebLogic AdminServer, with a <LocationMatch "/*">, all requests are
routed through the proxy. In this case, there is perimeter defense using the proxy.
Figure C–1 Communication Channels for OAM Servers and WebGates
See Also: "About Certificates, Authorities, and Encryption Keys" on
page C-3
Securing Communication Between OAM Servers and WebGates
Securing Communication C-3
Process overview: Authentication and authorization
1. Request is intercepted by WebGate.
2. Authentication (credential collection) occurs over HTTP(s) channel.
3. Authorization occurs over the NAP channel with OAM Agents only (not mod_
osso).
Using the secure-sockets layer (SSL) protocol helps prevent eavesdropping and
successful man-in-the-middle attacks across the HTTP (HTTPS) channel. The SSL
protocol is included as part of most Web server products and Web browsers. SSL uses
the public-and-private key encryption system, which includes the use of a digital
certificate. For details about enabling SSL communication for a Web server or directory
server, see your vendor's documentation.
The PEM (Privacy Enhanced Mail) format (BASE64-encoded ASCII) is preferred for
private keys, digital certificates, and trusted certificate authorities (CAs). The preferred
keystore format for OAM Servers is JCEKS and for OAM Clients is JKS (Java KeyStore)
format. Access Manager components use X.509 digital certificates in DER (binary form
of a certificate) format only.
For more information, see:
■About Certificates, Authorities, and Encryption Keys
■About Security Modes and X509Scheme Authentication
■About the Importcert Tool
C.2.1 About Certificates, Authorities, and Encryption Keys
Depending on the public key infrastructure, the digital certificate establishes
credentials for Web-based transactions based on:
■Certificate owner's name
■Certificate serial number
■Certificate expiration date
■A copy of the certificate holder's public key, which is used to encrypt messages
and digital signatures
■The digital signature of the certificate-issuing authority is provided so that a
recipient can verify that the certificate is real
Digital certificates can be stored in a registry from which authenticating users can look
up the public keys of other users.
In cryptography, a public key is a value provided by a designated authority to be used
as an encryption key. The system for using public keys is called a public key
infrastructure (PKI). As part of a public key infrastructure, a certificate authority
checks with a registration authority (RA) to verify information provided by the
requestor of a digital certificate. When the RA verifies the requestor's information, the
CA can issue a certificate.
Private keys can be derived from a public key. Combining public and private keys is
known as asymmetric cryptography, which can be used to effectively encrypt
messages and digital signatures.
Securing Communication Between OAM Servers and WebGates
C-4 Administrator's Guide for Oracle Access Management
C.2.2 About Security Modes and X509Scheme Authentication
Administrators must ensure that the OAM Server is reachable only over the transport
specified in the OAM Server configuration. OAM Server configuration defines the end
points for the Server and accounts for the deployment of load balancers or reverse
proxies. When the OAM Server is reachable over both HTTP and HTTPS, all requests
(over either transport) are accepted.
To allow the user to interact with the OAM Server (and logout) over SSL with
non-X509 authentication schemes, the specified Server Port must not be configured to
require CLIENT CERTS.
With the X509 authentication scheme (X509Scheme), the OAM Server SSL Port must
differ from the Server Port, and must be configured to require Client Certificates.
When X509Scheme is used, the X509 module is called after credential collection.
X509Scheme requires the X509 challenge method and the X509 authentication module.
The fully-qualified URL to the credential collector must be specified as the Challenge
URL within X509Scheme. For example:
https://managed_server_host:managed_
server_ssl_port/oam/CredCollectServlet/X509
C.2.3 About the Importcert Tool
Administrators use the Oracle-provided
importcert
tool for several different
procedures related to keystores, keys, and certificates. Table C–1 provides the syntax
for
importcert
commands.
See Also:
■"About Cert Mode Encryption and Files" on page C-6
■"About Simple Mode, Encryption, and Keys" on page C-14
Note: If a relative Challenge URL is specified with X509Scheme, the
OAM Server uses the specified Server Host/Port to construct the
fully-qualified URL of the X509 Credential Collector. However, this
configuration will not work.
See Also: "Managing SSO Tokens and IP Validation" on page 13-5
Table C–1 importcert Command Syntax
Option Description
keystore Follow this command with the path to an existing (or new)
keystore. For example:
/scratch/.oamkeystore
or
/scratch/clientKey.jks
privatekeyfile Follow this option with the path to your private key. For
example:
/scratch/aaa_key.der
signedcertfile Follow this option with the path to your signed certificate. For
example:
/scratch/aaa_cert.der
Generating Client Keystores for OAM Tester in Cert Mode
Securing Communication C-5
C.3 Generating Client Keystores for OAM Tester in Cert Mode
This section is required to generate JKS keystores to be used with OAM Tester in Cert
mode only. Otherwise, you can skip this section.
This section describes how to use importcert commands to generate client keystores
for OAM Tester in Cert mode to contain the imported trusted certificate chain.
To generate client keystores for OAM Tester in Cert mode
1. Use ImportCert tool to create JKS keystores (file name specified by -privatekeyfile
and -signedcertfile). For example:
- java -cp importcert.jar
oracle.security.am.common.tools.importcerts.CertificateImport -keystore
<Keystore path> -privatekeyfile <Private key file> -signedcertfile <Signed
alias Follow this option with your keystore entry alias. Required with
genkeystore.:
alias
storetype Follow this option with your keystore type. By default, the store
type is JCEKS (OAM Server keystore). For example:
Server keystore .oamkeystore, of type:
JCEKS
Client keystore/scratch/clientTrustStore.jks and
/scratch/clientKey.jks can be used. Both are type:
JKS
genkeystore This flag is required for generating OAM client certificates. The
client does not expose the alias and alias password parameters.
However, importcert tool sets the keystore password as the alias
password.
Specify:
Yes or No
Yes imports the certificates in a new keystore.
No imports certificates into an existing keystore.
Sample for OAM Server
- java -cp importcert.jar
oracle.security.am.common.tools.importcerts.Certificate
Import -keystore <path to .oamkeystore> -privatekeyfile
<path to aaa_key.der> -signedcertfile <path to aaa_
cert.der> -alias oam.certmode -aliaspassword <password>
-storetype <JCEKS> genkeystore <yes>
Enter the keystore password and alias password when
prompted.
Sample for OAM Client
See Also "Generating Client
Keystores for OAM Tester in
Cert Mode"
- java -cp importcert.jar
oracle.security.am.common.tools.importcerts.Certificate
Import -keystore <path to clientkey.JKS>
-privatekeyfile <path to aaa_key.der> -signedcertfile
<path to aaa_cert.der> -storetype <JKS> genkeystore
<yes>
Enter the keystore password when prompted.
See Also: "About the Importcert Tool" on page C-4
Table C–1 (Cont.) importcert Command Syntax
Option Description
Configuring Cert Mode Communication for Access Manager
C-6 Administrator's Guide for Oracle Access Management
certificate file> path -storetype <JKS> genkeystore <yes>
Enter the keystore password when prompted.
2. Proceed as needed for your environment:
■Configuring Cert Mode Communication for Access Manager
■Configuring Simple Mode Communication with Access Manager
3. Remove a Keystore: Use the following command to remove the JKS keystore. For
example:
keytool -delete -alias <alias> -keystore <path to clientkey.JKS> -storetype
<JKS>
Enter the keystore password when prompted.
C.4 Configuring Cert Mode Communication for Access Manager
This section describes how to configure Cert mode communication for Access
Manager. The following tasks apply to Cert mode only.
Prerequisites
During agent registration, at least one OAM Server instance must be running in the
same mode as the agent. Otherwise, registration fails. After agent registration,
however, you could change the communication mode of the OAM Server.
Task overview: Adding certificates for the OAM Server includes
1. Reviewing:
■Securing Communication Between OAM Servers and WebGates
■About Cert Mode Encryption and Files
2. Generating a Certificate Request and Private Key for OAM Server
3. Retrieving the OAM Keystore Alias and Password
4. Importing the Trusted, Signed Certificate Chain Into the Keystore
5. Adding Certificate Details to Access Manager Settings
6. Generating a Private Key and Certificate Request for WebGates
7. Updating WebGate to Use Certificates
C.4.1 About Cert Mode Encryption and Files
The certificate request for WebGate generates the request file aaa_req.pem, which you
must send to a root CA that is trusted by the OAM Sever. The root CA returns the
certificates, which can then be installed either during or after 10g WebGate installation
(for 11g WebGate these must be copied to the WebGate instance area manually after
WebGate installation and configuration).
■aaa_key.pem (reserved name for WebGate key file, which cannot be changed)
Note: In Simple mode, the bundled Access Manager-CA-signed
certificates are used and most of the following tasks are not needed.
Configuring Cert Mode Communication for Access Manager
Securing Communication C-7
■aaa_cert.pem (reserved name for WebGate certificate file, which cannot be
changed)
■aaa_chain.pem (reserved name for CA Cert for WebGate side)
During component installation in Cert mode, you are asked to present a certificate
obtained from an external CA. If you do not yet have a certificate you can request one.
Until you receive the certificate, you can configure the WebGate in Simple mode.
However, you cannot complete OAM deployment until the certificates are issued and
installed.
If you choose Cert mode when registering WebGate as an OAM Agent, a field appears
where you can enter the Agent Key Password. When editing an 11g WebGate
registration, password.xml is updated only when the mode is changed from Open to
Cert or Simple to Cert. In cert mode, once generated, password.xml cannot be
updated. Editing the agent Key Password does not result in creation of a new
password.xml.
You must create a Cert request and send that to the CA. When the certificate is
returned you must import it to the OAM Server (or copy it to the WebGate).
C.4.2 Generating a Certificate Request and Private Key for OAM Server
Use the following procedure to retrieve the private key, certificate, and CA certificate
for the OAM Server.
To retrieve the private key and certificates for OAM Server
1. Generate both the certificate request (aaa_req.pem) and Private Key (aaa_key.pem)
as follows:
–OpenSSL req –new –keyout aaa_key.pem –out aaa_req.pem –utf8
-nodes -config openssl_silent_ohs11g.cnf
2. Submit the certificate request (aaa_req.pem) to a trusted CA.
3. Download the CA Certificate in base64 as aaa_chain.pem.
4. Download the Certificate in both base64 and DER format as aaa_cert.pem and
aaa_cert.der.
5. Encrypt the private key (aaa_key.pem) using a password as follows:
openssl rsa -in aaa_key.pem -passin pass: -out aaa_key.pem -passout pass:
******** -des
6. Proceed to "Retrieving the OAM Keystore Alias and Password".
C.4.3 Retrieving the OAM Keystore Alias and Password
Users with valid Administrator credentials can perform the following task to retrieve
the alias of the certificate in the specified keystore to be used for authentication, and
the password that is required to import a certificate.
Note: The certified tool to maintain consistency between 10g and 11g
registration, is openSSL. Oracle recommends that you use openSSL
rather than other tools to generate certificates and keys in PEM
format.
Configuring Cert Mode Communication for Access Manager
C-8 Administrator's Guide for Oracle Access Management
To retrieve the OAM Keystore password
1. Confirm the Oracle Access Management Console is running.
2. On the computer hosting the Oracle Access Management Console, locate the
WebLogic Scripting Tool in the OAM Installation path to use when retrieving the
keystore password. For example:
$ORACLE_IDM_HOME/common/bin/
Here, $ORACLE_IDM_HOME is the base installation directory; /common/bin is
the path in which the scripting tool is located.
3. Start the WebLogic Scripting Tool:
·/ wlst.sh
4. In the WLST shell, enter the command to connect and then enter the requested
information. For example:
wls:/offline> connect()
Please enter your username [weblogic] :
Please enter your password [welcome1] :
Please enter your server URL [t3://localhost:7001] :
wls:/base_domain/serverConfig>
5. Enter the following command to change the location to the read-only
domainRuntime tree (For help, use help(domainRuntime)). For example:
wls:/OAM_AC> domainRuntime()
6. Use the Oracle Enterprise Manager Console to retrieve the credentials for the
OAM keystore.
1. Login to the Oracle Enterprise Manager Console.
2. Navigate to Farm_base_domain -> WebLogic Domain ->
<domain name>
3. Right click and select ’System mbean browser’.
4. Search for JpsCredentialStore.
Alternatively, navigate to application defined mbeans ->com.oracle.jps ->
Domain: <domain name> -> JpsCredentialStore ->JpsCredentialStore
5. Click the 'operations' tab in the right hand window.
6. Click getPortableCredential.
7. Enter OAM_STORE for or Parameter 1 and jks for or Parameter 2.
8. Click Invoke.
The returned value is the keystore password.
7. Pay close attention to the password of the OAM Keystore that is displayed because
this is required to import the certificates.
8. Proceed to "Importing the Trusted, Signed Certificate Chain Into the Keystore".
C.4.4 Importing the Trusted, Signed Certificate Chain Into the Keystore
The Oracle-provided importcert tool is used to import existing private key, signed
certificate (public key) files into the specified keystore format: JKS (client keystore
format) or JCEKS (OAM Server keystore format; .oamkeystore for instance.).
Configuring Cert Mode Communication for Access Manager
Securing Communication C-9
The keystores associated with Access Manager accepts only PKCS8 DER format
certificates:
■If you have PEM format certificates signed by your certificate authority (CA), the
following procedure describes how to convert and then import these using the
importcert
shipped with Access Manager.
■If PEM format certificates are not available, create a certificate request and have it
signed by your CA before beginning the following procedure.
Following are the steps for using the JDK version 6 keytool. If you have a different
version of keytool, refer the documentation for your JDK version.
Prerequisites
Retrieving the OAM Keystore Alias and Password
To import the trusted certificate chain into the keystore
1. Locate the keytool in the following path:
$MW_HOME/jdk160_18/bin/keytool
2. Unzip importcert.zip and locate the Readme file in the following location:
$ORACLE_IDM_HOME/oam/server/tools/importcert/README
3. aaa_chain.pem: Using a text editor, modify the aaa_chain.pem file to remove all
data except that which is contained within the CERTIFICATE blocks, then save the
file.
----BEGIN CERTIFICATE-----
...
CERTIFICATE
...
-----END CERTIFICATE-----
4. Import the trusted certificate chain using the following command with details for
your environment. For example:
keytool -importcert -file aaa_chain.pem -trustcacerts -storepass <password>
-keystore $ORACLE_HOME\user_projects\domains\$DOMAIN\config\fmwconfig\
.oamkeystore -storetype JCEKS
5. When prompted to trust this certificate, type
yes
.
6. aaa_cert.pem:
a. Edit aaa_certn.pem using TextPad to remove all data except that which is
contained within the CERTIFICATE blocks, and save the file in a new location
to retain the original. For example:
----BEGIN CERTIFICATE-----
...
CERTIFICATE
...
Note: When you use the keytool utility, the default key pair
generation algorithm is Digital Signature Algorithm (DSA). However,
Oracle Access Management and WebLogic Server do not support DSA
and you must specify another key pair generation and signature
algorithm.
Configuring Cert Mode Communication for Access Manager
C-10 Administrator's Guide for Oracle Access Management
-----END CERTIFICATE-----
b. Enter the following command to convert the signed certificate (aaa_cert.pem)
to DER format using openSSL or any other tool. For example:
openssl x509 -in aaa_cert.pem -inform PEM -out aaa_cert.der -outform DER
7. aaa_key.pem:
a. Edit aaa_key.pem to remove all data except that which is contained within the
CERTIFICATE blocks, and save the file in a new location to retain the original.
For example:
----BEGIN CERTIFICATE-----
...
CERTIFICATE
...
-----END CERTIFICATE-----
b. Enter the following command to convert the private key (aaa_key.pem) to
DER format using openSSL or any other tool. For example:
openssl pkcs8 -topk8 -nocrypt -in aaa_key.pem -inform PEM -out aaa_key.der
-outform DER
8. Import signed DER format certificates into the keystore. For example:
a. Import aaa_key.der using the following command line arguments and details
for your environment. For example:
c:\Middleware\idm_home\oam\server\tools\importcert
- java -cp importcert.jar
oracle.security.am.common.tools.importcerts.CertificateImport
-keystore <> -privatekeyfile <path> -signedcertfile <path>
-alias [ -storetype <> genkeystore <> -help]
9. Proceed to "Adding Certificate Details to Access Manager Settings".
C.4.5 Adding Certificate Details to Access Manager Settings
After importing the certificates into the keystore, you must add the alias and password
that you specified earlier into Access Manager settings configuration in Oracle Access
Management Console, as described here.
Prerequisites
Importing the Trusted, Signed Certificate Chain Into the Keystore
Note: Enter the key store password and alias password when
prompted. On a Windows system, use a semicolon (;) instead of a
colon (:) in the command line.
Note: No explicit configuration is needed for Simple mode, which is
provided out of the box.
Configuring Cert Mode Communication for Access Manager
Securing Communication C-11
To add certificate details to Access Manager Settings
1. In the Oracle Access Management Console, click Configuration at the top of the
window.
2. In the Launch Pad tab, select Access Manager from the View drop-down menu in
the Settings section.
3. In the Access Protocol section, fill in the alias and alias password details acquired
in the previous procedure. For example:
Cert Mode Configuration
PEM keystore Alias:
my_keystore_alias
PEM keystore Alias Password:
my_keystore_alias_pw
4. Click Apply to save the configuration.
5. Close the page.
6. Open the OAM Server registration page, click the Proxy tab, change the Proxy
mode to Cert, and click Apply.
7. Restart the OAM Server.
8. Proceed to "Generating a Private Key and Certificate Request for WebGates".
C.4.6 Generating a Private Key and Certificate Request for WebGates
Use the following procedure to retrieve the private key, certificate, and CA certificate
for the WebGate.
To retrieve the private key and certificates for WebGates
1. Generate both the certificate request (aaa_req.pem) and Private Key (aaa_key.pem)
as follows:
openssl req -new -keyout aaa_key.pem -out aaa_req.pem -utf8 -nodes
2. Submit the certificate request (aaa_req.pem) to a trusted CA.
3. Download the CA Certificate in base64 as aaa_chain.pem.
4. Download the Certificate in base64 format as aaa_cert.pem.
5. Encrypt the private key (aaa_key.pem) using a password as follows:
openssl rsa -in aaa_key.pem -passin pass: -out aaa_key.pem -passout pass:
******** -des
6. Proceed to "Updating WebGate to Use Certificates".
See Also:
■"Managing the Access Protocol for OAM Proxy Simple and Cert
Mode Security" on page 13-6
Note: The certified tool to maintain consistency between 10g and 11g
registration, is openSSL. Oracle recommends that you use openSSL
rather than other tools to generate certificates and keys in PEM
format.
Configuring Cert Mode Communication for Access Manager
C-12 Administrator's Guide for Oracle Access Management
C.4.7 Updating WebGate to Use Certificates
For all communication modes (Open, Simple, or Cert), the Agent registration should
be updated from the Oracle Access Management Console:
■Registering an Agent: If you choose Cert mode when registering an OAM Agent, a
field appears where you can enter the Agent Key Password.
■Editing/Updating an Agent: When editing an 11g WebGate registration,
password.xml is updated only when the mode is changed from Open to Cert or
Simple to Cert.
Editing the agent Key Password does not result in creation of a new
password.xml. In Cert mode, once generated, password.xml cannot be updated.
Prerequisites
Adding Certificate Details to Access Manager Settings
To update the communication mode in the WebGate Agent registration
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, click Agents.
3. On the Search page, define your criteria and open the desired agent registration, as
described in "Searching for an OAM Agent Registration" on page 15-20.
4. On the agent's registration page, locate the Security options and click Cert (or
Simple).
5. Cert Mode: Enter the Agent key Password as specified in Step 5 of "Generating a
Private Key and Certificate Request for WebGates".
6. Click Apply to submit the changes.
7. Copy your updated WebGate files as follows:
11g WebGate:
ObAccessClient.xml
cwallet.sso
(11g WebGate only)
password.xml
■From: $IDM_DOMAIN_HOME/output/AGENT_NAME
■To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g WebGate: ObAccessClient.xml
■From: $WLS_DOMAIN_HOME/output/AGENT_NAME
■To: $WebGate_install_dir/oblix/lib
10g WebGate: password.xml
■From: $WLS_DOMAIN_HOME/output/AGENT_NAME
■To: $WebGate_install_dir/oblix/config
8. Copy the following files that were created when "Generating a Certificate Request
and Private Key for OAM Server":
11g WebGate:
■From:
Configuring Simple Mode Communication with Access Manager
Securing Communication C-13
aaa_key.pem: WebGate11g_home/webgate/ohs/tools/openssl
aaa_cert.pem: The location where this was saved after receiving from CA
aaa_chain.pem: The location where this was saved after receiving from CA
■To: OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g WebGate:
■From:
aaa_key.pem: The location where the private key file was generated
aaa_cert.pem: The location where this was saved after receiving from CA
aaa_chain.pem: The location where this was saved after receiving from CA
■To: $WebGate_install_dir/oblix/config
9. Restart the OAM Server and the Oracle HTTP Server instance.
C.5 Configuring Simple Mode Communication with Access Manager
The transport security communication mode is chosen during OAM installation. In
Simple mode, the installer generates a random global passphrase initially, which can
be edited as required later.
When you register an OAM Agent or a new OAM Server, you can specify the Security
mode. However, changing the global passphrase requires that you reconfigure all
agents to use the mode and the new global passphrase.
The agent mode can be higher but not lower. The highest level of security is Cert
mode, the lowest is Open mode:
Cert mode Simple mode Open mode
This section provides the information you need to configure Simple mode
communication.
Task overview: Configuring Simple mode communication includes
1. Reviewing:
■"About Simple Mode, Encryption, and Keys"
■"About the Importcert Tool"
2. Retrieving the Global Passphrase for Simple Mode
3. Updating WebGate Registration for Simple Mode
4. Verifying Simple Mode Configuration
Note: Communication between the agent and server works when the
WebGate mode matches (or is higher) than the OAM Server mode.
Note: During agent registration, at least one OAM Server instance
must be running in the same mode as the agent. Otherwise,
registration fails. After agent registration, however, you could change
the communication mode of the OAM Server.
Configuring Simple Mode Communication with Access Manager
C-14 Administrator's Guide for Oracle Access Management
C.5.1 About Simple Mode, Encryption, and Keys
For Simple mode encryption, Access Manager includes a certificate authority with its
own private key, which is installed across all WebGates and OAM Servers. During
installation, the OAM Server generates and saves the private-public keypair for the
server. Similarly, for the OAM agent, an Oracle certificate authority is installed with
the agent installation.
The installer generates a random global passphrase initially, which can be edited or
viewed as needed. When an agent is registered in SIMPLE mode, the following client
certificates are generated to be consumed by clients:
■aaa_key.pem: Contains private key
■aaa_cert.pem: Signed certificate
■password.xml: Contains the random global passphrase in obfuscated format
C.5.2 Retrieving the Global Passphrase for Simple Mode
Access Manager generates a random global passphrase for Simple mode
communication during installation. The following procedure describes how to retrieve
this password.
To retrieve the random global passphrase for Simple mode communication
1. Ensure that the Oracle Access Management Console is running.
2. On the computer hosting the Oracle Access Management Console, locate the
WebLogic Scripting Tool in the following path. For example:
$ORACLE_IDM_HOME/common/bin
Where $ORACLE_IDM_HOME represents the base installation directory path;
/common/bin is the path wherein the scripting tool is located.
3. Start the WebLogic scripting tool. For example, on a Unix system:
./ wlst.sh
4. In the WLST shell, enter the command to connect and then enter the requested
information. For example:
wls:/offline> connect()
Please enter your username [weblogic] :
Please enter your password [weblogic] :
Please enter your server URL [t3://localhost:7001] :
wls:/base_domain/serverConfig>
5. Enter the following command to change the location to the read-only
domainRuntime tree (for help, use help(domainRuntime)). For example:
wls:/OAM_AC>domainRuntime()
6. View the global passphrase by entering the following command. For example:
wls:/OAM_AC> displaySimpleModeGlobalPassphrase()
7. Proceed to "Updating WebGate Registration for Simple Mode".
Note: Changing the global passphrase requires reconfiguring all
agents that are already configured in Simple mode.
Configuring Simple Mode Communication with Access Manager
Securing Communication C-15
C.5.3 Updating WebGate Registration for Simple Mode
Artifacts generated for Simple Security mode use the Global Pass phrase and any
change must be propagated to WebGates.
To update an existing WebGate registration for Simple mode, you can delete the
WebGate registration using the Oracle Access Management Console, then re-register it
(specifying Simple mode and disabling the automatic generation of policies).
Alternatively, you can edit the WebGate registration and then copy the artifacts as
described here.
To update the WebGate registration for Simple mode
1. In the Oracle Access Management Console, click Application Security at the top
of the window.
2. In the Launch Pad tab, click Agents.
3. On the Search page, define your criteria and open the desired agent registration, as
described in "Searching for an OAM Agent Registration" on page 15-20.
4. In the registration page, locate the Security options and click Simple.
5. Click Apply to submit the changes.
6. Copy the updated WebGate files as follows:
11g WebGate:
ObAccessClient.xml
cwallet.sso (11g WebGate only)
password.xml
■From: $WLS_DOMAIN_HOME/output/AGENT_NAME (the WebLogic
domain home where the OAM AdminServer is installed)
■To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g WebGate: ObAccessClient.xml
■From: $WLS_DOMAIN_HOME/output/AGENT_NAME
■To: $WebGate_install_dir/oblix/lib
10g WebGate: password.xml
■From: $WLS_DOMAIN_HOME/output/AGENT_NAME
■To: $WebGate_install_dir/oblix/config
7. Copy the following files, as directed for your WebGate release:
aaa_key.pem
aaa_cert.pem
11g WebGate:
■From: $IDM_DOMAIN_HOME/output/AGENT_NAME
■To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config/simple
10g WebGate:
See Also:
■"Viewing or Editing an OAM Agent Registration Page in the
Console" on page 15-22
Configuring Simple Mode Communication with Access Manager
C-16 Administrator's Guide for Oracle Access Management
■From: $IDM_DOMAIN_HOME/output/AGENT_NAME
■To: $WebGate_install_dir/oblix/config/simple
8. Restart the OAM Server and the Oracle HTTP Server instance.
C.5.4 Verifying Simple Mode Configuration
You must restart the Web server to instantiate the change to Simple mode. Then you
can validate the results
To validate Simple mode changes
1. From a command-line window, restart the Web server. For example:
d:\middleware\ohs_home\instances\ohs_webgate11g\bin
opmnctl stopall
opmnctl startall
2. In a browser window, enter the URL to a resource protected by the WebGate using
Simple mode.
3. Enter your login credentials, when asked.
4. Confirm that the resource is served.
D
Reviewing Bundled, Generated, and Migrated Artifacts D-1
D
Reviewing Bundled, Generated, and Migrated
Artifacts
[39]
This appendix provides a look at sample artifacts that are either bundled with Access
Manager, or generated during agent registration. This appendix includes the following
sections:
■Bundled 10g IAMSuiteAgent Artifacts
■Generated Artifacts: OpenSSO
■Migrated Artifacts: OpenSSO
D.1 Bundled 10g IAMSuiteAgent Artifacts
This section provides the following topics:
■Pre-Registered 10g IAMSuiteAgent
■IAMSuiteAgent Security Provider Settings, WebLogic Administration Console
■IAMSuiteAgent Registration
■Resources Protected by IAMSuiteAgent
■Pre-seeded IAM Suite Application Domain and Policies
D.1.1 Pre-Registered 10g IAMSuiteAgent
This 10g OAM Agent, and the companion Application Domain, described in
Chapter 25, are available with 11.1.1.5. Oracle strongly recommends that you do not
alter these definitions.
The IAMSuiteAgent provides single sign-on functionality for the IDM Administration
Console. The IAMSuiteAgent is installed and pre-configured as part of the OAM
Server installation and configuration.
The IAMSuiteAgent is a domain-wide agent:
■Once deployed, the IAMSuiteAgent is installed on every server in the domain
■Unless disabled, every request coming into the WebLogic Application Server is
evaluated and processed by the IAMSuiteAgent
Note: The original IDMDomainAgent is not available with this patch
set. It remains as an artifact after you apply the patch set. However, all
content is removed.
Bundled 10g IAMSuiteAgent Artifacts
D-2 Administrator's Guide for Oracle Access Management
■Configuration details are located under the 10g Webgates node (Policy
Configuration tab) in the Oracle Access Management Console
Certain IAMSuiteAgent configuration elements are available in the WebLogic
Administration Console (in the Security Provider section) and others in the Oracle
Access Management Console.
D.1.2 IAMSuiteAgent Security Provider Settings, WebLogic Administration Console
In the Security Provider section of the WebLogic Administration Console are five
bootstrap configuration parameters.
While Oracle recommends that you retain these without making changes, there are
circumstances where you might need to change one of the following parameters:
■Primary Access Server: You can replace this value with information for your actual
OAM Server. The default value (localhost:5575) can be replaced with information
for your actual OAM Server if more than one host is part of the IDM Domain. The
IAM Suite Agent and companion Application Domain (IAMSuite) replaces the
11.1.1.3.0 IDM Domain Agent and its companion Application Domain.
■Agent Password: By default there is no password. However, you can add one here
if you want to establish a password for the IAMSuiteAgent connection to the
OAM Server through the NetPoint (now Oracle) Access Protocol (NAP or OAP).
Figure D–1 illustrates the default Security Provider settings for the IAMSuiteAgent.
Figure D–1 IAMSuiteAgent Settings in the WebLogic Administration Console
D.1.3 IAMSuiteAgent Registration
The IAMSuiteAgent registration page provides details about the agent, like all other
OAM agent registration pages.
Bundled 10g IAMSuiteAgent Artifacts
Reviewing Bundled, Generated, and Migrated Artifacts D-3
■Security Mode: Open is the only security mode available for the IAMSuiteAgent.
This cannot be changed.
■Preferred Host: IAMSuiteAgent is the pre-configured host required by this agent
Figure D–2 shows the IAMSuiteAgent page. Notice the User Defined Parameter, which
informs behavior to fall back to the container policy in the WebLogic Server and
provides a redirect URL for logout.
Figure D–2 IAMSuiteAgent Registration
You can replace this agent with a 10g Webgate, as described in Chapter 30,
"Registering and Managing 10g WebGates with Access Manager 11g".
Table D–1 outlines the differences between IAMSuiteAgent and 11g and 10g
WebGates.
Note: The Access Client Password here must match the Agent
Password in the WebLogic Administration Console. If you changed
the Agent Password, you must also change the Access Client
Password.
Bundled 10g IAMSuiteAgent Artifacts
D-4 Administrator's Guide for Oracle Access Management
D.1.4 Resources Protected by IAMSuiteAgent
Figure D–3 illustrates the resources protected by the IAMSuiteAgent, including the
exact Authentication and Authorization policies. Oracle recommends that you do not
make any additions or changes. The WebLogic Administration Console (/console) is
protected.
Table D–1 Comparing IAMSuiteAgent with 11g and 10g Webgates
Element 11g Webgate 10g Webgate IAMSuiteAgent
Primary Cookie Domain N/A x x
Token Validity Period x N/A N/A
Preferred Host x x x
Logout URL x x x
Logout Callback URL x N/A N/A
Logout Redirect URL x N/A N/A
Logout Target URL x N/A N/A
Cache Pragma Header
Cache Control Header
x
x
x
x
x
x
User Defined Parameters
proxySSLHeaderVar=IS_SSL
URLInUTF8Format=true
client_request_retry_
attempts=1
inactiveReconfigPeriod=10
proxySSLHeaderVar=IS_SSL
URLInUTF8Format=true
client_request_retry_
attempts=1
inactiveReconfigPeriod=10
fallbackToContainerPolicy
=true
logoutRedirectUrl=http://
hostname.domain.com:14100
/oam/server/logout
protectWebXmlSecuredPages
Only=true
Deny on Not Protected x x x
Bundled 10g IAMSuiteAgent Artifacts
Reviewing Bundled, Generated, and Migrated Artifacts D-5
Figure D–3 Resources Protected by the IAMSuiteAgent
D.1.5 Pre-seeded IAM Suite Application Domain and Policies
The following figures present Authentication Policies in the IAM Suite Application
Domain:
■Figure D–4, "IAMSuite Authentication Policy: OAM Admin Console Policy"
■Figure D–5, "Protected HigherLevel Policy: Authentication, LDAP Scheme"
■Figure D–6, "Protected LowerLevel Policy: Authentication, OIMScheme"
■Figure D–7, "Public Policy: Authentication, AnonymousSheme"
Bundled 10g IAMSuiteAgent Artifacts
D-6 Administrator's Guide for Oracle Access Management
Figure D–4 IAMSuite Authentication Policy: OAM Admin Console Policy
Bundled 10g IAMSuiteAgent Artifacts
Reviewing Bundled, Generated, and Migrated Artifacts D-7
Figure D–5 Protected HigherLevel Policy: Authentication, LDAP Scheme
Bundled 10g IAMSuiteAgent Artifacts
D-8 Administrator's Guide for Oracle Access Management
Figure D–6 Protected LowerLevel Policy: Authentication, OIMScheme
Figure D–7 Public Policy: Authentication, AnonymousSheme
IAM Suite Authorization Policy
Figure D–8 presents Authorization Policy in the IAM Suite Application Domain. By
default, no explicit conditions or responses are defined. However, you can add any
that are appropriate for your environment.
Bundled 10g IAMSuiteAgent Artifacts
Reviewing Bundled, Generated, and Migrated Artifacts D-9
Figure D–8 IAM Suite Authorization Policy
IAM Suite Token Issuance Policy
Figure D–9 presents IAM Suite Token Issuance Policy in the IAM Suite Application
Domain. By default, there are no explicit conditions defined. However, you can define
any that are needed in your environment.
Figure D–9 IAM Suite Token Issuance Policy and Resource URLs
Generated Artifacts: OpenSSO
D-10 Administrator's Guide for Oracle Access Management
D.2 Generated Artifacts: OpenSSO
This section shows the custom authentication module, host identifier, Application
Domain, and policies generated during OpenSSO Agent provisioning.
■Generated OpenSSOAgentAuthPlugin
■Generated Host Identifier: OpenSSOAgent1
■Generated Application Domain: OpenSSOAgent1
■Generated Resources: OpenSSOAgent1
■Generated Authentication Policy: OpenSSOAgent Application Domain
■Generated Authorization Policy: OpenSSOAgent Application Domain
D.2.1 Generated OpenSSOAgentAuthPlugin
Figure D–10 shows the OpenSSOAgent Custom Authentication Module:
OpenSSOAgentAuthPlugin.
Figure D–10 Generated Authentication Module: OpenSSOAgentAuthPlugin
Generated Artifacts: OpenSSO
Reviewing Bundled, Generated, and Migrated Artifacts D-11
D.2.2 Generated Host Identifier: OpenSSOAgent1
Figure D–11 Generated Host Identifier: OpenSSOAgent1
D.2.3 Generated Application Domain: OpenSSOAgent1
Figure D–12 Generated Application Domain: OpenSSOAgent1
Generated Artifacts: OpenSSO
D-12 Administrator's Guide for Oracle Access Management
D.2.4 Generated Resources: OpenSSOAgent1
Figure D–13 Application Domain Resources: OpenSSOAgent1
D.2.5 Generated Authentication Policy: OpenSSOAgent Application Domain
Figure D–14 Generated Authentication Policy: OpenSSOAgent Application Domain
Migrated Artifacts: OpenSSO
Reviewing Bundled, Generated, and Migrated Artifacts D-13
D.2.6 Generated Authorization Policy: OpenSSOAgent Application Domain
Figure D–15 Generated Authorization Policy: OpenSSOAgent Application Domain
D.3 Migrated Artifacts: OpenSSO
This section shows the artifacts that are migrated when you use Oracle-provided tools
to analyze and migrate an OpenSSO environment to Oracle Access Management
Console.
■Migrated User Identity Store: OpenSSOAgent1
■Migrated Agents: OpenSSOAgent1
■Migrated Authentication Module: OpenSSOAgent1
■Migrated Host Identifier: OpenSSOAgent1
■Migrated Application Domain: OpenSSOAgent1
■Migrated Resources: OpenSSOAgent1
■Migrated Authentication Policy: OpenSSOAgent1
■Migrated Authorization Policy: OpenSSOAgent1
Migrated Artifacts: OpenSSO
D-14 Administrator's Guide for Oracle Access Management
D.3.1 Migrated User Identity Store: OpenSSOAgent1
Figure D–16 Migrated User Identity Store
Migrated Artifacts: OpenSSO
Reviewing Bundled, Generated, and Migrated Artifacts D-15
D.3.2 Migrated Agents: OpenSSOAgent1
Figure D–17 Migrated Agent: OpenSSOAgent1
Migrated Artifacts: OpenSSO
D-16 Administrator's Guide for Oracle Access Management
D.3.3 Migrated Authentication Module: OpenSSOAgent1
Figure D–18 Migrated Authentication Module: OpenSSOAgent1
D.3.4 Migrated Host Identifier: OpenSSOAgent1
Figure D–19 Migrated Host Identifier: OpenSSOAgent1
D.3.5 Migrated Application Domain: OpenSSOAgent1
Figure D–20 Migrated Application Domain: OpenSSOAgent1
Migrated Artifacts: OpenSSO
Reviewing Bundled, Generated, and Migrated Artifacts D-17
D.3.6 Migrated Resources: OpenSSOAgent1
Figure D–21 Migrated Resources: OpenSSOAgent1
D.3.7 Migrated Authentication Policy: OpenSSOAgent1
Figure D–22 Migrated Authentication Policy: OpenSSOAgent1
Migrated Artifacts: OpenSSO
D-18 Administrator's Guide for Oracle Access Management
D.3.8 Migrated Authorization Policy: OpenSSOAgent1
Figure D–23 Migrated Authorization Policy2 Condition: OpenSSOAgent1
Figure D–24 Migrated Authorization Policy2: IP Condition Details
E
Troubleshooting E-1
E
Troubleshooting
This chapter provides troubleshooting tips.
■Introduction to Oracle Access Management Troubleshooting
■Using My Oracle Support for Additional Troubleshooting Information
■Oracle Access Management Console Inconsistent State
■AdminServer Won't Start if the Wrong Java Path Given with WebLogic Server
Installation
■Agent Naming Not Unique
■Application URL Requirements
■Authentication Issues
■Authorization Issues
■Cannot Access Authentication LDAP or Database
■Cannot Find Configuration
■Co-existence Between OSSO and Access Manager
■Could Not Find Partial Trigger
■Denial of Service Attacks
■Deployments with Freshly Installed 10g Webgates
■Disabling Windows Challenge/Response Authentication on IIS Web Servers
■Changing UserIdentityStore1 Type Can Lock Out Administrators
■IIS Web Server Issues
■jps Logger Class Instantiation Warning is Logged on Authentication
■Internationalization, Languages, and Translation
■Login Failure for a Protected Page
■OAM Metric Persistence Timer IllegalStateException: SafeCluster
■Partial Cluster Failure and Intermittent Login and Logout Failures
■RSA SecurID Issues and Logs
■Registration Issues
■Rowkey does not have any primary key attributes Error
■SELinux Issues
Introduction to Oracle Access Management Troubleshooting
E-2 Administrator's Guide for Oracle Access Management
■Session Issues
■SSL versus Open Communication
■Start Up Issues
■Synchronizing OAM Server Clocks
■Using Coherence
■Validation Errors
■Web Server Issues
■Windows Native Authentication
E.1 Introduction to Oracle Access Management Troubleshooting
Oracle Access Management is a business critical system; downtime comes with a
potentially high cost to your business. The goal of system analysis is to quickly isolate
and correct the cause of any problem. This requires a big picture view of your system
and the tools to observe the live system and correlate components to the bigger
picture.
To assist Administrators in performing a quick diagnosis, this section provides the
following topics:
■About System Analysis and Problem Scenarios
■About LDAP Server or Identity Store Issues
■About OAM Server or Host Issues
■About Agent-Side Configuration and Load Issues
■About Runtime Database (Audit or Session Data) Issues
■About Change Propagation or Activation Issues
■About Policy Store Database Issues
E.1.1 About System Analysis and Problem Scenarios
System analysis includes understanding how the product works, what can go wrong,
how likely the scenarios are, and the consequences or observable issues.
System problems can be divided into two basic categories:
■Cascading catastrophic failure
■Gradual breakdown in performance
Cascading catastrophic failure might be caused by:
■LDAP server is loaded and unresponsive
■Morning peak load starts
■Webgates send requests to the primary OAM Server
■Webgate requests time-out and Webgates retry to secondary OAM Server
Gradual breakdown in performance might occur over time when, for example:
■OAM is sized and rolled out for 10,000 users and 500 groups
■Over the course of a year, the number of users and groups increases significantly
(to 50,000 users and 250 groups for example)
Introduction to Oracle Access Management Troubleshooting
Troubleshooting E-3
For information on the most commonly encountered issues, see the following topics:
■About System Analysis and Problem Scenarios
■About LDAP Server or Identity Store Issues
■About OAM Server or Host Issues
■About Agent-Side Configuration and Load Issues
■About Runtime Database (Audit or Session Data) Issues
■About Change Propagation or Activation Issues
■About Policy Store Database Issues
E.1.2 About LDAP Server or Identity Store Issues
This topic provides symptoms, probable cause, and steps to diagnose the following
issues:
■Symptoms: Operational Slowness
■Symptoms: Total loss of service
Symptoms: Operational Slowness
■Poor user experience
■Agent time outs lead to retries
Cause
■Non-OAM load might be impacting OAM operations
■Capacity problems due to gradual increase in peak load
Symptoms: Total loss of service
Cause
■Outage of all LDAP servers
■The load balancer is timing out old connections
Diagnosis
1. Shut down the LDAP server.
2. Restart your browser.
3. Try to access a protected site.
4. Review errors in the OAM Server log file, as described in Chapter 7 (alternatively,
in Chapter 12).
5. Try to access Oracle Access Management Console.
6. Observe errors in WebLogic AdminServer log file.
7. Bring up the LDAP server again.
8. Retry access to a protected application.
9. Retry access to the Oracle Access Management Console.
10. Correct the issue based on the requirements in your environment.
Introduction to Oracle Access Management Troubleshooting
E-4 Administrator's Guide for Oracle Access Management
E.1.3 About OAM Server or Host Issues
This topic provides symptoms, probable cause, and steps to diagnose the following
issues:
■Symptoms: Capacity Problems
■Symptoms: Interference with Other Services on the Host
Symptoms: Capacity Problems
■Poor user experience due to slow operations
■Agent time outs and retry can result in extra load
Cause
■CPU cycles
■Memory issues
Symptoms: Interference with Other Services on the Host
■Poor user experience due to slow operations
■Agent time outs and retry may result in extra load
Cause
■CPU cycle contention
■Memory contention
■File system full
Diagnosis: OAM Server
1. Shut down the OAM Server
2. Try to access a Webgate or mod_osso protected resource
3. Bring up the OAM Server
4. Use the Access Tester to test authentication and authorization as described in
Chapter 26.
5. Use 'top' to figure out the CPU and Memory consumption of the OAM Server as
you use the access tester
6. Get a thread dump of the OAM Server.
Diagnosis: AdminServer
1. Shut down the AdminServer.
2. Restart your browser and access a protected resource, which should work.
3. Use remote registration to register a new partner, as described in Chapter 15 (this
should fail).
4. Startup OAM AdminServer.
E.1.4 About Agent-Side Configuration and Load Issues
This topic provides symptoms, probable cause, and steps to diagnose time issues
between agents and servers.
Introduction to Oracle Access Management Troubleshooting
Troubleshooting E-5
Symptoms: Difference in Clock time Between Agent and Server
■High CPU usage at both agent and server
■User experiences a system hang
Cause
■Agent thinks the token issued by the server is invalid
■Agent keeps going back to the server to re-issue the token
Diagnosis
1. Access protected resource.
2. Confirm: Client access hangs.
3. Confirm: High CPU usage on agent and server.
E.1.5 About Runtime Database (Audit or Session Data) Issues
The audit and session functions are both write intensive operations. The policy
database can be tuned for read intensive service.
Symptoms
■Audit and session operations are slow
■File system on the OAM Server is full with audit data that is not yet written to the
database
■Loss of in-memory session data when one of the servers in the cluster fails
Cause
■Database is not tuned for write intensive operations
■Database is unavailable due to maintenance
■Space issues in the database
Diagnosis
1. Shut down the database used to store Audit and Session data.
2. Try to access a protected resource.
3. Review error and warning messages in the OAM Server log files, as described in
Chapter 7 (alternatively, in Chapter 12).
E.1.6 About Change Propagation or Activation Issues
This topic provides symptoms, probable cause, and steps to diagnose the following
issues:
Symptoms
■Changes to policy do not take immediate effect
■Changes to system configuration do not take immediate effect
Cause
■Servers being too busy handling runtime requests (CPU contention)
■Coherence network slowness
Using My Oracle Support for Additional Troubleshooting Information
E-6 Administrator's Guide for Oracle Access Management
Diagnosis: See "About Policy Store Database Issues"
E.1.7 About Policy Store Database Issues
This topic provides symptoms, probable cause, and steps to diagnose policy database
issues.
Symptoms: No policy changes are allowed; no impact on runtime
Cause
■Database is unavailable (down for maintenance)
■Space issues in the database
Diagnosis
1. Shut down the database containing OAM policies.
2. Try to access a protected resource and observe the runtime access is not impacted.
3. Try to access the Oracle Access Management Console to edit policies, and then
observe errors in the AdminServer log file.
E.2 Using My Oracle Support for Additional Troubleshooting Information
You can use My Oracle Support (formerly MetaLink) to help resolve Oracle Fusion
Middleware problems. My Oracle Support contains several useful troubleshooting
resources, such as:
■Knowledge base articles
■Community forums and discussions
■Patches and upgrades
■Certification information
You can access My Oracle Support at
https://support.oracle.com
.
E.3 Administrator Lockout
Problem
Administrator cannot successfully log in to the Oracle Access Management Console.
The following message appears:
Manually Change Identity Store Settings at OPSS Level and configure the
IDMDOmainAgent.
Cause
Access Manager secures the Oracle Access Management Console based on
authentication information in the IAM Suite Application Domain: OAM Admin
Console Policy. This policy relies on a single Authentication Scheme
(OAMAdminConsoleScheme), which uses a Form challenge method and LDAP
Note: You can also use My Oracle Support to log a service request.
Oracle Access Management Console Inconsistent State
Troubleshooting E-7
Authentication Module. The LDAP Authentication Module must be pointing to the
User Identity Store designated as the System Store.
If, for example, your deployment is configured to use Oracle Internet Directory (with
all Administrators, users, and groups defined therein) ensure that the LDAP
Authentication Module points to this user identity store and that this is designated as
the System Store.
Solution
1. Insert a user identity into both your designated system store and the Embedded
LDAP store.
2. Log in to Oracle Access Management Console.
3. Configure the
LDAP
Authentication Module used by the designated System Store to
point to the appropriate User Identity Store, as described in "Managing Native
Authentication Modules" on page 22-23.
E.4 Error During Federation Configuration After Upgrade from PS1 to
PS2
IAM Suite is the OOTB Application Domain created when OAM 11.1.2 is installed.
This Application Domain can be renamed after installation but when upgrading OAM
to 11.1.2.2.0, it must be renamed back to IAM Suite. If it has been renamed, the
upgrade operation will fail with this error seen in the WLS admin logs.
java.lang.NullPointerException
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.FedR2PS2Bootstr
apHandler.createFedAuthnResource(FedR2PS2BootstrapHandler.java:505)
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.FedR2PS2Bootstr
apHandler.doBootstrap(FedR2PS2BootstrapHandler.java:151)
at
oracle.security.am.common.policy.tools.upgrade.r2ps2.bootstrap.R2PS2BootstrapH
elper.doBootstrap(R2PS2BootstrapHelper.java:70)
at
oracle.security.am.common.policy.tools.PolicyComponentLifecycle.initialize(Pol
.
icyComponentLifecycle.java:99)
If the IAM Suite Application Domain has been renamed, it is required to rename it
back to its original IAM Suite name prior to beginning the upgrade process. After the
upgrade, the name can be changed back to a custom name.
E.5 Oracle Access Management Console Inconsistent State
Problem
Administrators performing updates concurrently will result in an inconsistent state
within the system configuration of the Oracle Access Management Console.
Cause
Concurrent configuration updates are not supported.
AdminServer Won't Start if the Wrong Java Path Given with WebLogic Server Installation
E-8 Administrator's Guide for Oracle Access Management
Solution
Only one Administrator should be allowed to modify the system configuration at any
given time.
E.6 AdminServer Won't Start if the Wrong Java Path Given with WebLogic
Server Installation
WebLogic Server (wls1035_generic) installation is successful on Windows 64-bit with
32-bit Java (jdk1.6.0_24). When setup.exe is executed you must provide the path of the
64-bit java (jdk1.6.0_23) to successfully launch the install shield.
If you provide the 32-bit Java (jdk1.6.0_24) path, the install shield is not launched.
However, if you execute config.cmd from \Middleware\Oracle_IDM1\common\bin,
by default 32-bit Java (jdk1.6.0_24) path is used, but after successful installation Access
Manager installation, you cannot start AdminServer.
On Windows host, the path to 32-bit JAVA_HOME (c:\Program files
(x86)\java\jdkxxx) is not correctly handled by the startWeblogic.cmd. Replacing
SUN_JAVA_HOME to use the path with the shorter name (c:\progra~2\java\jdkxxxx)
works fine.
On Windows, the shorter names can be seen by executing "dir /X".
Alternatively, you can set windows cmd shell variable JAVA_HOME to path with
shorter name and execute startWeblogic.cmd within that. For example:
>set JAVA_HOME=c:\progra~2\java\jdkXXX
>startweblogic.cmd
E.7 Agent Naming Not Unique
A unique identifying name for each Agent registration is preferred. However:
■If the Agent Name exists, no error occurs and the registration does not fail.
Instead, Access Manager creates the policies if they are not already in place.
■ If the host identifier exists, the unique Agent Base URL is added to the existing
host identifier and registration proceeds.
E.8 Application URL Requirements
The number of characters allowed in a URL are based on browser version.
The main attribute that affects the size of a cookie is the length of the requested URL.
Some of the system generated URLs for ADF applications are quite long and can cause
the cookie to exceed the maximum size.
Another case is when using custom plug-ins. The data that a plug-in adds to the
authentication context is persisted in the cookie and can cause the cookie size to grow.
Multiple wrong password attempts can also add more context data to the cookie.
Combined with one of the above cases, the cookie size can rapidly grow.
Solutions
Ensure that your applications do not use URLs that exceed the length that Access
Manager and the browser can handle.
Authentication Issues
Troubleshooting E-9
The cookie cache mode can be changed to
FORM
mode from default
COOKIE
mode.
FORM
mode works with long URLs. The only difference in behavior is for programmatic
authentication, which requires a proper form Submit to pass the
OAM_REQ
parameter set
to the form. Custom credential collection pages need to handle the
OAM_REQ
parameter
that is submitted with the form.
Also, to support long URLs, set the
serverRequestCacheType
parameter to
FORM
in
oam-config.xml under $
DOMAIN_HOME/config/fmwconfig/oam-config.xml
:
<Setting Name="serverRequestCacheType"
Type="xsd:string">FORM</Setting>
E.9 Authentication Issues
This section provides the following information:
■Anonymous Authentication Issues
■X.509Scheme and SSL Handshake Issues
■X.509 Protected Resource and Single Sign Off
■X509CredentialExtractor Certificate Validation Error
E.9.1 Anonymous Authentication Issues
Problem
Challenge Redirect URL can be NULL; however, Challenge Method cannot be NULL.
If you open the Anonymous authentication scheme to edit, and click Apply without
adding a value for Challenge method, the following errors might appear:
Messages for this page are listed below.
* Challenge Method You must make at least one selection.
* Challenge Redirect You must enter a value.
Solution
You must include both a challenge method and a challenge redirect whenever you edit
an anonymous authentication scheme.
E.9.2 X.509Scheme and SSL Handshake Issues
The Access Manager X.509 Authentication Scheme relies on SSL to deliver the user's
X.509 certificate to the OAM Server. The X.509 Authentication Scheme requires the
X.509Plugin as the value of the Challenge Method (not the Authentication Module).
Problem
User has selected his certificate in the Browser but the Certificate is not available to the
OAM Server.
Solution
The specific solution will depend on the reason for the SSL Handshake failure. For
instance:
Authentication Issues
E-10 Administrator's Guide for Oracle Access Management
■For debugging SSL connections terminating on the Weblogic Server, please refer to
http://docs.oracle.com/cd/E12840_01/wls/docs103/secmanage/ssl.html
■For debugging SSL connections terminating on the OHS server, see
http://docs.oracle.com/cd/E12839_01/web.1111/e10144/under_
mods.htm#i1007687
.
Determine the reason for the SSL Handshake failure and the peer that is terminating
the SSL Handshake. The solution will fall into the following categories:
■Configuration Issues
■Trust Issues
■Certificate Validation Issues
E.9.2.1 Configuration Issues
If you are encountering problems establishing a SSL connection with the default
WebLogic server SSL implementation, switch to using the JSSE SSL implementation
which is supported with WLS 10.3.3+.
The following list identifies other possible configuration issues.
■OHS plugin is incorrectly configured and not sending the user certificate to the
WebLogic server.
■Cipher suites: As configured, are not compatible with the user certificate.
■Smart cards: The browser is not communicating with the smart card reader.
■PKCS#11 (or hardware cryptography): Ensure that the devices are in working
order.
E.9.2.2 Trust Issues
The server name within the certificate does not match the host name. This check can be
disabled through configuration.
The server does not contain a CA certificate on the user certificate path in its trust
store.
E.9.2.3 Certificate Validation Issues
The following list identifies possible configuration issues.
■Certificate has expired.
■Certificate has been revoked.
■Certificate validation is not working because this is incorrectly configured or there
are connectivity issues.
E.9.3 X.509 Protected Resource and Single Sign Off
Problem
Single Sign Off might not work after accessing the resource with X.509 authentication.
When the user is logged out with the logout URL and tries to access the resource in the
same browser, authentication might not occur. Instead, the user should be asked for
authentication using the certificate pop up.
This can occur with any Agent type.
Authorization Issues
Troubleshooting E-11
Solution
After executing the logout URL, click on Clear SSL State from the browser as follows,
and the access the X.509-protected resource:
From the browser window, open the Tools menu, click Internet Options, choose
Content, and then Clear SSL state.
E.9.4 X509CredentialExtractor Certificate Validation Error
Problem
Client certificate authentication works fine using the standard X509 Authentication
Module after importing the root and sub CA certificates into the WebLogic Server and
.oamkeystore keystores.
However, a certificate validation error can occur when using a Custom X509Plugin
Authentication Module and root and sub CA certificates into the WebLogic Server and
.oamkeystore keystores.
Solution
With the Custom X509Plugin Authentication Module the root and sub CA certificates
must be added to the DOMAIN_HOME/config/fmwconfig/amtruststore because the
X509CredentialExtractor plug-in loads certificates from this location.
E.10 Authorization Issues
This section provides the following topics:
■Authorization Condition Error
■LDAP Search Filter Test Results
■Authorization Header Response Names
E.10.1 Authorization Condition Error
An error is logged in the oam-server diagnostic log file whenever you create or edit an
IPv4 range or temporal condition:
.... refreshPolicy specified but no response collector supplied
Cause
This is a message that is erroneously being logged at the ERROR level.
Solution
The correct level of the message is INFO.
E.10.2 LDAP Search Filter Test Results
If too many results are returned, you are informed as follows:
Cannot Access Authentication LDAP or Database
E-12 Administrator's Guide for Oracle Access Management
Solution
1. Click OK.
2. Click Test Fil ter to initiate a new test.
3. In the Edit Search Filter dialog, make your changes.
4. Check the Test Results.
E.10.3 Authorization Header Response Names
Some characters might not be usable within header response names or values,
depending on whether the client receiving these responses is a Webgate, and if so
which Web server is protected. Certain characters might be subject to automatic
conversion to other characters in a server-specific way.
Oracle recommends that you refer to your Web server documentation for more details.
E.11 Cannot Access Authentication LDAP or Database
If the LDAP directory that is used for authentication is down or inaccessible (or the
database that is configured as the policy store), it might be due to a heavy load or a
timeout. You see a message when attempting to a protected resource that uses this
LDAP or policy store.
Solution
1. Manually shut down the registered LDAP or database.
2. Restart the registered LDAP or database.
E.12 Cannot Find Configuration
E.12.1 Configuration Does Not Exist ...
If you attempt to create and apply configuration details for an OAM Server before
configuring the OAM Server in the WebLogic Server domain, a message informs you
of the following:
Configuration does not exist for path
/DeployedComponent/Server/oamServer/Instance/test
For more information, please see the server's error log for
an entry beginning with: Server Exception during PPR, #6.
Denial of Service Attacks
Troubleshooting E-13
To resolve this issue, you must configure the OAM Server in the WebLogic Server
domain before you register the configuration with Access Manager.
E.13 Co-existence Between OSSO and Access Manager
Problem
In the OSSO 10g coexistence with Access Manager 11g, if a user tries to access a
protected resource when the OAM server is down, the request is redirected to the
OSSO 10g login page through the load balancer. If the user enters valid credentials, the
resource is provided.
However, if the user deletes the Oracle HTTP Server cookie and brings the OSSO 10g
server down (and brings the OAM Server up), upon accessing the protected resource
the user is asked for Access Manager login (authentication). Instead, the application
should be accessible without authentication.
Solution
Confirm that the migrated User Identity Store is set as the Access Manager Default
Store and System Store.
E.14 Could Not Find Partial Trigger
In the Administration Server output, you might see a "Could Not Find Partial Trigger"
error (multiple times for each clicked policy configuration node or host identifier
node) and also when you click any of other nodes in the navigation tree. This does not
block functionality.
E.15 Denial of Service Attacks
A denial-of-service attack (DoS attack) or distributed denial-of-service attack (DDoS
attack) is an attempt to make a computer resource unavailable to its intended users.
One common method of attack involves saturating the target (victim) machine with
external communication requests, such that it cannot respond to legitimate traffic, or
responds so slowly as to be rendered effectively unavailable.
Denial of service attacks are classified into Authenticated and Unauthenticated
Requests, and further classified as:
■NAP Requests
■HTTP Requests
Authenticated NAP Requests
For Authenticated NAP Requests, the OAM Server maintains a counter in the session
and limits the number of retries. Despite this, after redirecting the user to an error page
the user can repeat the cycle. This needlessly consumes server resources and can lead
to OAM Server overloading.
See Also:
■
enableCoexistMode
and
disableCoexistMode
in the Oracle Fusion
Middleware WebLogic Scripting Tool Command Reference
■Oracle Fusion Middleware Upgrade Guide for Oracle Identity and
Access Management
Denial of Service Attacks
E-14 Administrator's Guide for Oracle Access Management
Authenticated HTTP Requests
You can handle a flood of HTTP Authenticated requests with a combination of
WebLogic overload configuration and mod_security module settings.
Unauthenticated NAP Requests
Unauthenticated NAP Requests are handled by the WebLogic MDB pool throttling.
This limits the number of NAP Requests that are forwarded to the OAM Server.
Again, this does not differentiate legitimate users from malicious ones.
Unauthenticated HTTP Requests
Configuring the mod_security module for the OHS server that front-ends the OAM
Server enables rejection of malicious requests (unauthenticated HTTP Requests).
For more information, see:
■Protecting the OAM Server from Crashing Under Load
■Compensating for Network Latency
■Protecting OAM Servers from a Flood of HTTP Requests
E.15.1 Protecting the OAM Server from Crashing Under Load
If the number of requests to the OAM Server unexpectedly increases beyond what the
server can handle, it could crash.
To limit the number of requests to the OAM Server:
1. In the WebLogic Console, use the Message Driven Bean pool to restrict the number
of NAP requests to the OAM Server.
MDBeans pull NAP requests from the Server queue and deliver NAP requests to
the Server for processing. Limiting the number of MDBean instances helps control
the number of requests that are processed at a given time.
2. In the WebLogic Console, configure the number of WebLogic worker threads that
can be used (to restrict the number of requests to the OAM Server).
MDBeans pull NAP requests from the server queue and deliver NAP requests to
the Server for processing. Limiting the number of MDBean instances helps control
the number of requests that are processed at a given time.
3. In the WebLogic Console, configure the number of WebLogic worker threads that
can be used (to restrict the number of requests to the OAM Server).
See the topic on Thread Management in the guide to Oracle Fusion Middleware
Performance and Tuning for Oracle WebLogic Server.
4. In the WebLogic Console, specify a maximum incoming request size, complete
message timeout, and set the number of file descriptors, to optimize performance
as described in following topics in the Oracle Fusion Middleware Performance
and Tuning for Oracle WebLogic Server:
■Tuning Message Size
Note: To avoid OAM Server overloading with Authenticated NAP
Requests, use relevant WebLogic overload configuration settings.
These ensure that the server does not crash under load. However, this
does not differentiate legitimate users from malicious users.
Deployments with Freshly Installed 10g Webgates
Troubleshooting E-15
■Tuning Complete Message Timeout
■Tuning Number of File Descriptors
E.15.2 Compensating for Network Latency
Consider the scenario where Webgate sends an authentication request to the OAM
Server. After successful credential collection and validation, the OAM Server creates
the session and the relevant cookies (OAM_ID, ObSSOCookie). However, due to
network latency, the response times out by the time the OAM Server sends it to the
Webgate which triggers Webgate to re-send the authentication request to the Server.
The OAM Server recognizes the session, then recreates the ObSSOCookie, and sends
the response to the agent.
If the network latency persists, the cycle continues in an infinite loop between the
Server and the Webgate. The user is neither asked to login again nor presented with an
error message.
E.15.3 Protecting OAM Servers from a Flood of HTTP Requests
ModSecurity is a Web application firewall (WAF) that can be deployed as part of the
existing Apache-based Web server infrastructure. This module can be plugged into the
OHS Server that front-ends the OAM Server. In this way, Mod_security module
protects the OAM Server from denial of service attacks.
A flexible rule engine is at the heart of ModSecurity. It implements the ModSecurity
Rule Language, a specialized programming language designed to work with HTTP
transaction data. A new configuration directive uses the httpd-guardian script to
monitor for Denial of Service (DoS) attacks. By default httpd-guardian defends against
clients that send more than 120 requests in a minute, or more than 360 requests in five
minutes.
To protect from a flood of HTTP Requests
1. Add the mod_security module to the OHS Server that front-ends the OAM Server.
2. In the OHS Server configuration, set the configuration directive to use the
httpd-guardian script to monitor for Denial of Service (DoS) attacks.
Syntax:
SecGuardianLog |/path/to/httpd-guardian
Example:
SecGuardianLog |/usr/local/apache/bin/httpd-guardian
E.16 Deployments with Freshly Installed 10g Webgates
Use the OAM Server's diagnostic features to debug on the OAM Server side. This
section includes the following topics:
■Authentication Issues with 10g Webgates
■Logout Issues with 10g Webgates
See Also:
http://www.modsecurity.org/documentation/modsecurity-apache/2
.5.12/html-multipage/configuration-directives.html#N10689
Diagnosing Initialization and Performance Issues
E-16 Administrator's Guide for Oracle Access Management
E.16.1 Authentication Issues with 10g Webgates
Use the following methods to troubleshoot authentication issues when you have
freshly installed 10g Webgates in your Access Manager deployment.
■Confirm that your request was protected using an http header trace like Internet
Explorer HTTP Headers or Firefox Live HTTP Headers
■Confirm that the request is sent to the OAM Server for authentication
–GET /oam/server/obrareq.cgi?....
–Host: oam-server:port
E.16.2 Logout Issues with 10g Webgates
Use the following methods to troubleshoot logout issues when you have freshly
installed 10g Webgates in your Access Manager deployment.
■Make liberal use of HTTP Header Trace
■Confirm that the specific logout.html was copied to /access/oamsso folder in the
10g Webgate installation directory. If not present, you must create the logout.html
as described in "Configuring Centralized Logout for 10g WebGate with 11g OAM
Servers" on page 30-22.
■Change the 10g Webgate's httpd.conf to remove the following lines:
<LocationMatch "/oamsso/*">
Satisfy any
</LocationMatch>
■From the Oracle Access Management Console, confirm that the LogoutUrls
parameter (/oamsso/logout.html) is configured for this Webgate
E.17 Diagnosing Initialization and Performance Issues
This section includes the following topics:
■Diagnosing an Initialization Issue
■Diagnosing a Performance Issue
■Diagnosing Out-of-Memory Issues With a Heap Dump
E.17.1 Diagnosing an Initialization Issue
Problem
OAM Server does not start up.
Solution
1. Locate and review the OAM Server log file on the computer hosting the OAM
Server.
DOMAIN_HOME/servers/SERVER-NAME/logs/SERVER-NAME-diagnostics.log
See Also: Chapter 27, "Configuring Centralized Logout for Sessions
Involving 11g WebGates"
Diagnosing Initialization and Performance Issues
Troubleshooting E-17
2. Enable logging for this computer, as described in Chapter 7, "Logging Component
Event Messages":
DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml
3. Restart the OAM Server, observe the behavior, check the log file again if needed.
E.17.2 Diagnosing a Performance Issue
Problem
Monitoring the OAM Server reveals a significant spike in latency during
authentication.
Solution
1. Locate and review the OAM Server log file on the computer hosting the OAM
Server.
DOMAIN_HOME/servers/SERVER-NAME/logs/SERVER-NAME-diagnostics.log
2. Enable logging for this computer, as described in Chapter 7, "Logging Component
Event Messages":
DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml
3. Restart the OAM Server, observe the behavior, check the log file again if needed.
E.17.3 Diagnosing Out-of-Memory Issues With a Heap Dump
Problem
Debugging for all expression parsing and evaluation produced a significant
performance drag within ~20 hours due to memory growth; running out of memory in
~50 hours.
Configuration: 2GB heap; 3 minute session timeout; jdbc connections tuned min=32
max=200; jdbc connection idle timeout disabled; jbo pool size min = 10 & max=150
Solution
To generate heap-dumps for comparison, you use the following command-line tools
jmap for Sun jvm or jrcmd for jrockit jvm located under JAVA_HOME/bin.
For jrockit jvm
jrcmd pid <command>
/jrockit_160_14_R27.6.5-32/bin/jrcmd 16775 heap_diagnostics
/jrockit_160_14_R27.6.5-32/bin/jrcmd 16775 print_threads
/jrockit_160_14_R27.6.5-32/bin/jrcmd 16775 jrarecording ....
For Sun jvm
jmap -histo <pid>
jmap -dump:live,format=b,file=heap.bin <pid>
Disabling Windows Challenge/Response Authentication on IIS Web Servers
E-18 Administrator's Guide for Oracle Access Management
E.18 Disabling Windows Challenge/Response Authentication on IIS Web
Servers
The IIS Web server on Windows supports Challenge/Response Authentication, which
defaults to On when IIS is installed. This enables users to use their domain log-ins
when requesting resources from IIS and can conflict with Access Manager's
authentication.
For example, on the first request from an Internet Explorer (IE) browser to a resource
on IIS protected by Access Manager with a basic authentication scheme, IE displays a
login dialog box requesting a domain along with the user name and password login
provided by Access Manager.
To disable Windows challenge/response authentication
1. Launch the Microsoft Management Console for IIS.
2. Select the Web Server Host under Internet Information Server in the left hand
panel.
3. Right click and select Properties.
4. Scroll down and select Edit the Master Properties for WWW Service.
5. Select the Directory Security tab.
6. Select Edit Anonymous Access and Authentication Control.
7. Complete the appropriate step for your platform:
Windows 2000: Clear the Integrate Windows Authentication box.
8. Click OK.
9. In the Windows IIS properties screen, click OK.
10. Close the Microsoft Management Console.
E.19 Changing UserIdentityStore1 Type Can Lock Out Administrators
An Identity Store that is designated as the System Store should not be edited to change
the store type (from Embedded LDAP to OID, for instance) nor the connection URLs.
If you do need to change the Identity Store that is designated as the System Store
should not be edited to change the store type, Oracle recommends that you create a
new Identity Store and then edit that registration to mark it as your System Store.
E.20 IIS Web Server Issues
The following topics are provided to assist you:
■Form Authentication or Pass-Through Not Working
■IIS and General Web Component Guidelines
■Issues with IIS v6 Web Servers
■Page Cannot Be Displayed Error
■Removing and Reinstalling IIS DLLs
IIS Web Server Issues
Troubleshooting E-19
E.20.1 Form Authentication or Pass-Through Not Working
If form authentication or pass-through functionality is not working, the problem might
be that either "
UseWebGateExtForPassthrough
" parameter is not set to true in the
Webgate profile or that webgate.dll is not configured as Wild Card Application
Mapping in IIS. In such cases, Webgate does not perform authentication or
authorization for HTTP "POST" requests for the resources protected by form-based
authentication.
Solution: Confirm that the
UseWebGateExtForPassthrough
parameter is configured in
the Webgate profile with a value of
true
and that webgate.dll is configured as Wild
Card Application Mapping.
E.20.2 IIS and General Web Component Guidelines
Following are some general guidelines to follow when installing Access Manager
Webgates with IIS Web servers.
Account Privileges: The account that performs Access Manager installation must have
administration privileges. The user account that is used to run OAM services must
have the "Log on as a service" right, which can be set by selecting Administrative
Tools, Local Policy, Local Policies, User Rights Assignments, Log on as a service.
IIS 6 Web Servers: You must run the WWW service in IIS 5.0 isolation mode. This is
required by the ISAPI postgate filter. During Access Manager installation, this is
usually set automatically. If it is not, you must set it manually for the Default Web site.
Webgate for IIS 7 Web Server: To use Form-based authentication without enabling
pass through functionality (for example,
"access/oblix/apps/webgate/bin/webgate.dll" is an action in the Form-based
authentication scheme), ensure that the entry "<add segment="bin"/>" is not present
in the applicationHost.config file. If the entry is present, you must remove it. Use the
following steps to check this entry:
■Go to Windows\System32\inetsrv\config and open the file
applicationHost.config.
■Search for the <
hiddenSegments
> module and remove the entry
<add
segment="bin"/>
if it is present.
Webgate: When installing IIS Webgates, setting various permissions for the /access
directory is required for IIS Webgates only when you are installing on a file system
that supports NTFS. For example, suppose you install the ISAPI Webgate in Simple or
Cert mode on a Windows 2000 computer running the FAT32 file system. The last
installation panel provides instructions for manually setting various permissions that
cannot be set on the FAT32 file system. In this case, these instructions may be ignored.
E.20.3 Issues with IIS v6 Web Servers
On IIS 6 Web servers only, you must run the WWW service in IIS 5.0 isolation mode,
which is a requirement of the ISAPI postgate filter. This scenario will work if you have
32-bit Access Manager binaries running on a 32-bit Windows operating system.
However, there is an issue if you attempt to run a 32-bit postgate.dll on a 64-bit
Windows machine with IIS running in 32-bit mode.
Problem
When running IIS in IIS5.0 isolation mode, you see the following message:
"ISAPI Filter 'C:\webgate\access\oblix\apps\webgate\bin\webgate.dll' could not be
loaded due to a configuration problem.
IIS Web Server Issues
E-20 Administrator's Guide for Oracle Access Management
Cause
The current configuration only supports loading images built for an AMD 64-bit
processor architecture. The data field contains the error number.
Solution
To learn more about this issue, including how to troubleshoot this kind of processor
architecture mismatch error, see the following Web site:
http://go.microsoft.com/fwlink/?LinkId=29349
For more information, see Help and Support Center at:
http://go.microsoft.com/fwlink/events.asp
Problem
IIS5 never existed as 64-bit. However, IIS v6's IIS5 Compatibility Mode on 64-bit
Windows computers only runs as 64-bit.
Cause
It is architecturally impossible run IIS5 Isolation Mode 32- bit on 64-bit Windows, as
described in documentation available through the following URLs:
http://www.microsoft.com/communities/newsgroups/en-us/default.aspx?dg=microsoft.pu
blic.inetserver.iis&tid=5dd07102-8896-40cc-86cb-809060fa9426&cat=en_US_
02ceb021-bb43-476d-8f8f-6c00a363ccf5&lang=en&cr=US&p=1
http://blogs.msdn.com/david.wang/archive/2005/12/14/HOWTO-Diagnose-one-cause-of-W3
SVC-failing-to-start-with-Win32-Error-193-on-64bit-Windows.aspx
E.20.4 Page Cannot Be Displayed Error
A "The page cannot be displayed" error that appears after configuring Webgate for
pass-through functionality, indicates a configuration issue.
Solution: Confirm that the
UseWebGateExtForPassthrough
parameter is configured in
the Webgate profile with a value of
true
and that webgate.dll is configured as Wild
Card Application Mapping.
E.20.5 Removing and Reinstalling IIS DLLs
When Access Manager is running with Microsoft's IIS Web server, you must manually
uninstall and reinstall the following ISAPI filters when reinstalling Access Manager.
■
tranfilter.dll
■
oblixlock.dll
(if you installed Webgate)
■
webgate.dll
(if you installed Webgate)
To remove and reinstall IIS DLLs
1. Uninstall Access Manager.
2. Manually uninstall the preceding DLLs.
3. Reinstall Access Manager.Active Directory.
4. Manually reinstall the DLLs.
Internationalization, Languages, and Translation
Troubleshooting E-21
E.21 Import and File Upload Limits
The UPLOAD_MAX_MEMORY and UPLOAD_MAX_DISK_SPACE is set to "50mb".
To upload more than 50mb, manually change these settings in web.xml.
To reset the memory and disk space parameters
1. Locate web.xml in WEB-INF/lib/ngam-ui.war.
2. Edit the file to change UPLOAD_MAX_MEMORY. For example:
<context-param>
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY</param-name>
<param-value>104857600</param-value>
<context-param>
3. Edit the file to change UPLOAD_MAX_DISK_SPACE. For example:
<context-param>
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE</param-name>
<param-value>104857600</param-value>
<context-param>
4. Save the file.
5. Restart the OAM Server.
E.22 jps Logger Class Instantiation Warning is Logged on Authentication
A jps logger class instantiation warning is might appear on the back end upon
authentication. However, this is a harmless warning and no action is required.
E.23 Internationalization, Languages, and Translation
This section provides the following topics:
■Automatically Generated Descriptions Are Not Translated
■Console Looks Messy
■Authentication Fails: Users with Non-ASCII Characters
■Access Tester Does Not Work with Non-ASCII Agent Names
■Locales, Languages, and Oracle Access Management Console Login Page
Note: These filters can change depending on the version of IIS you
are using. If these filters do not exist or there are others present,
contact Oracle to determine if the filters that are present need to be
removed.
See Also: "Providing File Upload Capability" in the Oracle
Application Development Framework Developer's Guide.
Internationalization, Languages, and Translation
E-22 Administrator's Guide for Oracle Access Management
E.23.1 Automatically Generated Descriptions Are Not Translated
The automatically generated Description for some components are not translated. This
is expected and enables Administrators to change the Description to whatever they
require. Following such a change, translation by Oracle is not possible.
E.23.2 Console Looks Messy
The Oracle Access Management Console displays policies and resources oddly when
the input configuration file for remote registration is not in UTF-8 format or when the
OAM Server is not started in UTF-8 locale (en_US.utf8, for instance).
Be sure to use UTF-8 encoding if creating a configuration file for the remote
registration tool, oamreg, to generate authentication policies and protected resources.
Also, be sure to start OAM Server in UTF-8 locale machines. Otherwise, the Oracle
Access Management Console might display policies and resources oddly following
successful inband registration.
E.23.3 Authentication Fails: Users with Non-ASCII Characters
Configure Access Manager to use Kerberos Authentication Scheme with WNA
challenge method, and create a non-ASCII user in Microsoft Active Directory.
Problem
An exception occurs when trying to get user details to populate the subject with the
user DN and GUID attributes. Authentication fails and an error is recorded in the
OAM Server log when a non-ASCII user in Active Directory attempts to access an
Access Manager-protected resource:
... Failure getting users by attribute : cn, value ....
Cause
The username in the attribute is passed without modification as a java string.
Solution
Non-ASCII users can access the resource protected by Kerberos WNA scheme now by
applying this JVM system property (for the built-in WebLogic SPNEGO support):
-Dsun.security.krb5.msinterop.kstring=true
E.23.4 Access Tester Does Not Work with Non-ASCII Agent Names
Register a Webgate with Access Manager using a non-ASCII name. In the Access
Tester, enter the valid IP Address, Port, and Agent ID (non-ASCII name), then click
Connect.
Connection testing fails.
E.23.5 Locales, Languages, and Oracle Access Management Console Login Page
When the browser locale is not supported, the Oracle Access Management Console
Login page shows as server locale. It should fall back to English. This is the expected
behavior:
■If the client Locale is not supported, Oracle Access Management falls back to the
server locale.
OAM Metric Persistence Timer IllegalStateException: SafeCluster
Troubleshooting E-23
■If the server locale is not supported, Oracle Access Management falls back to
English.
When users select an unsupported language and come to the Access Manager SSO
page, it shows as server locale (German, for example). However, after logging in, all
the pages are displayed as English.
To fall back to English
Disable the Access Manager SSO page and the original Access Manager login page
also falls back to English.
E.24 Login Failure for a Protected Page
Problem
After installing OAM and protecting a page using a physical host and port, register the
application using the OHS physical host and port. Login fails to prompt the user for
credentials when accessing the protected page. The log file shows that the URL is
re-directed to a Virtual Host despite the fact that all configuration and registration is
setup correctly.
Solution
Remove any Virtual Host Directives from httpd.conf when protecting a page using the
Oracle HTTP Server (OHS) physical host and port.
E.25 OAM Metric Persistence Timer IllegalStateException: SafeCluster
Problem
After using the WebLogic Configuration Wizard to create an OAM Server cluster on
two computers, and starting AdminServer, all servers start up properly. After shut
down, a third server is added using the WebLogic Server Administration Console to
create a new managed server and add it to the cluster. The third server goes into
Running mode when started, with some exceptions in the start up log.
... Exception in thread "OAM Metric Persistence Timer"
Solution
in addition to the actions in the WebLogic Administration Console, you must register
the server using the Oracle Access Management Console to ensure that the server can
identify itself.
For server registration details, see "Managing Individual OAM Server Registrations"
on page 6-5.
Note: When adding and registering a second server instance for the
same computer, all port numbers must differ: OAM Proxy port; the
"port" that must match the one in the WebLogic Server Console; and
the Coherence port.
Partial Cluster Failure and Intermittent Login and Logout Failures
E-24 Administrator's Guide for Oracle Access Management
E.26 Partial Cluster Failure and Intermittent Login and Logout Failures
Problem
In the event of a partial outage of Access Manager (on some, but not all instances of
the cluster), end users might see intermittent login and logout failures.
Workarounds
1. Remove OHS from the deployment
2. Configure the OHS cluster such that each OHS instance is pinned to a WebLogic
Server instance.
3. The WebLogic Server container with the malfunctioning Access Manager
application must be removed from service (shutdown) and brought back up upon
recovery.
E.27 RSA SecurID Issues and Logs
Each OAM SecurID Server must be registered as a separate agent with the RSA
Authentication Manager. This provisions the OAM SecurID Server with its own node
secret file. Every OAM SecurID Server must have its configuration file stored under
$DOMAIN_HOME/config/fmwconfig/servers/$SERVER_NAME/oam.
If the RSA SecurID authentication plug-in returns an error, it is logged in the OAM
Server log. Web Server logs can also provide clues as to what might be going wrong.
Be sure the enable logging on your Web server.
If communication has been established between the Access Server and Authentication
Manager, the
sdadmin
tool provides access to logs under the Report menu. Both
Activity and Exception reports may give you helpful information.
Verify Authentication Manager Logging Configuration and Reports
1. Confirm that you have added the user and assigned a token using the
Authentication Manager Administrator tool,
sdadmin
.
2. Verify that you have copied the
sdconf.rec
file to the OAM Server.
3. In the Authentication Manager console, Report menu, open Activity and
Exception reports for helpful information.
Check SecurID Plug-In Parameters with Modified HTML Fields
If you have modified the HTML field names in the HTML forms, ensure that the RSA
SecurID plug-in parameters are configured to match.
Remove the @ character From any Login Attribute Value
User login can fail if there is an at-sign (@) in the login attribute value. This is a known
issue with SecurID.
SELinux Issues
Troubleshooting E-25
E.28 Registration Issues
Problem: Remote Registration Tool Failure
Solution
Ensure that the agent name is unique (does not already exist) and that the
AdminServer is running.
Problem: No ObAccessClient.xml File Generated
Solution
Protected and public resources must be described as relative URLs of the format
'/index.html'. If the resource does not begin with a '/', no ObAccessClient.xml file will
be generated.Verify the protected and public resource URLs and ensure all begin with
a "/". For more information, see "About the Resource URL, Prefixes, and Patterns" on
page 25-18.
Problem: Partner Registration Failure
Partner registration can fail if you do not supply a unique agent name, which is also
used to create an Application Domain. The agent name and Application Domain name
must be the same and must be unique. Using the oamreg validate command can fail
when the agent name does not match the Application Domain name.
Solution
Ensure that the agent name and Application Domain name are the same.
E.29 Rowkey does not have any primary key attributes Error
While browsing across the Resources table in the Resource Type tab the following error
message is logged:
@ <Error>
<oracle.adfinternal.view.faces.model.binding.CurrencyRowKeySet>
@ <BEA-000000> <ADFv: Rowkey does not have any primary key attributes. Rowkey:
oracle.jbo.Key[], table: model.ResTypeVOImpl@620289.>
This is harmless and does not hinder any functionality.
E.30 SELinux Issues
Delivered with Oracle Enterprise Linux, SELinux modifications provide a variety of
policies through the use of Linux Security Modules (LSM) within the Linux kernel.
SELinux requires performing additional steps after installing Access Manager
Webgates and before starting the associated Web server.
Problem
The following errors could be reported in logs/console when starting a Web server on
Linux distributions that have more strict SELinux policies in place (after installing an
Webgate):
11g Webgate
$Webgate_OH/webgate/ohs/lib/webgate.so: cannot restore segment prot after reloc:
Permission denied.
Session Issues
E-26 Administrator's Guide for Oracle Access Management
10g Webgate
$Webgate_install_dir/access/oblix/apps/webgate/bin/webgate.so: cannot restore
segment prot after reloc:
Permission denied.
Cause
These errors are reported due to Secure Linux security context policies on files.
Solution
To avoid these errors and start the Web server, run following
chcon
commands to
change the security context on files after installing each Access Manager Web
component and before restarting the associated Web server. For more information on
the
chcon
command, see your Linux documentation.
1. Run chcon -t texrel_shlib_t PATH_TO_LIBWEBPLUGINS.SO. For example:
chcon -t texrel_shlib_t /Webgate_install_dir/access/oblix/lib/webgate.so
... and libxmlengine.so
2. Run chcon -t texrel_shlib_t PATH_TO_LIBWEBGATE.SO. For example:
chcon -t texrel_shlib_t /Webgate_install_dir/access/oblix/apps/webgate/
bin/webgate.so
E.31 Session Issues
This section provides the following details:
■Session Impersonation Not Enabled by Default
■Sessions with Oracle Access Manager 11.1.1 Integrated with Oracle Identity
Federation 11.1.1
E.31.1 Session Impersonation Not Enabled by Default
Session impersonation is not enabled by default. You can update the value in
oam-config.xml, then update the version of oam-config.xml to automatically
propagate the ImpersonationConfig status to all managed servers without a restart.
To enable Session Impersonation
1. Back up DOMAIN_HOME/config/fmwconfig/oam-config.xml.
2. Set
ImpersonationConfig
to
true
:
<Setting Name="ImpersonationConfig" Type="htf:map">
<Setting Name="EnableImpersonation" Type="xsd:boolean">false</Setting>
</Setting>
3. Configuration Version: Increment the
Version xsd:integer
as shown in the next
to last line of this example (existing value (25, here) + 1):
Example:
<Setting Name="Version" Type="xsd:integer">
<Setting xmlns="http://www.w3.org/2001/XMLSchema"
Name="NGAMConfiguration" Type="htf:map:>
<Setting Name="ProductRelease" Type="xsd:string">11.1.1.3</Setting>
Start Up Issues
Troubleshooting E-27
<Setting Name="Version" Type="xsd:integer">25</Setting>
</Setting>
4. Save oam-config.xml.
E.31.2 Sessions with Oracle Access Manager 11.1.1 Integrated with Oracle Identity
Federation 11.1.1
Expected Behavior: Oracle Identity Federation 11.1.1 session is not cleared
When Oracle Access Manager 11.1.1 is integrated with Oracle Identity Federation
11.1.1, and you clear the session using the console, only the Oracle Access Manager
session is cleared. The Oracle Identity Federation session is not cleared.
E.32 SSL versus Open Communication
If both the SSL and Open ports of the Managed Server are enabled, then the Managed
Server is set to the SSL port by default.
If you must use the non-ssl port, the credential collector URL the authentication
scheme must be set to the absolute URL which points to 'http' as the protocol and
non-ssl port.
E.33 Start Up Issues
Problem: AdminServer Startup (or Remote Registration Tool Failure) on AIX
Platforms
AdminServer start up fails with following message:
"java.net.SocketException:
No buffer space available".
Configuration for the number of AIX file descriptors set for the operating system is
substantially high (
ulimit
file descriptor) resulting in a buffer overflow that causes
remote registration failure with the following message:
The ulimit value is application dependent and applies exclusively to application
program data and the application stack. The default number of open files setting
(2000) is typically sufficient for most applications. If the value is too low, errors might
occur when opening files or establishing connections. Because this value limits the
number of file descriptors that a server process might open, a value that is too low
prevents optimum performance. For the AIX operating system, the default setting is
2000.
Solution
Increasing the
ulimit
file descriptor limits might improve performance. Increasing
some of the other limits might be needed depending on your application.
1. Log in as root.
2. Perform the following steps to change the open file limit to 10,000 files:
a. Open the command window.
b. Locate and edit /etc/security/limits file to add the following lines to the user
account on which the AdminServer process runs:
nofiles = 10000
Synchronizing OAM Server Clocks
E-28 Administrator's Guide for Oracle Access Management
nofiles_hard = 10000
c. Save the file and restart AIX.
3. In a command window, decrease the TCP_TIMEWAIT interval with the following
command to set the state to 15 seconds (which allows TCP to release closed
connections faster and increases the number of available resources for open
connections).
/usr/sbin/no –o tcp_timewait =1
4. Tune the following parameters to 256k, as shown:
no -a |grep space
tcp_recvspace = 262144
tcp_sendspace = 262144
udp_recvspace = 262144
udp_sendspace = 262144
5. Tune the following parameters as indicated here:
no -o rfc1323=1
no -o sb_max=4194304
Problem: Connection to OAM Server could not be established: Exception in
connecting to server. Connection refused.
Cause:
This is normal and expected behavior for the Managed Server where the OAM Server
runs because the IAMSuiteAgent agent is started before the OAM Server.
The IAMSuiteAgent is deployed on every WebLogic container. When the WebLogic
container starts, the agent tries to connect to the OAM Server. If it fails to connect, this
message is logged and the agent tries to establish the connection in subsequent
requests. When the agent is successful, this message is no longer displayed.
Solution
If the connection to the OAM Server is not successful, the IAMSuiteAgent falls back
and the WebLogic container handles protection (including login), if it is configured.
E.34 Synchronizing OAM Server Clocks
The state of a session is the source of truth for relying parties. Synchronization of
system clocks of the various Servers is required.
The system clock of the relying party might be out of synchronization with the SME
clock. If the relying party's clock is:
■Ahead of the session clock A relying party's request for authentication is made and
the active sessionID is returned.
■Behind the session clock: Event notifications to the relying party help invalidate
the session.
For example, if a Web server clock is ahead of the server clock, a request sent from the
Webgate to the OAM Server will contain a time that, to the OAM Server, has not yet
occurred. This can cause login events to fail. When running in Simple or Cert mode,
time stamps might become out of sync, or the client certificate might appear to be
invalid.
Using Coherence
Troubleshooting E-29
For successful operation:
■Ensure all computer clocks are synchronized. There is no tolerance level. If, for
example, the Webgate clock is even slightly ahead of the OAM Server clock, a
cookie generated by the Webgate will appear to be in the future and can cause
problems in the OAM Server.
■Confirm that the clock on each computer running a Webgate is not running ahead
of the OAM Servers with which it is associated. The OAM Server must be ahead of
the Webgate clock by a maximum of 60 seconds.
E.35 Using Coherence
Access Manager uses Oracle Coherence to replicate session states within a distributed
installation. Coherence is used to communicate state changes between the Oracle
Access Management Console and OAM Servers.
Consider the following 2 distributed deployment topologies. Coherence relies on User
Datagram Protocol (UDP) for cluster discovery and heartbeat. If a firewall exists
between certain components of Access Manager, then the corresponding UDP ports
used by Coherence must be open. Otherwise, Access Manager might not work
correctly.
For example, the UDP ports used by Coherence must be opened as follows:
■The Oracle Access Management Console is deployed within the intranet, and
OAM Servers are deployed in the DMZ. In this case, the UDP ports used by
Coherence must be opened on the firewall between the DMZ and the intranet.
■The Oracle Access Management Console and OAM Servers are deployed in
different security zones of the DMZ, with firewalls between any two adjacent
zones. In this case, the UDP ports used by Coherence must be opened on the
firewall between the adjacent security zones, where one or more instances of
Oracle Access Management Console and OAM Servers run.
Access Manager 11g uses Oracle Coherence to provide a distributed cache with
low-data access latencies and to transparently move data between distributed caches
(and into the session store). Session data is redundant across these tiers. For example,
when a session is created, it then exists within the local cache on the server that created
it, the distributed cache, and (if enabled) within the session store database as well. For
more information, see Chapter 16, "Maintaining Access Manager Sessions".
Whether you are viewing Oracle Coherence settings for an individual server instance
or Oracle Coherence details that are common to all OAM Servers, Oracle recommends
that you do not modify Oracle Coherence settings unless requested to do so by an
Oracle Support Representative.
Note: To avoid event notification issues, ensure that all OAM Server
clocks are synchronized to Time Services such as NIST internet time
service.
WARNING: Oracle recommends that you do not modify Oracle
Coherence settings unless requested to do so by an Oracle Support
Representative.
Validation Errors
E-30 Administrator's Guide for Oracle Access Management
Oracle Coherence logging appears in the WebLogic Server log only. There is no bridge
from Oracle Coherence logging to Access Manager logging.
E.36 Validation Errors
Problem: Resource not added to Authentication or Authorization Policy
While creating an Authentication or Authorization Policy, if you add a resource that is
already used in another Authentication or Authorization Policy, a validation error
appears when you click Apply. This is expected.
If you click OK in the error window and then attempt to add a valid resource that is
not used within another Authentication or Authorization Policy, the resource is not
added and the Authentication or Authorization Policy is not created.
Solution
1. Click Apply and close the Authentication or Authorization Policy page.
2. From the navigation tree, click the named policy again, click the Edit to open the
page, and add the new resource.
Problem: Validation Failure - "description" attribute is not valid
A validation error appears if you enter an optional description longer than 200
characters.
Solution
Keep optional descriptions to 200 characters in length and less than 10 lines.
E.37 Web Server Issues
The following issues with Web servers may arise:
■Server Fails on an Apache Web Server
■Apache v2 on HP-UX
■Apache v2 Bundled with Red Hat Enterprise Linux 4
■Apache v2 Bundled with Security-Enhanced Linux
■Apache v2 on UNIX with the mpm_worker_module for Webgate
■Domino Web Server Issues
■Errors, Loss of Access, and Unpredictable Behavior
■Known Issues for ISA Web Server
■Oracle HTTP Server Fails to Start with LinuxThreads
■Oracle HTTP Server Webgate Fails to Initialize On Linux Red Hat 4
■Oracle HTTP Server Web Server Configuration File Issue
■Issues with IIS v6 Web Servers
■PCLOSE Error When Starting Sun Web Server
■Removing and Reinstalling IIS DLLs
See Also: Oracle Coherence documentation.
Web Server Issues
Troubleshooting E-31
E.37.1 Server Fails on an Apache Web Server
Symptom: You are running an Apache Web server, and an OAM Server fails,
displaying the following message:
libthread panic: cannot create new lwp
(PID: 9035 LWP 2). stackrace:
ff3424cc
0
This symptom may be caused by the Apache Web server launching more instances of
itself. This can happen when the server determines that more instances are needed to
service the number of connections between one or more Webgates and the OAM
Server.
The additional instances create even more connections, which exceed the number of
connections by the OAM Server.
Solution: Reduce the number of
MinSpareServers
,
MaxSpareServers
,
StartServers
,
and
MaxClients
parameters.
Go to the OAM Server's configuration directory and open the
http.d
configuration
file.
Recommended parameter settings:
■
MinSpareServers
1
■
MaxSpareServers
5
■
StartServers
3
■
MaxClients
5
E.37.2 Apache v2 on HP-UX
When running Apache v2 on HP-UX, do not use
nobody
for User or Group, because
shared memory may not work. Instead, use your login name as User Name with a
your group as Group Name On HP-UX (on Solaris, "www" is equivalent to "nobody").
When running Apache v2 on HPUX 11.11, ensure that the
AcceptMutex
directive in the
Apache httpd.conf file is set to "
fcntl
". If the directive is not present, add it to the
httpd.conf file (
AcceptMutex fcntl
). For more information, see:
http://issues.apache.org/bugzilla/show_bug.cgi?id=22484
E.37.3 Apache v2 Bundled with Red Hat Enterprise Linux 4
After installing a Webgate on vendor-bundled Apache, the Web server may give the
following error upon startup:
Error: Cannot load libgcc_s.so.1 library - Permission denied.
Solution: Change the Security-Enhanced Linux (SELinux) policy rules for Access
Manager Webgates as described in "Tuning Apache/IHS v2 Webgates for Access
Manager" on page 31-27.
E.37.4 Apache v2 Bundled with Security-Enhanced Linux
Errors might be reported in WebServer logs/console when starting a Web server on
Linux distributions, which have stricter SELinux policies in place, after installing an
Access Manager Web component. You can avoid these errors by running appropriate
chcon
commands for the installed Web component before restarting the Web server.
Web Server Issues
E-32 Administrator's Guide for Oracle Access Management
E.37.5 Apache v2 on UNIX with the mpm_worker_module for Webgate
The following item is required only if you compile Apache v2 for Webgate on UNIX
with the mpm_worker_module. In this case, you need to modify the thread.c file from
the Apache source for the UNIX environment. Making this change ensures that the
default pthread stacksize for Webgate produces optimal performance during
multi-threaded server implementation. If this change is not made, the default pthread
stack size would not be sufficient for Webgate and could result in a crash.
Apache 2.0 does not support the ThreadStackSize option. Therefore:
■With UNIX-based Apache v2.1 and later you must use the ThreadStackSize
directive to set the size of the stack (for autodata) of threads that handle client
connections and call modules to help process those connections.
■With UNIX-based Apache 2, it is best to use the compilable source while adding
the mpm_worker_module and changing the thread.c file to avoid a stack overflow.
The following procedure shows how to modify the Apache v2.0 thread.c file to
provide the default pthread stacksize needed by Webgate for optimal performance
during multi-threaded server implementation. For details about the Apache v2.1+
ThreadStackSize directive, see
http://httpd.apache.org/docs/2.2/mod/mpm_
common.html#threadstacksize.
To modify the Apache v2.0 thread.c file for Webgate in a UNIX environment
1. Locate the thread.c file. For example:
APACHE 2.0.52 source/srclib/apr/threadproc/unix/thread.c
2. Locate the function named apr_threadattr_create(apr_threadattr_t **new,apr_
pool_t *pool) in the following code segment:
**new,apr_pool_t *pool) in the following code segment:
1-----> apr_status_t stat;
2
3-----> (*new) = (apr_threadattr_t *)apr_pcalloc(pool, sizeof(apr_threadattr_
t));
4-----> (*new)->attr = (pthread_attr_t *)apr_pcalloc(pool, sizeof(pthread_attr_
t));
5
6-----> if ((*new) == NULL || (*new)->attr == NULL) {
7-----> return APR_ENOMEM;
8-----> }
9
10----->(*new)->pool = pool;
11----->stat = pthread_attr_init((*new)->attr);
12
13-----> if (stat == 0) {
14-----> return APR_SUCCESS;
15-----> }
16----->#ifdef PTHREAD_SETS_ERRNO
17----->stat = errno;
18----->#endif
See Also: "SELinux Issues" on page E-25
Note: The following procedure should be performed only for the
Apache 2.0 Webgate. Otherwise, the default pthread stack size is not
sufficient for the Webgate and could result in a crash.
Web Server Issues
Troubleshooting E-33
19
20----->return stat;
21
3. Add the following code before line 13 shown earlier.
int stacksize = 1 << 20;
pthread_attr_setstacksize(&(*new)->attr, stacksize);
4. Run configure, make, and make install to set up the Apache Web server with the
mpm_worker_module.
E.37.6 Domino Web Server Issues
Failure Authentication Event: For Domino Web servers, the redirection of a URL
through Access Manager may not work if the authentication type is set as Basic Over
LDAP and the URL to be redirected is mentioned as one of the following:
Either a relative path present on the same Web server
Or the Full path URL on the same Web server containing a computer name
defined in the host identifier string combinations.
To overcome a failure authentication event, you must set the redirected URL with a
computer name that is not defined under the host identifier group. For example, the IP
address of the computer.
This problem does not occur with a form-based authentication type.
Header Variables: It may not be possible to pass header variables other than
REMOTE_USER to Webgates installed on Lotus Notes Domino Web servers when
using Client Certificate authentication scheme.
For example, header variables cannot be set on the one request where Client Certificate
authentication occurs. However, all other requests do allow header variables to be set.
For more information, see Chapter 34, "Configuring Lotus Domino Web Servers for
10g WebGates".
E.37.7 Errors, Loss of Access, and Unpredictable Behavior
Symptom: If you installed Access Manager on UNIX under a different user ID than
you used to create your Web server instance, Access Manager can become unstable.
Users may experience behavior such as:
■Random bug report pages
■Failure to write to log file errors
■Loss of access to Web pages
Solution: Change file permissions using the chown command. Change the Access
Manager directory to the same user ID that you used to create your Web server
instance.
E.37.8 Known Issues for ISA Web Server
Webgate uses ISAPI extension for displaying user deny error message and for
displaying the diagnostic page. However, ISA 2006 does not support extensions.
Therefore:
Web Server Issues
E-34 Administrator's Guide for Oracle Access Management
■If the user is denied access by Webgate, the user gets Page Cannot be displayed
error message instead of Access Manager denied access error message.
■The following diagnostic URL does not work for ISA:
http(s)://hostname:port/access/oblix/apps/webgate/bin/webgate.dll?progid=1
for webgate.
E.37.9 Oracle HTTP Server Fails to Start with LinuxThreads
After installing a Webgate instance on an Oracle HTTP Server, the server does not start
up. This occurs because Access Manager uses an older Linux threading model.
Solution: When using LinuxThreads mode, comment out the Perl module in the
httpd.conf file, update the LD_ASSUME_KERNEL environment variable, and restart,
as described in the following procedure.
To resolve the failure to start Oracle HTTP Server in LinuxThreads mode
1. Comment out the perl module in the httpd.conf file in the following location:
Oracle HTTP Server 11g:
$ORACLE_INSTANCE/config/OHS/ohs_name/httpd.conf
Oracle HTTP Server v2:
OH$/ohs/conf/httpd.conf
Oracle HTTP Server v1.3:
OH$/Apache/Apache/conf/httpd.conf
2. To update the LD_ASSUME_KERNEL value, open the following file in a text
editor:
OH$/opmn/conf/opm.xml
3. Find the following line:
<process-type id="HTTP_Server" module-id="OHS">
Add the following information under the line you found in the previous step:
<environment>
<variable id="LD_ASSUME_KERNEL" value="2.4.19" />
</environment>
4. Save this file.
5. Run the following commands to implement your changes:
opmnctl stopall
opmnctl startall
E.37.10 Oracle HTTP Server Webgate Fails to Initialize On Linux Red Hat 4
This situation might arise whether you are using Access Manager with LinuxThreads
or NPTL.
Symptom: Webgate fails to initialize when installed on an Oracle HTTP Server
running Red Hat Enterprise Server version 4.0 with a kernel version lower than
2.6.9-34.EL. Version 2.6.9-34.EL is supplied with the Red Hat version 4, update 3.
Note: When running Access Manager, LinuxThreads is used by
default. This requires setting the environment variable LD_ASSUME_
KERNEL to 2.4.19. If you are using NPTL with Access Manager, you
do not set LD_ASSUME_KERNEL to 2.4.19.9
Web Server Issues
Troubleshooting E-35
Solution: To prevent this problem, you must upgrade to Red Hat version 4, update 3
or higher.
E.37.11 Oracle HTTP Server Web Server Configuration File Issue
Problem
With Oracle Application Server 10.1.x, OC4J, when the httpd.conf file is modified
automatically during Webgate installation, it can be corrupted.
Solution
Before installing Webgate, run the following command to prevent the httpd.conf file
from being overwritten.
$ORACLE_HOME/dcm/bin/dcmctl updateConfig -ct ohs
E.37.12 Issues with IIS v6 Web Servers
On IIS 6 Web servers only, you must run the WWW service in IIS 5.0 isolation mode,
which is a requirement of the ISAPI postgate filter. This scenario will work if you have
32-bit Access Manager binaries running on a 32-bit Windows operating system.
However, there is an issue if you attempt to run a 32-bit postgate.dll on a 64-bit
Windows machine with IIS running in 32-bit mode.
Problem
When running IIS in IIS5.0 isolation mode, you see the following message:
"ISAPI Filter 'C:\webgate\access\oblix\apps\webgate\bin\webgate.dll' could not be
loaded due to a configuration problem.
Cause
The current configuration only supports loading images built for an AMD 64-bit
processor architecture. The data field contains the error number.
Solution
To learn more about this issue, including how to troubleshoot this kind of processor
architecture mismatch error, see the following Web site:
http://go.microsoft.com/fwlink/?LinkId=29349
For more information, see Help and Support Center at:
http://go.microsoft.com/fwlink/events.asp
Problem
IIS5 never existed as 64-bit. However, IIS v6's IIS5 Compatibility Mode on 64-bit
Windows computers only runs as 64-bit.
Cause
It is architecturally impossible run IIS5 Isolation Mode 32- bit on 64-bit Windows, as
described in documentation available through the following URLs:
http://www.microsoft.com/communities/newsgroups/en-us/default.aspx?dg=microsoft.pu
blic.inetserver.iis&tid=5dd07102-8896-40cc-86cb-809060fa9426&cat=en_US_
02ceb021-bb43-476d-8f8f-6c00a363ccf5&lang=en&cr=US&p=1
Windows Native Authentication
E-36 Administrator's Guide for Oracle Access Management
http://blogs.msdn.com/david.wang/archive/2005/12/14/HOWTO-Diagnose-one-cause-of-W3
SVC-failing-to-start-with-Win32-Error-193-on-64bit-Windows.aspx
E.37.13 PCLOSE Error When Starting Sun Web Server
Symptom: When attempting to start the Sun Web server, you get an error like the
following:
Unable to start, PCLOSE
Solution: A number of problems can cause this error:
■A syntax error in your
obj.conf
file
■Leading spaces in your
obj.conf
file
■Installing Access Manager as a different user ID than what you used to create your
Web server instance
■A carriage return at the end of the
obj.conf
file
E.37.14 Removing and Reinstalling IIS DLLs
When Access Manager is running with Microsoft's IIS Web server, you must manually
uninstall and reinstall the following ISAPI filters when reinstalling Access Manager.
■
tranfilter.dll
■
oblixlock.dll
(if you installed Webgate)
■
webgate.dll
(if you installed Webgate)
To remove and reinstall IIS DLLs
1. Uninstall Access Manager.
2. Manually uninstall the preceding DLLs.
3. Reinstall Access Manager.Active Directory.
4. Manually reinstall the DLLs.
E.38 Windows Native Authentication
Problem
After setting up Windows Native Authentication, and accessing the WNA-protected
page, the browser might give an error indicating that the user name and/or password
are incorrect.
Cause
The Identity Store used by Oracle Access Management might not point to Windows
Active Directory. By default, the identity store is Embedded LDAP.
Note: These filters can change depending on the version of IIS you
are using. If these filters do not exist or there are others present,
contact Oracle to determine if the filters that are present need to be
removed.
Windows Native Authentication
Troubleshooting E-37
Solution
1. In the Oracle Access Management Console, review the identity store
configuration: System Configuration, Data Sources, User Identity Store.
2. Confirm the LDAP store settings point to Active Directory.
Windows Native Authentication
E-38 Administrator's Guide for Oracle Access Management

Navigation menu