Aiaag Oracle Fusion Middleware Administrator Guide For Access Management 11.1.2.3

User Manual:

Open the PDF directly: View PDF .
Page Count: 1662

Download
Open PDF In Browser	View PDF

[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.

Content
Preface ............................................................................................................................................................... lvii
What's New in This Guide? .................................................................................................................... lix
Part I

Introduction to Oracle Access Management

1 Introducing Oracle Access Management
1.1
1.2
1.2.1
1.2.2
1.3
1.3.1
1.3.2
1.4
1.5
1.5.1
1.5.2
1.5.3

Understanding Oracle Access Management Services ........................................................... 1-1
Understanding Oracle Access Management Access Manager ............................................. 1-3
About Components in Access Manager ........................................................................... 1-4
Understanding Access Manager Deployments............................................................... 1-5
About Access Manager 11.1.2.3.0 ............................................................................................. 1-7
About the Features Of Access Manager 11.1.2.3.0 .......................................................... 1-7
About Features Not In Access Manager 11.1.2.3.0.......................................................... 1-9
About System Requirements and Certification ...................................................................... 1-9
Understanding Oracle Access Management Installation................................................... 1-10
About Oracle Access Management Installation .......................................................... 1-10
About Oracle Access Management and WebGates ..................................................... 1-10
About Oracle Access Management Post-Installation Tasks ....................................... 1-10

2 Getting Started with Oracle Access Management
2.1
2.1.1
2.1.2
2.1.3
2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.5
2.5.1

Starting and Stopping Servers in Your Deployment .............................................................
Starting Node Manager.......................................................................................................
Starting and Stopping WebLogic AdminServer..............................................................
Starting and Stopping Managed WebLogic Servers and Access Manager Servers ...
About Oracle Access Management Administrators ..............................................................
About the Oracle Access Management Console and the Policy Manager Console ..........
Understanding the Oracle Access Management Console.....................................................
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.............................................................................
Logging Into the Oracle Access Management Console.........................................................
Logging Into The Oracle Access Management Console ................................................

2-1
2-1
2-2
2-2
2-3
2-4
2-5
2-5
2-6
2-6
2-7
2-7
2-7
2-8

iii

2.5.2
2.6
2.6.1
2.6.2
2.6.3
2.7
2.8
2.9
2.9.1
2.9.2
2.9.3

Logging Into the Secure Oracle Access Management Console (HTTPS) .................... 2-8
Using the Oracle Access Management Console ..................................................................... 2-9
Signing Out........................................................................................................................... 2-9
Accessing Online Help..................................................................................................... 2-10
Conducting A Search ....................................................................................................... 2-10
Configuring with the Command-Line Tools ....................................................................... 2-11
Logging, Auditing, Reporting and Monitoring Performance ........................................... 2-11
Configuring Oracle Access Management Login Options .................................................. 2-12
Administering the Forgot Password URL .................................................................... 2-12
Choosing a User Login Language .................................................................................. 2-13
Understanding Persistent Login..................................................................................... 2-16

Part II Managing Common and System Configurations
3 Managing Common Services and Certificate Validation
3.1
3.2
3.3
3.3.1
3.3.2
3.4
3.4.1
3.4.2
3.4.3
3.4.4

Configuring Oracle Access Management................................................................................ 3-1
Enabling or Disabling Available Services ............................................................................... 3-3
Managing Common Settings..................................................................................................... 3-5
Managing Common Settings ............................................................................................. 3-6
Viewing Common Coherence Settings............................................................................. 3-7
Managing Certificate Validation and Revocation .................................................................. 3-7
Enabling the Certificate Revocation List Functionality.................................................. 3-8
Enabling OCSP Certificate Validation ............................................................................. 3-9
Enabling CRL Distribution Point Extensions .................................................................. 3-9
Additional OCSP Configurations................................................................................... 3-10

4 Delegating Administration
4.1
4.2
4.3
4.4
4.5
4.6

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
4-2
4-3
4-3
4-4
4-4

5 Managing Data Sources
5.1
5.1.1
5.1.2
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
5.2.6
5.2.7

iv

About the Data Sources ............................................................................................................. 5-1
About the oam-config.xml Configuration Data File....................................................... 5-3
About the Default LDAP Group........................................................................................ 5-4
Registering and Managing User Identity Stores ................................................................... 5-4
Understanding User Identity Stores ................................................................................. 5-4
Using the System Store for User Identities ...................................................................... 5-5
Using Multiple Identity Stores........................................................................................... 5-6
Defining the User Identity Store Registration Settings .................................................. 5-8
Registering a New User Identity Store .......................................................................... 5-12
Viewing or Editing a User Identity Store Registration ............................................... 5-13
Deleting a User Identity Store Registration .................................................................. 5-14

5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.4
5.4.1
5.4.2
5.5
5.5.1
5.5.2
5.5.3
5.6
5.6.1
5.6.2
5.6.3
5.7

Managing the Identity Directory Service User Identity Stores .........................................
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......................................................
Understanding Administrator Roles.....................................................................................
Adding Administrator Roles...........................................................................................
Managing Administrator Roles ......................................................................................
Managing the Policy and Session Database ........................................................................
About the Database Store for Policy, Password Management, and Sessions ..........
About Database Deployment..........................................................................................
Configuring a Separate Database for Access Manager Sessions ...............................
Introduction to Oracle Access Management Keystores .....................................................
About Access Manager Security Keys and the Embedded Java Keystore ...............
About Access Manager Keystores..................................................................................
About Identity Federation Keystore ..............................................................................
Integrating a Supported LDAP Directory with Oracle Access Manager ........................

5-14
5-15
5-17
5-21
5-24
5-25
5-25
5-26
5-27
5-27
5-29
5-29
5-29
5-30
5-31
5-31
5-32
5-34
5-34

6 Managing Server Registration
6.1
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.2.5
6.3
6.3.1
6.3.2
6.3.3
6.3.4

Part III

Before You Register ....................................................................................................................
Understanding OAM Server Registration and Management...............................................
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 ...................................
About Restarting Servers After Configuration Changes ...............................................
Managing Individual OAM Server Registrations .................................................................
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-1
6-1
6-2
6-3
6-3
6-4
6-4
6-5
6-5
6-8
6-9
6-9

Logging, Auditing, Reporting and Monitoring Performance

7 Logging Component Event Messages
7.1
7.2
7.2.1
7.2.2
7.2.3
7.3
7.3.1
7.3.2
7.4

About Oracle Access Management Logging...........................................................................
Logging Component Event Messages .....................................................................................
About Component Loggers................................................................................................
Sample Logger and Log Handler Definition ...................................................................
About Logging Levels.........................................................................................................
Configuring Logging for Access Manager .............................................................................
Modifying the Logger Level for Access Manager...........................................................
Adding an Access Manager-Specific Logger and Log Handler ...................................
Configuring Logging for Security Token Service and Identity Federation........................

7-1
7-1
7-3
7-4
7-5
7-5
7-6
7-7
7-8

v

7.4.1
7.4.2
7.5
7.6
7.7

Configuring Logging for Security Token Service or Identity Federation ................... 7-9
Defining Log Level and Log Details for Security Token Service or Identity Federation ..
7-10
About Mobile and Social Logging ......................................................................................... 7-11
Understanding Logging for the Access Portal Service....................................................... 7-11
Validating Run-time Event Logging Configuration ........................................................... 7-11

8 Auditing Administrative and Run-time Events
8.1
8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.3
8.3.1
8.3.2
8.3.3
8.4
8.4.1
8.4.2
8.5
8.5.1
8.5.2
8.5.3
8.5.4
8.6
8.6.1
8.6.2
8.6.3
8.7
8.7.1
8.7.2
8.7.3
8.7.4
8.8

Introduction to Oracle Fusion Middleware Auditing ........................................................... 8-1
Understanding Oracle Access Management Auditing ......................................................... 8-2
About Oracle Access Management Auditing Configuration ....................................... 8-2
About Audit Record Storage.............................................................................................. 8-3
About Audit Reports and Oracle Business Intelligence Publisher............................... 8-4
About the Audit Log and Data .......................................................................................... 8-5
Access Manager Events You Can Audit.................................................................................. 8-6
Access Manager Administrative Events You Can Audit............................................... 8-6
Access Manager Run-time Events You Can Audit ......................................................... 8-8
Auditing Authentication Events..................................................................................... 8-11
Mobile and Social Events You Can Audit ............................................................................ 8-11
REST Run-Time Audit Events ........................................................................................ 8-11
Mobile and Social Audit Events ..................................................................................... 8-12
Identity Federation Events You Can Audit.......................................................................... 8-14
Session Management Events for Identity Federation.................................................. 8-14
Protocol Flow Events for Identity Federation .............................................................. 8-15
Server Configuration Events for Identity Federation.................................................. 8-15
Security Events for Identity Federation......................................................................... 8-16
Security Token Service Events You Can Audit ................................................................... 8-16
About Audit Record Content Common to All Events ................................................ 8-17
Security Token Service Administrative Events You Can Audit ................................ 8-17
Security Token Service Run-time Events You Can Audit........................................... 8-19
Setting Up Auditing for Oracle Access Management ........................................................ 8-20
Setting Up the Audit Database Store ............................................................................. 8-21
Preparing Oracle Business Intelligence Publisher EE ................................................. 8-21
Using the Oracle Access Management Console for Audit Configuration .............. 8-22
Adding, Viewing, or Editing Audit Settings ............................................................... 8-24
Validating Auditing and Reports ......................................................................................... 8-25

9 Logging WebGate Event Messages
9.1
9.1.1
9.1.2
9.2
9.2.1
9.2.2
9.3
9.4
9.4.1
vi

About Logging, Log Levels, and Log Output......................................................................... 9-1
About Log Levels................................................................................................................. 9-2
About Log Output ............................................................................................................... 9-3
About Log Configuration File Paths and Contents ............................................................... 9-4
Log Configuration File Paths and Names ........................................................................ 9-4
Log Configuration File Contents ....................................................................................... 9-5
About Directing Log Output to a File or the System File ..................................................... 9-9
Structure and Parameters of the Log Configuration File ................................................... 9-10
About The Log Configuration File Header................................................................... 9-11

9.4.2
9.4.3
9.4.4
9.4.5
9.4.6
9.4.7
9.5
9.5.1
9.6
9.6.1
9.6.2
9.7
9.7.1
9.7.2
9.8

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.............................................................................................
About Activating and Suppressing Logging Levels...........................................................
About Log Handler Precedence .....................................................................................
Understanding the Mandatory Log-Handler Configuration Parameters .......................
Settings in the Default Log Configuration File ............................................................
Description of the Settings in the Default Log Configuration File ............................
Configuring Different Threshold Levels for Different Types of Data..............................
About the MODULE_CONFIG Section.........................................................................
Configuring a Log Level Threshold for a Function or Module .................................
Filtering Sensitive Attributes..................................................................................................

9-11
9-11
9-13
9-14
9-14
9-15
9-16
9-16
9-17
9-18
9-20
9-22
9-22
9-25
9-26

10 Reporting
10.1
10.2
10.3
10.4
10.4.1
10.4.2
10.4.3
10.5

About the Reports ....................................................................................................................
Accessing Oracle Access Management Reports ..................................................................
Supported Output Formats ....................................................................................................
Reports for Access Manager...................................................................................................
Account Management Reports .......................................................................................
Authentication Reports....................................................................................................
Errors and Exceptions ......................................................................................................
Creating Reports Using Third-Party Software ....................................................................

10-1
10-2
10-2
10-3
10-3
10-3
10-4
10-6

11 Monitoring Performance and Health
11.1
11.2
11.2.1
11.2.2
11.3
11.3.1
11.3.2
11.4
11.4.1
11.4.2
11.5
11.5.1
11.5.2
11.5.3
11.6
11.6.1
11.6.2

Introduction to Performance Monitoring.............................................................................
Monitoring Server Metrics Using Oracle Access Management Console .........................
Monitoring Server Instance Performance .....................................................................
Reviewing Server Metrics................................................................................................
Monitoring SSO Agent Metrics Using Oracle Access Management Console .................
Reviewing WebGate Metrics ..........................................................................................
Reviewing OSSO Agent Metrics.....................................................................................
Introduction to OAM Proxy Metrics and Tuning .............................................................
About OAM Proxy Metrics ...........................................................................................
OAM Proxy Server Tuning Parameters.......................................................................
Monitoring Metrics Using the DMS Console ....................................................................
Monitoring OAM Metrics..............................................................................................
Monitoring Coherence Caches......................................................................................
Monitoring OpenSSO Proxy Metrics ...........................................................................
Monitoring the Health of an Access Manager Server.......................................................
Understanding WebGate and Access Manager Communications ..........................
Monitoring Access Manager Server Health................................................................

11-1
11-2
11-2
11-2
11-6
11-6
11-8
11-10
11-10
11-10
11-11
11-11
11-12
11-12
11-14
11-15
11-15

vii

12 Monitoring Performance and Logs with Fusion Middleware Control
12.1
12.2
12.2.1
12.2.2
12.3
12.3.1
12.3.2
12.3.3
12.4
12.4.1
12.4.2
12.4.3
12.4.4
12.5
12.5.1
12.5.2
12.6
12.6.1
12.6.2
12.7
12.7.1
12.7.2
12.8
12.8.1
12.8.2

Introduction to Fusion Middleware Control ......................................................................
Logging In to and Out of Fusion Middleware Control ......................................................
Logging In To Fusion Middleware Control..................................................................
Logging Out of Fusion Middleware Control................................................................
Displaying Menus and Pages in Fusion Middleware Control .........................................
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 .....
Viewing Performance in Fusion Middleware Control .......................................................
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 ..............................................
Managing Log Level Changes in Fusion Middleware Control.......................................
About Dynamic Log Level Changes ............................................................................
Setting Log Levels Dynamically Using Fusion Middleware Control .....................
Managing Log File Configuration from Fusion Middleware Control ...........................
About Log File Configuration.......................................................................................
Managing Log Files with Fusion Middleware Control.............................................
Viewing Log Messages in Fusion Middleware Control...................................................
About Finding, Viewing, and Exporting Log Messages ...........................................
Viewing Logged Messages With Fusion Middleware Control................................
Displaying MBeans in Fusion Middleware Control .........................................................
About the System MBean Browser...............................................................................
Managing Mbeans ..........................................................................................................

12-1
12-2
12-3
12-3
12-3
12-3
12-5
12-7
12-8
12-9
12-15
12-17
12-19
12-19
12-20
12-24
12-24
12-24
12-27
12-28
12-28
12-32
12-33
12-34
12-36

Part IV Managing Access Manager Settings and Agents
13 Configuring Access Manager Settings
13.1
13.2
13.2.1
13.2.2
13.3
13.3.1
13.3.2
13.4
13.4.1
13.4.2
13.5
13.5.1
13.5.2
13.5.3
13.5.4
13.5.5

viii

Oracle Access Management Overview .................................................................................
Managing Load Balancing .....................................................................................................
About Common Load Balancing Settings ....................................................................
Managing OAM Server Load Balancing Settings ........................................................
Managing Secure Error Modes .............................................................................................
About OAM Server Error Modes ...................................................................................
Managing OAM Server Secure Error Modes................................................................
Managing SSO Tokens and IP Validation ............................................................................
About Access Manager SSO Tokens and IP Validation Settings ...............................
Managing SSO Tokens and IP Validation.....................................................................
Managing the Access Protocol for OAM Proxy Simple and Cert Mode Security ..........
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................................................................................

13-1
13-1
13-1
13-2
13-3
13-3
13-5
13-5
13-5
13-6
13-6
13-7
13-8
13-8
13-9
13-9

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
15.2
15.2.1
15.2.2
15.2.3
15.3
15.4
15.4.1
15.4.2
15.4.3
15.4.4
15.5
15.5.1
15.5.2
15.5.3
15.6
15.6.1
15.7
15.7.1
15.7.2
15.7.3
15.7.4
15.8
15.8.1
15.8.2
15.9

Before Registering and Managing Agents............................................................................ 15-1
Understanding OAM Agent Registration Parameters in the Console............................. 15-2
About Create OAM WebGate Page and Parameters................................................... 15-2
About User-Defined WebGate Parameters................................................................... 15-5
About IP Address Validation for WebGates............................................................... 15-10
Registering an OAM Agent Using the Console................................................................. 15-13
Configuring and Managing Registered OAM Agents Using the Console .................... 15-14
Understanding Registered OAM Agent Configuration Parameters in the Console .........
15-14
Searching for an OAM Agent Registration ................................................................. 15-20
Viewing or Editing an OAM Agent Registration Page in the Console................... 15-22
Deleting OAM Agent Registration Using the Console ............................................. 15-23
Understanding the Remote Registration Tool, Modes, and Process .............................. 15-24
About Remote Registration Command Arguments and Modes ............................. 15-25
Common Elements within Remote Registration Request Templates ..................... 15-26
About Key Use, Generation, Provisioning, and Storage........................................... 15-27
Understanding Remote Registration Templates: OAM Agents...................................... 15-29
OAM Agent Parameters for Remote Registration ..................................................... 15-29
Performing Remote Registration for OAM Agents .......................................................... 15-32
Acquiring and Setting Up the Remote Registration Tool ........................................ 15-33
Creating Your Remote Registration Request.............................................................. 15-34
Performing In-Band Remote Registration .................................................................. 15-34
Performing Out-of-Band Remote Registration .......................................................... 15-35
Introduction to Updating Agents Remotely ...................................................................... 15-37
About Remote Agent Update Modes ......................................................................... 15-37
About Remote 11g OAM Agent Updates Template.................................................. 15-37
Updating Agents Remotely ................................................................................................. 15-38

ix

15.9.1
Updating Agent Registrations Remotely ....................................................................
15.9.2
Validating an Agent Registration Remotely ...............................................................
15.9.3
Removing an Agent Registration Remotely ...............................................................
15.10 Validating Remote Registration and Resource Protection...............................................
15.10.1
Validating Agent Registration using the Oracle Access Management Console....
15.10.2
Verifying Authentication and Access After Remote Registration ..........................
15.11 Replacing the IAMSuiteAgent with an 11g WebGate ......................................................
15.11.1
Registering a Replacement 11g WebGate for IAMSuiteAgent ................................
15.11.2
Installing the Replacement 11g WebGate for IAMSuiteAgent ................................
15.11.3
Updating the WebLogic Server Plug-in Configuration ............................................
15.11.4
Confirming the AutoLogin Host Identifier for an OAM / OIM Integration.........
15.11.5
Configuring OAM Security Providers for WebLogic................................................
15.11.6
Disabling IAMSuiteAgent .............................................................................................
15.11.7
Verifying the Webgate Configuration .........................................................................
15.12 Managing the Preferred Host in 10g WebGates................................................................

15-38
15-39
15-39
15-40
15-40
15-40
15-42
15-43
15-45
15-45
15-46
15-46
15-50
15-51
15-51

setAllowEmptyHostIdentifier.............................................................................................. 15-53

16 Maintaining Access Manager Sessions
16.1
16.2
16.2.1
16.2.2
16.2.3
16.3
16.3.1
16.3.2
16.4
16.4.1
16.4.2
16.4.3
16.4.4
16.5
16.5.1
16.5.2
16.6
16.7
16.8
16.8.1
16.8.2

Introducing Access Manager Session Management ...........................................................
Understanding Server-Side Session Management..............................................................
Securing Access Manager Sessions ................................................................................
Understanding the Access Manager Session Lifecycle, States, and Enforcement...
Access Manager Sessions and the Role of Oracle Coherence.....................................
Server-Side Session Enforcement Examples ........................................................................
Example 1: Single Authentication Scheme....................................................................
Example 2: Multiple Authentication Schemes..............................................................
Configuring the Server-Side Session Lifecycle ...................................................................
About Global Session Lifecycle Settings .......................................................................
About Application-Specific Session Overrides ..........................................................
Viewing or Modifying Global Session Settings..........................................................
Viewing or Modifying Optional Application-Specific Session Overrides .............
Managing Active Server-Side Sessions...............................................................................
About the Session Management Pages........................................................................
Locating and Managing Active Sessions.....................................................................
Validating Server-Side Session Operations........................................................................
Understanding Client-Side Session Management.............................................................
Using WLST To Configure Session Management .............................................................
displaySSOSessionType.................................................................................................
configSSOSessionType...................................................................................................

16-1
16-2
16-2
16-3
16-6
16-7
16-7
16-7
16-8
16-9
16-10
16-11
16-11
16-12
16-12
16-14
16-15
16-16
16-16
16-16
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

x

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
18.2
18.3
18.3.1
18.3.2
18.4
18.5
18.5.1
18.5.2
18.5.3
18.6
18.6.1
18.6.2
18.6.3
18.6.4
18.6.5

Before Setting Up a Multi-Data Center.................................................................................
Understanding the Primary Use Cases.................................................................................
Setting Up a Multi-Data Center .............................................................................................
Enabling the Master Data Center ...................................................................................
Setting Up the Clone Data Center ..................................................................................
Adding A Second Clone to An Existing Multi-Data Center Setup...................................
Understanding Multi-Data Center Security Modes............................................................
OPEN Security Mode .......................................................................................................
SIMPLE Security Mode ....................................................................................................
CERT Security Mode ........................................................................................................
WLST Commands for Multi-Data Centers.........................................................................
enableMultiDataCentreMode .......................................................................................
disableMultiDataCentreMode ......................................................................................
addPartnerForMultiDataCentre ...................................................................................
removePartnerForMultiDataCentre.............................................................................
setMultiDataCenterType ...............................................................................................

18-1
18-2
18-2
18-3
18-5
18-7
18-7
18-8
18-8
18-9
18-10
18-11
18-12
18-13
18-14
18-15

xi

18.6.6
18.6.7
18.6.8
18.6.9
18.6.10

setMultiDataCenterWrite ..............................................................................................
setMultiDataCentreClusterName ................................................................................
validateMDCConfig .......................................................................................................
exportAccessStore...........................................................................................................
importAccessStore ..........................................................................................................

18-15
18-16
18-16
18-16
18-17

19 Synchronizing Data In A Multi-Data Center
19.1
19.1.1
19.1.2
19.1.3
19.2
19.3
19.3.1
19.3.2
19.3.3
19.4
19.5
19.6
19.6.1
19.6.2
19.6.3
19.7
19.8
19.8.1
19.8.2

Understanding the Multi-Data Center Sync ........................................................................
How Replication Works...................................................................................................
Understanding the Replication Agreement .................................................................
Manually Syncing Data in a Multi-Data Center...........................................................
Enabling Data Replication ......................................................................................................
Syncing Master and Clone Metadata ....................................................................................
Syncing the UDM Metadata............................................................................................
Creating the Replication Agreement .............................................................................
Modifying the Replication Agreement ..........................................................................
Using and Customizing Transformation Rules...................................................................
Modifying a Rule Document ................................................................................................
Using REST API for Replication Agreements....................................................................
Querying for Replication Agreement Details .............................................................
Modifying an Existing Replication Agreement..........................................................
Deleting a Replication Agreement ...............................................................................
Replicating Domains in Identity Manager Deployments ................................................
Best Practices for Replication ...............................................................................................
Enabling Replication Logs.............................................................................................
Changing the User Identifier ........................................................................................

19-1
19-2
19-3
19-4
19-4
19-5
19-5
19-5
19-8
19-9
19-11
19-13
19-13
19-13
19-14
19-14
19-15
19-15
19-15

20 Setting Up the Multi-Data Center: A Sequence
20.1
20.2
20.3
20.4

Part VI

Before You Begin......................................................................................................................
Setting Up a Multi-Data Center .............................................................................................
Enabling Automated Policy Synchronization .....................................................................
Troubleshooting the Multi-Data Center Setup ..................................................................

20-1
20-2
20-9
20-11

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.1
About Multiple Network Domain SSO .........................................................................
21.1.2
About Application SSO and Access Manager ..............................................................
21.1.3
About Multiple WebLogic Server Domain SSO...........................................................
21.1.4
About Reverse-Proxy SSO ...............................................................................................
21.2
Understanding the Access Manager Policy Model.............................................................
21.3
Anatomy of an Application Domain and Policies ............................................................
21.3.1
About Resource Definitions for Policies......................................................................
21.3.2
About Authentication Policies .....................................................................................
21.3.3
About Authorization Policies........................................................................................

xii

21-1
21-4
21-4
21-5
21-6
21-7
21-10
21-11
21-11
21-12

21.3.4
About Token Issuance Policies .....................................................................................
21.4
Introduction to Policy Conditions and Rules ....................................................................
21.5
Understanding SSO Cookies ................................................................................................
21.5.1
About Single Sign-On Cookies During User Login...................................................
21.5.2
About Single Sign-On Server and Agent Cookies .....................................................
21.6
Introduction to Configuration Tasks for Single Sign-On .................................................

21-13
21-13
21-14
21-14
21-15
21-20

22 Managing Authentication and Shared Policy Components
22.1
22.2
22.3
22.3.1
22.3.2
22.3.3
22.3.4
22.4
22.4.1
22.4.2
22.4.3
22.4.4
22.4.5
22.4.6
22.4.7
22.5
22.5.1
22.5.2
22.5.3
22.6
22.6.1
22.6.2
22.6.3
22.7
22.7.1
22.7.2
22.7.3
22.7.4
22.7.5
22.7.6
22.7.7
22.7.8
22.8
22.8.1
22.8.2
22.8.3
22.8.4

Prerequisites ............................................................................................................................. 22-1
Understanding Authentication and Shared Policy Component Tasks ........................... 22-1
Managing Resource Types...................................................................................................... 22-2
About Resource Types and Their Use ........................................................................... 22-2
About the Resource Type Page....................................................................................... 22-4
Searching for a Specific Resource Type ......................................................................... 22-6
Creating a Custom Resource Type................................................................................. 22-7
Managing Host Identifiers...................................................................................................... 22-7
About Host Identifiers ..................................................................................................... 22-8
About Virtual Web Hosting ......................................................................................... 22-10
About the Host Identifier Page ..................................................................................... 22-14
Creating a Host Identifier .............................................................................................. 22-15
Searching for a Host Identifier Definition................................................................... 22-16
Viewing or Editing a Host Identifier Definition ........................................................ 22-16
Deleting a Host Identifier Definition ........................................................................... 22-17
Understanding Authentication Methods and Credential Collectors ............................. 22-18
About Different Authentication Methods................................................................... 22-18
Comparing Embedded Credential Collector with Detached Credential Collector ...........
22-19
Authentication Event Logging and Auditing ............................................................ 22-23
Managing Native Authentication Modules ....................................................................... 22-23
About Native Access Manager Authentication Modules ........................................ 22-24
Viewing or Editing Native Authentication Modules ................................................ 22-28
Deleting a Native Authentication Module.................................................................. 22-29
Orchestrating Multi-Step Authentication with Plug-in Based Modules ...................... 22-29
Comparing Simple Form and Multi-Factor (Multi-Step) Authentication .............. 22-30
About Plug-ins for Multi-Step Authentication Modules ......................................... 22-31
About Plug-in Based Modules for Multi-Step Authentication ................................ 22-39
Example: Leveraging SubjectAltName Extension Data and Integrating with Multiple
OCSP Endpoints 22-46
Creating and Orchestrating Plug-in Based Multi-Step Authentication Modules . 22-48
Creating and Managing Step-Up Authentication ..................................................... 22-50
Configuring an HTTPToken Extractor Plug-in .......................................................... 22-56
Configuring a JSON Web Token Plug-in .................................................................... 22-56
Deploying and Managing Individual Plug-ins for Authentication................................ 22-58
About Managing Your Own Authentication Plug-ins .............................................. 22-59
Making Custom Authentication Plug-ins Available for Use ................................... 22-62
Checking an Authentication Plug-in's Activation Status.......................................... 22-63
Deleting Your Custom Authentication Plug-ins ........................................................ 22-64

xiii

22.9
Managing Authentication Schemes.....................................................................................
22.9.1
About Authentication Schemes and Pages .................................................................
22.9.2
Understanding Multi-Level and Step-Up Authentication........................................
22.9.3
Creating an Authentication Scheme ............................................................................
22.9.4
Searching for an Authentication Scheme ....................................................................
22.9.5
Viewing, Editing, or Deleting an Authentication Scheme........................................
22.10 Extending Authentication Schemes with Advanced Rules .............................................
22.10.1
Using Advanced Rules...................................................................................................
22.10.2
Using Context Data for Advanced Rules ....................................................................
22.11 Configuring Challenge Parameters for Encrypted Cookies ............................................
22.11.1
About Challenge Parameters for Encrypted Cookies................................................
22.11.2
Configuring Challenge Parameters for Security of Encrypted Cookies .................
22.11.3
Setting Challenge Parameters for Persistence of Encrypted Cookies .....................
22.12 Configuring Authentication POST Data Handling...........................................................
22.12.1
About Authentication Post Data Preservation and Restoration ..............................
22.12.2
About Configuring Authentication POST Data Handling .......................................
22.12.3
About Post Data Size Limits..........................................................................................
22.12.4
Configuring Authentication POST Data Handling ...................................................
22.12.5
Testing POST Data Handling Configuration..............................................................
22.13 Long URL Handling During Authentication.....................................................................
22.13.1
About Long URLs and Authentication Handling......................................................
22.13.2
About Configuring Long URL Handling ....................................................................
22.14 Using Application Initiated Authentication ......................................................................

22-64
22-65
22-79
22-82
22-83
22-83
22-84
22-85
22-86
22-88
22-88
22-89
22-89
22-90
22-90
22-91
22-93
22-94
22-95
22-95
22-95
22-96
22-97

23 Understanding Credential Collection and Login
23.1
23.1.1
23.1.2
23.2
23.3
23.4
23.5
23.5.1
23.5.2
23.5.3
23.5.4
23.6
23.6.1
23.6.2
23.7
23.7.1
23.7.2
23.7.3

Logging In with Access Manager Credential Collection ...................................................
Login with Self-Service Provisioning Applications.....................................................
Login Processing with Access Manager-Protected Resources ...................................
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 ...................................
Enabling DCC Credential Operations .........................................................................
Locating and Updating DCC Forms for Password Policy .......................................
Adding PasswordPolicyValidationScheme to Authentication Policy for DCC ....
Supporting Federation Flows With DCC ....................................................................
Tunneling from DCC to Access Manager Over Oracle Access Protocol .......................
How DCC Tunneling with OAP Works......................................................................
Configuring OAP Tunneling.........................................................................................
Configuring a DCC WebGate for X509 Authentication ...................................................
Configuring the WebLogic Server................................................................................
Configuring a WebGate For DCC ................................................................................
Converting the DCC WebGate to SSL .........................................................................

23-1
23-2
23-2
23-3
23-5
23-9
23-10
23-11
23-12
23-12
23-14
23-14
23-15
23-15
23-16
23-16
23-19
23-20

24 Using Password Policy
24.1
24.2
xiv

Using Password Management ............................................................................................... 24-1
Enabling Password Management .......................................................................................... 24-2

Configuring Password Policy ................................................................................................ 24-3
Specifying Credential Collector URLs with Password Policy........................................... 24-5
Using the Oracle-Provided Password Forms....................................................................... 24-8
Managing Global Password Policy ..................................................................................... 24-10
Defining Your Global Password Policy....................................................................... 24-11
Designating the Default Store for Your Password Policy......................................... 24-12
Adding Key Password Attributes to the Default Store............................................. 24-13
Adding an Administrator to Change User Attributes After a Password Change 24-15
Configuring Password Policy Authentication .................................................................. 24-15
Configuring the Password Policy Validation Authentication Module .................. 24-15
Configuring the PasswordPolicyValidationScheme ................................................ 24-19
Adding Your PasswordPolicyValidationScheme to ECC Authentication Policy . 24-20
Completing Password Policy Configuration ..................................................................... 24-21
Setting the Error Message Mode for Password Policy Messages ............................ 24-21
Overriding Native LDAP Password Policy Validation............................................. 24-21
Disabling ECC Operation and Using DCC Exclusively............................................ 24-22
Testing Your Multi-Step Authentication..................................................................... 24-23
Configuring the IPFUserPasswordPolicyPlugin............................................................... 24-24
Enabling the IPF Password Service.............................................................................. 24-24
Configuring Password Policy for IPF Password Service .......................................... 24-25
Extending the LDAP Definitions.................................................................................. 24-25
Configuring the Password Policy Validation Authentication Module and Scheme .........
24-26
24.9.5
Setting Up the Forgot Password Module .................................................................... 24-26

24.3
24.4
24.5
24.6
24.6.1
24.6.2
24.6.3
24.6.4
24.7
24.7.1
24.7.2
24.7.3
24.8
24.8.1
24.8.2
24.8.3
24.8.4
24.9
24.9.1
24.9.2
24.9.3
24.9.4

25 Managing Policies to Protect Resources and Enable SSO
25.1
25.2
25.2.1
25.2.2
25.2.3
25.3
25.3.1
25.3.2
25.3.3
25.3.4
25.3.5
25.3.6
25.4
25.4.1
25.4.2
25.4.3
25.4.4
25.5
25.5.1
25.5.2
25.5.3

Prerequisites .............................................................................................................................
Introduction to Application Domain and Policy Creation ................................................
Generating Application Domains and Policies Automatically..................................
Managing Application Domains and Policies Remotely ............................................
Creating or Managing an Application Domain and Policies .....................................
Understanding Application Domain and Policy Management ........................................
Navigating the Application Domain Pages ..................................................................
Displaying the Application Domain Summary Page ..................................................
Displaying the Resource Container in an Application Domain ................................
Displaying Authentication Policy Pages .......................................................................
Displaying Authorization Policy Pages.........................................................................
Displaying Token Issuance Policy Pages ....................................................................
Managing Application Domains Using the Console ........................................................
Creating a New Application Domain ..........................................................................
Searching for an Existing Application Domain..........................................................
Viewing or Editing an Application Domain...............................................................
Deleting an Application Domain and Its Contents ...................................................
Adding and Managing Policy Resource Definitions ........................................................
Defining Resources in an Application Domain..........................................................
Defining Resources in an Application Domain..........................................................
Searching for a Resource Definition.............................................................................

25-1
25-2
25-3
25-3
25-3
25-4
25-5
25-5
25-6
25-7
25-8
25-10
25-10
25-11
25-12
25-12
25-13
25-13
25-14
25-27
25-28

xv

25.5.4
Viewing, Editing, or Deleting a Resource Definition ...............................................
25.6
Defining Authentication Policies for Specific Resources .................................................
25.6.1
About the Authentication Policy Page ........................................................................
25.6.2
Creating an Authentication Policy for Specific Resources .......................................
25.6.3
Searching for an Authentication Policy .......................................................................
25.6.4
Viewing or Editing an Authentication Policy.............................................................
25.6.5
Deleting an Authentication Policy ...............................................................................
25.7
Defining Authorization Policies for Specific Resources...................................................
25.7.1
About Authorization Policies for Specific Resources ................................................
25.7.2
Creating an Authorization Policy and Specific Resources .......................................
25.7.3
Searching for an Authorization Policy .......................................................................
25.7.4
Viewing or Editing an Authorization Policy and Resources ...................................
25.7.5
Deleting an Entire Authorization Policy ....................................................................
25.8
Configuring Success and Failure URLs for Authorization Policies................................
25.9
Introduction to Authorization Policy Rules and Conditions ..........................................
25.9.1
About Allow or Deny Rules ..........................................................................................
25.9.2
About Authorization Policy Conditions ....................................................................
25.9.3
About Classifying Users and Groups for Conditions ...............................................
25.9.4
Guidelines for Authorization Responses Based on Conditions...............................
25.10 Defining Authorization Policy Conditions ........................................................................
25.10.1
Choosing a Condition Type ..........................................................................................
25.10.2
Defining Identity Conditions ........................................................................................
25.10.3
Defining IP4 Range Conditions ....................................................................................
25.10.4
Defining Temporal Conditions.....................................................................................
25.10.5
Defining Attribute Conditions......................................................................................
25.10.6
Viewing, Editing, or Deleting Authorization Policy Conditions.............................
25.11 Defining Authorization Policy Rules ..................................................................................
25.11.1
About Defining Rules in an Authorization Policy.....................................................
25.11.2
About Expressions and Expression-Based Policy Evaluation..................................
25.11.3
Defining Rules in an Authorization Policy .................................................................
25.12 Configuring Policy Ordering ...............................................................................................
25.13 Introduction to Policy Responses for SSO..........................................................................
25.13.1
About Authentication and Authorization Policy Responses for SSO.....................
25.13.2
About the Policy Response Language .........................................................................
25.13.3
About the Namespace and Variable Names for Policy Responses .........................
25.13.4
About Constructing a Policy Response for SSO.........................................................
25.13.5
About Policy Response Processing ..............................................................................
25.13.6
About Assertion Claims and Processing .....................................................................
25.14 Adding and Managing Policy Responses for SSO ............................................................
25.14.1
Adding a Policy Response for SSO ..............................................................................
25.14.2
Viewing, Editing, or Deleting a Policy Response for SSO ........................................
25.15 Validating Authentication and Authorization in an Application Domain ...................
25.16 Understanding Remote Policy and Application Domain Management........................
25.16.1
About Managing Policies Remotely.............................................................................
25.16.2
About the Create Policy Request Template ................................................................
25.16.3
About the Update Policy Request Template...............................................................
25.16.4
About Remote Policy Management and Templates ..................................................

xvi

25-30
25-31
25-31
25-33
25-34
25-34
25-35
25-35
25-36
25-37
25-37
25-38
25-38
25-39
25-40
25-40
25-41
25-42
25-43
25-43
25-44
25-45
25-51
25-54
25-55
25-59
25-60
25-60
25-63
25-66
25-67
25-68
25-68
25-70
25-70
25-72
25-74
25-75
25-75
25-75
25-76
25-76
25-77
25-78
25-79
25-80
25-80

25.17
25.18

Managing Policies and Application Domains Remotely ................................................. 25-82
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

xvii

27.4
Validating Global Sign-On and Centralized Logout .........................................................
27.4.1
Confirming Global Sign-On ............................................................................................
27.4.2
Validating Global Sign-On with Mixed Agent Types .................................................
27.4.3
Observing Centralized Logout .......................................................................................

Part VII

27-6
27-6
27-7
27-8

Registering and Using Agents with Access Manager

28 Registering and Managing Legacy OpenSSO Agents
28.1
28.1.1
28.1.2
28.2
28.3
28.3.1
28.3.2
28.4
28.4.1
28.4.2
28.5
28.5.1
28.5.2
28.5.3
28.5.4
28.6
28.6.1
28.7

Introduction to OpenSSO, Agents, Migration and Co-existence ......................................
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............................
Understanding OpenSSO Agent Registration Parameters ..............................................
About OpenSSO Agent Registration Parameters.......................................................
About the Expanded OpenSSO Agent Page and Parameters ..................................
Registering and Managing OpenSSO Agents Using the Console .................................
Registering an OpenSSO Agent using the Oracle Access Management Console .
Configuring and Managing Registered OpenSSO Agents Using the Console......
Performing Remote Registration for OpenSSO Agents ...................................................
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..................
Updating Registered OpenSSO Agents Remotely ............................................................
Updating OpenSSO Agents Remotely.........................................................................
Locating Other OpenSSO Agent Information ...................................................................

28-1
28-2
28-4
28-6
28-10
28-10
28-12
28-19
28-20
28-21
28-22
28-22
28-24
28-25
28-26
28-27
28-28
28-28

29 Registering and Managing Legacy OSSO Agents
29.1
29.1.1
29.1.2
29.2
29.2.1
29.2.2
29.3
29.3.1
29.3.2
29.3.3
29.3.4
29.4
29.4.1
29.4.2
29.4.3
29.5
29.6
29.6.1

xviii

Understanding OSSO Agents with Access Manager.......................................................... 29-1
About OSSO Agents with Access Manager .................................................................. 29-1
Comparing Access Manager 11g SSO versus OSSO 10g ............................................ 29-2
Registering OSSO Agents Using Oracle Access Management Console........................... 29-6
Understanding the Create OSSO Agent Registration Page and Parameters ........... 29-6
Registering an OSSO Agent (mod_osso) Using the Console ..................................... 29-8
Configuring and Managing Registered OSSO Agents Using the Console...................... 29-9
Understanding the Expanded OSSO Agent Page in the Console.............................. 29-9
Searching for an OSSO Agent (mod_osso) Registration .......................................... 29-10
Viewing or Editing OSSO Agent (mod_osso) Registration ...................................... 29-11
Deleting an OSSO Agent (mod_osso) Registration ................................................... 29-11
Performing Remote Registration for OSSO Agents .......................................................... 29-12
Understanding Request Templates for OSSO Remote Registration ....................... 29-12
Performing In-Band Remote Registration of OSSO Agents ..................................... 29-13
Performing Out-of-Band Remote Registration for OSSO Agents............................ 29-14
Updating Registered OSSO Agents Remotely................................................................... 29-15
Configuring Logout for OSSO Agents with Access Manager 11.1.2.............................. 29-16
About Centralized Logout with OSSO Agents (mod_OSSO) and Access Manager..........
29-17

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.2
Introduction to 10g OAM Agents for Access Manager 11g...............................................
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.3
About Installing Fresh 10g WebGates to Use With Access Manager 11.1.2 ............
30.2.4
About Centralized Logout with 10g OAM Agents and 11g OAM Servers..............
30.3
Comparing Access Manager 11.1.2 and 10g ........................................................................
30.3.1
Comparing Access Manager 11g versus 10g ................................................................
30.3.2
Comparing Access Manager 11g versus 10g Policy Model........................................
30.4
Configuring Centralized Logout for IAMSuiteAgent ......................................................
30.5
Registering a 10g WebGate with Access Manager 11g Remotely...................................
30.6
Managing 10g OAM Agents Remotely...............................................................................
30.7
Locating and Installing the Latest 10g WebGate for Access Manager 11g....................
30.7.1
Preparing for a Fresh 10g WebGate Installation with Access Manager 11g ..........
30.7.2
Locating and Downloading 10g WebGates for Use with Access Manager 11g ....
30.7.3
Starting WebGate 10g Installation................................................................................
30.7.4
Specifying a Transport Security Mode ........................................................................
30.7.5
Requesting or Installing Certificates for Secure Communications..........................
30.7.6
Specifying WebGate Configuration Details................................................................
30.7.7
Updating the WebGate Web Server Configuration...................................................
30.7.8
Finishing WebGate Installation ....................................................................................
30.7.9
Installing Artifacts and Certificates .............................................................................
30.7.10
Confirming WebGate Installation ................................................................................
30.8
Configuring Centralized Logout for 10g WebGate with 11g OAM Servers .................
30.8.1
About Centralized Logout Processing for 10g WebGate with 11g OAM Server ..
30.8.2
About the Centralized Logout Script for 10g WebGates with 11g OAM Servers .
30.8.3
Configuring Centralized Logout for 10g WebGates with Access Manager...........
30.9
Removing a 10g WebGate from the Access Manager 11g Deployment ........................

30-1
30-2

30-2
30-3
30-4
30-5
30-5
30-7
30-10
30-11
30-13
30-14
30-14
30-16
30-17
30-18
30-18
30-19
30-19
30-21
30-21
30-22
30-22
30-23
30-24
30-26
30-27

31 Configuring Apache, OHS, IHS for 10g WebGates
31.1
31.2
31.3
31.3.1
31.3.2
31.3.3
31.4
31.5
31.5.1
31.5.2
31.5.3

Prerequisites .............................................................................................................................
About Oracle HTTP Server and Access Manager ...............................................................
About Access Manager with Apache and IHS v2 Webgates.............................................
About the Apache HTTP Server .....................................................................................
About the IBM HTTP Server ...........................................................................................
About the Apache and IBM HTTP Reverse Proxy Server ..........................................
About Apache v2 Architecture and Access Manager.........................................................
Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers ............................
Requirements for IHS2 Web Servers..............................................................................
Requirements for Apache and IHS v2 Reverse Proxy Servers...................................
Requirements for Apache v2 Web Servers....................................................................

31-1
31-1
31-2
31-3
31-3
31-3
31-4
31-5
31-6
31-6
31-6

xix

31.6
Preparing Your Web Server....................................................................................................
31.6.1
Preparing the IHS v2 Web Server ..................................................................................
31.6.2
Preparing Apache and Oracle HTTP Server Web Servers on Linux.......................
31.6.3
Preparing Oracle HTTP Server Web Servers on Linux and Windows Platforms.
31.6.4
Setting Oracle HTTP Server Client Certificates..........................................................
31.6.5
Preparing the Apache v2 Web Server on UNIX.........................................................
31.6.6
Preparing the Apache v2 SSL Web Server on AIX.....................................................
31.6.7
Preparing the Apache v2 Web Server on Windows .................................................
31.7
Activating Reverse Proxy for Apache v2 and IHS v2.......................................................
31.7.1
Activating Reverse Proxy For Apache v2 Web Servers ............................................
31.7.2
Activating Reverse Proxy For IHS v2 Web Servers ...................................................
31.8
Verifying httpd.conf Updates for Webgates ......................................................................
31.8.1
Verifying Webgate Details.............................................................................................
31.8.2
Verifying Language Encoding ......................................................................................
31.9
Tuning Oracle HTTP Server Webgates for Access Manager...........................................
31.10 Tuning OHS /Apache Prefork and Worker MPM Modules for OAM..........................
31.10.1
Tuning Oracle HTTP Server /Apache Prefork MPM Module.................................
31.10.2
Tuning Oracle HTTP Server /Apache Worker MPM Module ................................
31.10.3
Tuning Kernel Parameters.............................................................................................
31.11 Starting and Stopping Oracle HTTP Server Web Servers................................................
31.12 Tuning Apache/IHS v2 Webgates for Access Manager .................................................
31.13 Removing Web Server Configuration Changes After Uninstall.....................................
31.14 Helpful Information .............................................................................................................

31-7
31-8
31-11
31-11
31-12
31-12
31-16
31-17
31-19
31-19
31-20
31-22
31-22
31-24
31-25
31-25
31-26
31-26
31-27
31-27
31-27
31-30
31-30

32 Configuring the ISA Server for 10g WebGates
32.1
32.2
32.3
32.4
32.4.1
32.4.2
32.5
32.5.1
32.5.2
32.5.3
32.6
32.7

33

32-1
32-1
32-2
32-2
32-2
32-3
32-3
32-3
32-4
32-6
32-7
32-7

Configuring the IIS Web Server for 10g WebGates
33.1
33.2
33.2.1
33.3
33.3.1
33.3.2
33.4
33.5

xx

Prerequisites .............................................................................................................................
About Access Manager and the ISA Server ........................................................................
Compatibility and Platform Support ...................................................................................
Installing and Configuring Webgate for the ISA Server ....................................................
Installing Webgate with ISA Server ...............................................................................
Changing /access Directory Permissions ....................................................................
Configuring the ISA Server for the ISAPI Webgate............................................................
Registering Access Manager Plug-ins as ISA Server Web Filters..............................
Configuring ISA Firewall Policies for ISA Web Filters ...............................................
Ordering the ISAPI Filters ...............................................................................................
Starting, Stopping, and Restarting the ISA Server .............................................................
Removing Access Manager Filters Before Webgate Uninstall on ISA Server.................

Prerequisites .............................................................................................................................
WebGate Guidelines for IIS Web Servers ............................................................................
Guidelines for ISAPI WebGates ....................................................................................
Prerequisite for Installing Webgate for IIS 7........................................................................
Prerequisite for Installing Any 10g Webgate for IIS 7.................................................
Prerequisite for Installing a 32-bit Webgate for IIS 7...................................................
Updating IIS 7 Web Server Configuration on Windows 2008...........................................
Completing Webgate Installation with IIS ...........................................................................

33-1
33-1
33-2
33-5
33-5
33-6
33-6
33-7

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
34.2
34.3
34.4
34.5
34.6
34.6.1

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 .......................................................................
Completing the WebGate Installation ..........................................................................

34-1
34-1
34-2
34-3
34-3
34-4
34-5

Part VIII Managing the Adaptive Authentication Service and Oracle Mobile
Authenticator
35 Introducing the Adaptive Authentication Service
35.1
35.2
35.2.1
35.2.2
35.2.3
35.3
35.4
35.4.1
35.4.2
35.4.3

Using the Adaptive Authentication Service ........................................................................
Working with the Adaptive Authentication Service ..........................................................
Understanding the One Time Password Option..........................................................
Understanding the Access Request (Push) Notification Option ...............................
Using the Oracle Mobile Authenticator with OTP And Access Request .................
Understanding Adaptive Authentication Service and OMA Configurations ................
Configuring the Adaptive Authentication Service .............................................................
Generating a Secret Key for the Oracle Mobile Authenticator ..................................
Configuring Mobile OAuth Services to Protect the Secret Key .................................
Configuring the Adaptive Authentication Plug-in......................................................

35-1
35-2
35-3
35-4
35-6
35-6
35-6
35-7
35-7
35-7

xxi

35.4.4
35.4.5
35.4.6
35.4.7

Setting Credentials for UMS, iOS and Android ........................................................... 35-9
Creating a Java KeyStore for iOS Access Request (Push) Notifications ................. 35-10
Configuring Host Name Verifier for Android Access Request (Push) Notifications........
35-11
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
37.2
37.3
37.4
37.4.1
37.4.2
37.4.3
37.4.4
37.4.5
37.4.6
xxii

Integrating Identity Federation with Access Manager.......................................................
Deploying Identity Federation with Oracle Access Management....................................
Understanding How Identity Federation Works ................................................................
Using Identity Federation.......................................................................................................
Achieving SSO...................................................................................................................
Logging Out.......................................................................................................................
Authorizing .......................................................................................................................
Forcing Authentication ....................................................................................................
Indicating a Passive Identity Provider ..........................................................................
User and Assertion Mapping .........................................................................................

37-1
37-2
37-2
37-3
37-4
37-4
37-4
37-4
37-5
37-5

37.4.7
37.5
37.5.1
37.5.2
37.6
37.6.1
37.6.2
37.6.3
37.6.4
37.7
37.8

Platform Dependencies....................................................................................................
Initiating Federation SSO........................................................................................................
IdP Initiated Federation SSO Service .............................................................................
SP Initiated Federation SSO Service...............................................................................
Exchanging Identity Federation Data ...................................................................................
Using SAML 2.0 ................................................................................................................
Using SAML 1.1 ................................................................................................................
Using OpenID 2.0............................................................................................................
Using WS-Federation 1.1 ...............................................................................................
Administrating Identity Federation ....................................................................................
Enabling Identity Federation................................................................................................

37-5
37-5
37-5
37-6
37-6
37-6
37-9
37-11
37-13
37-14
37-15

38 Managing Identity Federation Partners
38.1
38.2
38.3
38.3.1
38.3.2
38.4
38.4.1
38.4.2
38.5
38.5.1
38.5.2
38.6
38.6.1
38.6.2
38.6.3
38.6.4
38.7
38.7.1
38.7.2
38.8
38.9

Understanding Federation And Partners............................................................................. 38-1
Managing Federation Partners .............................................................................................. 38-1
Administering Identity Federation As A Service Provider ............................................... 38-2
Creating Remote Identity Provider Partners ................................................................ 38-2
Managing the Remote Identity Provider Partners....................................................... 38-8
Administering Identity Federation As An Identity Provider.......................................... 38-10
Creating Remote Service Provider Partners ............................................................... 38-10
Managing the Remote Service Provider Partners ...................................................... 38-11
Using Attribute Mapping Profiles....................................................................................... 38-12
Using the SP Attribute Mapping Profile ..................................................................... 38-12
Using the IdP Attribute Mapping Profile.................................................................... 38-14
Mapping Federation Authentication Methods to Access Manager Authentication Schemes.
38-15
Understanding Federation SSO As An IdP................................................................. 38-16
Understanding Federation SSO As An SP .................................................................. 38-17
Configuring an Alternate Authentication Scheme .................................................... 38-17
Using WLST For Mapping Administration ................................................................ 38-18
Using the Attribute Sharing Plug-in for the Attribute Query Service ........................... 38-18
Understanding the Plug-in and Query Service Design............................................. 38-18
Configuring for Attribute Sharing ............................................................................... 38-22
Using the Federation Proxy.................................................................................................. 38-24
Using WLST for Identity Federation Administration ...................................................... 38-25

39 Managing Settings for Identity Federation
39.1
39.2
39.3
39.3.1
39.3.2
39.4
39.4.1
39.4.2
39.5

Prerequisites .............................................................................................................................
Introduction to Federation Settings.......................................................................................
Managing General Federation Settings ................................................................................
About Managing General Federation Settings .............................................................
Managing General Federation Settings .........................................................................
Managing Proxy Settings for Federation..............................................................................
About Proxy Settings for Federation ............................................................................
Managing Proxy Settings for Identity Federation........................................................
Defining Keystore Settings for Federation ...........................................................................

39-1
39-1
39-2
39-2
39-3
39-3
39-3
39-4
39-4

xxiii

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
40.2
40.2.1
40.2.2
40.2.3
40.2.4
40.3
40.3.1
40.3.2
40.3.3
40.4
40.4.1
40.4.2
40.5
40.6
40.6.1
40.6.2
40.6.3
40.6.4
40.7
40.7.1
40.7.2
40.7.3
40.8
40.9
40.9.1
40.9.2
40.9.3

Using Identity Federation and Access Manager Together ................................................ 40-1
Using Authentication Schemes and Modules for Identity Federation 11g Release 2
(11.1.2.2) 40-2
About the FederationScheme Authentication Scheme................................................ 40-2
About the FederationMTScheme.................................................................................... 40-3
About the FederationPlugin Authentication Module ................................................. 40-3
Managing Authentication with Identity Federation in 11g Release 2 ...................... 40-4
Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1 .
40-6
About Scheme OIFScheme ............................................................................................. 40-7
About the OIFMTLDAPPlugin Authentication Module ............................................ 40-8
Managing Authentication with Oracle Identity Federation Release 11gR1............. 40-8
Managing Access Manager Policies for Use with Identity Federation ............................ 40-9
About Policy Responses with Assertion Attributes for Identity Federation ........... 40-9
Defining Policy Responses with Assertion Attributes for Identity Federation ..... 40-10
Testing Identity Federation Configuration ........................................................................ 40-12
Using the Default Identity Provisioning Plug-in .............................................................. 40-14
Why Use a Provisioning Plug-in? ................................................................................ 40-14
About the Default Provisioning Plug-in...................................................................... 40-14
Using the Default Provisioning Plug-in ...................................................................... 40-14
Switching to a Custom Provisioning Plug-in ............................................................. 40-15
Configuring the Identity Provider Discovery Service ...................................................... 40-15
Using the Bundled IdP Discovery Service .................................................................. 40-15
Creating a custom IdP Discovery Service ................................................................... 40-16
Disabling the use of an IdP Discovery Service ........................................................... 40-18
Configuring the Federation User Self-Registration Module............................................ 40-18
Integrating OAM Identity Provider With Microsoft Office 365 Service Provider ....... 40-20
Configuring Microsoft Office 365 for OAM Integration ........................................... 40-21
Configuring OAM for Microsoft Office 365 Integration ........................................... 40-22
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
41.2
41.3
41.4
41.5
41.6
41.7
41.7.1
xxiv

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 ........................................................................................
Centralized Token Authority Deployment...................................................................

41-1
41-2
41-3
41-6
41-8
41-8
41-9
41-9

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
Prerequisites ............................................................................................................................. 42-1
Typical Token Ecosystem ....................................................................................................... 42-1
Scenario: Identity Propagation with the Access Manager Token ..................................... 42-2
Component Processing: Identity Propagation with the OAM Token....................... 42-4
Request Security Token Attributes and Run Time Processing .................................. 42-5
Configuration Requirements: Identity Propagation with the OAM Token............. 42-7
Testing Your Implementation ....................................................................................... 42-15
Scenario: Web Service Security With On Behalf Of Username Token .......................... 42-16
Component interactions for Identity Propagation with Username Token ............ 42-16
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

42.1
42.2
42.3
42.3.1
42.3.2
42.3.3
42.3.4
42.4
42.4.1
42.4.2

43 Configuring Security Token Service Settings
Prerequisites ............................................................................................................................ 43-1
Introduction to Security Token Service Configuration ...................................................... 43-1
Post-Installation Configuration ...................................................................................... 43-2
About OAM Servers and Security Token Service........................................................ 43-3
About Security Token Service Clients ........................................................................... 43-4
About Agents and Security Token Service ................................................................... 43-4
About Security Token Service End Points and Policies .............................................. 43-5
Enabling and Disabling Security Token Service ................................................................. 43-7
About Security Token Service and the Oracle Access Management Console ......... 43-8
About Enabling Services for Security Token Service ................................................. 43-9
Enabling and Disabling Services for Security Token Service..................................... 43-9
Defining Security Token Service Settings............................................................................. 43-9
About Security Token Service Settings.......................................................................... 43-9
Managing Security Token Service Settings................................................................. 43-12
Using and Managing WSS Policies for Oracle WSM Agents .......................................... 43-12
Using and Modifying Oracle Workspace Studio Policies......................................... 43-13
Managing WSS Policies for Security Token Service: Classpath............................... 43-13
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

43.1
43.2
43.2.1
43.2.2
43.2.3
43.2.4
43.2.5
43.3
43.3.1
43.3.2
43.3.3
43.4
43.4.1
43.4.2
43.5
43.5.1
43.5.2
43.5.3

xxv

43.6.2
Retrieving the Oracle WSM Keystore Password........................................................
43.6.3
Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate .......
43.6.4
Adding Trusted Certificates to the Oracle WSM Keystore.......................................
43.6.5
Validating Trusted Certificates in the Oracle WSM Keystore..................................
43.6.6
Configuring Oracle WSM Agent for WSS Kerberos Policies ...................................
43.7
Managing and Migrating Security Token Service Policies ..............................................
43.7.1
About Managing and Migrating Security Token Service Policies...........................
43.7.2
Managing Security Token Service Policies .................................................................
43.7.3
Migrating Security Token Service Policies..................................................................
43.8
Logging Security Token Service Messages ........................................................................
43.9
Auditing the Security Token Service .................................................................................
43.9.1
About Security Token Service Audit Record Storage ...............................................
43.9.2
About Audit Reports and Oracle Business Intelligence Publisher..........................
43.9.3
About the Audit Log ......................................................................................................
43.9.4
About Auditing Security Token Service Events.........................................................

43-16
43-16
43-17
43-17
43-18
43-19
43-19
43-19
43-19
43-20
43-21
43-21
43-22
43-22
43-22

44 Managing Security Token Service Certificates and Keys
44.1
Prerequisites .............................................................................................................................
44.2
Introducing the Security Token Service Certificates and Keys .........................................
44.2.1
About Keystores and Security Token Service...............................................................
44.2.2
About the Oracle Web Services Manager Keystore (default-keystore.jks) ..............
44.2.3
About Using the OPSS Keystore for Requester Certificates.......................................
44.3
Managing Security Token Service Encryption/Signing Keys...........................................
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.3.3
Extracting an Security Token Service Certificate .........................................................
44.4
Managing Partner Keys for WS-Trust Communications ...................................................
44.4.1
About Partner Certificates ...............................................................................................
44.4.2
About Downloading the Relying Party's Certificate at Run Time ............................
44.4.3
Setting the Partner's Signing or Encryption Certificate ..............................................
44.5
Managing Certificate Validation ...........................................................................................
44.5.1
Managing the Trust Anchors Store (amtruststore) ......................................................
44.5.2
Managing Certificate Revocation Lists........................................................................
44.5.3
Using a Custom Trust Anchor Store for Security Token Service.............................

44-1
44-1
44-2
44-3
44-3
44-4

44-5
44-6
44-7
44-7
44-8
44-8
44-9
44-9
44-10
44-10

45 Managing Templates, Endpoints, and Policies
45.1
45.2
45.2.1
45.2.2
45.3
45.3.1
45.3.2
45.4
45.4.1
45.4.2
xxvi

Introduction ..............................................................................................................................
Searching for an Existing Template.......................................................................................
About Template Search Controls ..................................................................................
Searching For a Template ................................................................................................
Managing Token Issuance Templates...................................................................................
About Managing Token Issuance Templates ...............................................................
Managing a Token Issuance Template ........................................................................
Managing Token Validation Templates .............................................................................
About Managing Token Validation Templates..........................................................
Managing Token Validation Templates ......................................................................

45-1
45-2
45-3
45-4
45-5
45-5
45-12
45-13
45-13
45-23

45.5
45.5.1
45.5.2
45.6
45.6.1
45.6.2
45.6.3
45.7
45.7.1
45.7.2
45.8
45.8.1
45.8.2
45.8.3
45.9
45.9.1
45.9.2
45.9.3
45.9.4
45.9.5
45.9.6

Managing Security Token Service Endpoints....................................................................
About Managing Endpoints..........................................................................................
Managing EndPoints ......................................................................................................
Managing Token Issuance Policies, Conditions, and Rules ............................................
About Token Issuance Policies .....................................................................................
About Managing Token Issuance Conditions and Rules .........................................
Managing Token Issuance Policies and Conditions ..................................................
Managing TokenServiceRP Type Resources .....................................................................
About Managing TokenServiceRP Type Resources in Access Manager ................
Managing TokenServiceRP Type Resources in Application Domains ...................
Making Custom Classes Available......................................................................................
About Making Classes Available .................................................................................
About Narrowing a Search for Custom Tokens.........................................................
Managing Custom Tokens ...........................................................................................
Managing a Custom Security Token Service Configuration ...........................................
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-25
45-25
45-26
45-27
45-27
45-27
45-29
45-30
45-32
45-32
45-33
45-33
45-35
45-37
45-38
45-38
45-40
45-42
45-42
45-43
45-44

46 Managing Token Service Partners and Partner Profiles
46.1
46.2
46.2.1
46.2.2
46.3
46.3.1
46.3.2
46.3.3
46.4
46.4.1
46.4.2
46.4.3

Prerequisites .............................................................................................................................
Introduction Token Service Partners and Partner Profiles ................................................
About Token Service Partners ........................................................................................
About Partner Profiles .....................................................................................................
Managing Token Service Partners.........................................................................................
About Managing Token Service Partners .....................................................................
Managing a Token Service Partner ................................................................................
Refining Partner Searches ...............................................................................................
Managing Token Service Partner Profiles ............................................................................
About Managing Partner Profiles ..................................................................................
Managing a Token Service Partner Profile..................................................................
Refining a Profile Search................................................................................................

46-1
46-1
46-1
46-2
46-3
46-3
46-5
46-6
46-7
46-7
46-18
46-19

47 Troubleshooting Security Token Service
47.1
47.2
47.3

Authorization Issues................................................................................................................ 47-1
Endpoint Issues ........................................................................................................................ 47-2
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

xxvii

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
49.2
49.2.1
49.2.2
49.2.3
49.2.4
49.2.5
49.3
49.3.1
49.3.2
49.3.3
49.4
49.4.1

xxviii

Opening the Mobile and Social Services Configuration Page...........................................
Understanding Mobile and Social Services Configuration................................................
Understanding Service Providers ..................................................................................
Understanding Service Profiles ......................................................................................
Understanding Security Handler Plug-ins ...................................................................
Understanding Application Profiles ..............................................................................
Understanding Service Domains....................................................................................
Defining Service Providers .....................................................................................................
Defining, Modifying or Deleting an Authentication Service Provider.....................
Defining, Modifying or Deleting an Authorization Service Provider ....................
Defining, Modifying or Deleting a User Profile Service Provider...........................
Defining Service Profiles.......................................................................................................
Defining, Modifying and Deleting an Authentication Service Profile....................

49-1
49-2
49-2
49-3
49-3
49-4
49-4
49-4
49-5
49-17
49-18
49-22
49-22

49.4.2
49.4.3
49.5
49.5.1
49.5.2
49.5.3
49.6
49.6.1
49.6.2
49.7
49.7.1
49.7.2
49.8
49.8.1
49.8.2
49.9
49.9.1
49.9.2

Defining, Modifying and Deleting an Authorization Service Profile .....................
Defining, Modifying and Deleting a User Profile Service Profile ...........................
Defining Security Handler Plug-ins ....................................................................................
Creating a Security Handler Plug-in............................................................................
Editing or Deleting a Security Handler Plug-in .........................................................
Device Fingerprinting and Device Profile Attributes................................................
Defining Application Profiles ..............................................................................................
Creating an Application Profile....................................................................................
Editing or Deleting an Application Profile .................................................................
Defining Service Domains ....................................................................................................
Creating a Service Domain............................................................................................
Editing or Deleting a Service Domain .........................................................................
Using the Jailbreak Detection Policy ...................................................................................
Adding a New Jailbreak Detection Policy ..................................................................
Editing the Jailbreak Detection Policy .........................................................................
Configuring Mobile and Social Services with Other Oracle Products ...........................
Configuring Mobile and Social Services for Access Manager..................................
Configuring Mobile and Social Services for Oracle Adaptive Access Manager ...

49-24
49-25
49-26
49-27
49-27
49-27
49-28
49-28
49-29
49-30
49-30
49-34
49-34
49-34
49-35
49-36
49-36
49-41

50 Configuring Social Identity
50.1
50.2
50.2.1
50.2.2
50.2.3
50.3
50.3.1
50.3.2
50.3.3
50.3.4
50.4
50.4.1
50.4.2
50.4.3
50.5
50.5.1
50.5.2
50.6
50.7
50.7.1
50.7.2

Opening the Manage Social Identity Page ...........................................................................
Understanding Social Identity Configuration .....................................................................
Understanding Social Identity Providers......................................................................
Understanding Service Provider Interfaces ..................................................................
Understanding Application Profiles ..............................................................................
Defining 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................................................
Defining Service Provider Interfaces ..................................................................................
Creating a Service Provider Interface ..........................................................................
Editing or Deleting an Service Provider Interface .....................................................
Adding a Custom Service Provider Interface Implementation ...............................
Defining Application Profiles ..............................................................................................
Creating an Application Profile....................................................................................
Editing or Deleting an Application Profile .................................................................
Integrating Social Identity With Mobile Applications .....................................................
Linking Social Identity Provider Accounts ........................................................................
Using Social Identity Provider Account Linking .......................................................
Configuring Social Identity Provider Account Linking............................................

50-1
50-2
50-2
50-2
50-2
50-3
50-3
50-7
50-8
50-10
50-11
50-12
50-12
50-12
50-13
50-13
50-16
50-16
50-17
50-18
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

xxix

51.3
51.4
51.5
51.6
51.7

Part XII

Deploying Mobile and Social With Oracle Access Manager .............................................
Configuring a Webgate to Support Social Identity.............................................................
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-2
51-4
51-6
51-7
51-7

Managing the Oracle Access Management OAuth Service

52 Understanding OAuth Services
52.1
52.2
52.2.1
52.2.2
52.3
52.4
52.4.1
52.4.2
52.4.3
52.4.4
52.4.5
52.4.6
52.4.7
52.4.8
52.4.9
52.5
52.5.1
52.5.2
52.5.3
52.6
52.7
52.8
52.8.1
52.8.2
52.8.3
52.9

Using Oracle Access Management OAuth Services ...........................................................
Understanding OAuth Services Authorization for Web Clients ......................................
Understanding 3-Legged Authorization.......................................................................
Understanding 2-Legged Authorization.......................................................................
Understanding OAuth Services Authorization for Mobile Clients ..................................
Understanding the OAuth Services 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 .........................................................
Understanding OAuth Services Tokens .............................................................................
Understanding OAuth Services Access Tokens .........................................................
Understanding OAuth Services Refresh Tokens .......................................................
Understanding Mobile OAuth Services Client Tokens.............................................
Understanding the Authorization and Authentication Endpoints ................................
Enforcing Access Control......................................................................................................
Understanding Mobile OAuth Services Server-Side Single Sign-on..............................
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.....
Understanding OAuth Services Plug-ins ...........................................................................

52-1
52-2
52-3
52-4
52-5
52-10
52-10
52-10
52-11
52-12
52-13
52-17
52-18
52-18
52-18
52-18
52-19
52-20
52-20
52-20
52-21
52-21
52-22
52-22
52-24
52-25

53 Configuring OAuth Services
53.1
Enabling OAuth Services ........................................................................................................
53.2
Configuring OAuth Services Components in an Identity Domain ..................................
53.3
Configuring OAuth Services Settings ...................................................................................
53.3.1
Configuring Identity Domains ......................................................................................
53.3.2
Configuring Service Profiles ..........................................................................................
53.3.3
Configuring Clients ........................................................................................................
53.3.4
Configuring the Service Provider.................................................................................
53.3.5
Configuring Custom Resource Servers .......................................................................
53.3.6
Configuring User Profile Services ...............................................................................

xxx

53-1
53-2
53-3
53-4
53-6
53-12
53-18
53-20
53-22

53.3.7
Configuring Consent Management Services ..............................................................
53.3.8
Configuring Plug-Ins......................................................................................................
53.3.9
Configuring Server Settings ..........................................................................................
53.3.10
Configuring the Jailbreak Detection Policy ................................................................
53.3.11
Configuring Token Life Cycle Management ..............................................................
53.4
Configuring OAuth Services for Third-Party JWT Bearer Assertions ...........................
53.4.1
Understanding the Default Service Profile Keystore ................................................
53.4.2
Creating a Non-Default Keystore for a Service Profile .............................................
53.4.3
Configuring a Third-Party JWT Trust Issuer..............................................................
53.5
Configuring a WebGate to Protect OAuth Services..........................................................
53.6
Configuring OAM Session Synchronization......................................................................
53.7
Configuring Mobile OAuth for SSO Servlet Authentication...........................................
53.7.1
Configuring OAM and Your App to use the Mobile SSO Servlet...........................
53.7.2
Configuring the MobileSSOServlet Authentication Scheme....................................
53.8
Configuring the Mobile Security Manager Plug-in ..........................................................

53-25
53-27
53-28
53-29
53-30
53-31
53-31
53-32
53-36
53-37
53-39
53-40
53-40
53-41
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

xxxi

54.7.2
Required Environment-Specific Configuration Data ................................................
54.7.3
Customizing an Application Configuration Package to the Target Environment
54.7.4
Generating the Customized Application Configuration Package...........................
54.7.5
Deploying the Customized Application Configuration Package ............................
54.8
Managing Password Generation Policies...........................................................................
54.8.1
Searching for Password Generation Policies ..............................................................
54.8.2
Creating Password Generation Policies ......................................................................
54.8.3
Managing Policy Subscribers ........................................................................................
54.9
Managing Credential Sharing Groups................................................................................
54.9.1
Searching for Credential Sharing Groups ...................................................................
54.9.2
Creating Credential Sharing Groups ...........................................................................
54.9.3
Managing Applications in Credential Sharing Groups ............................................
54.10 Managing Global Agent Settings.........................................................................................
54.10.1
Searching for Sets of Global Agent Settings................................................................
54.10.2
Importing an INI File with a Global Agent Settings Configuration........................
54.10.3
Creating a Set of Global Agent Settings ......................................................................

54-48
54-48
54-50
54-50
54-51
54-51
54-52
54-54
54-55
54-56
54-56
54-58
54-59
54-60
54-60
54-60

Part XIV Using Identity Context
55 Using Identity Context
55.1
55.2
55.3
55.3.1
55.3.2
55.4
55.5
55.5.1
55.5.2
55.5.3
55.5.4
55.5.5
55.5.6
55.5.7
55.6

Part XV

Introducing Identity Context .................................................................................................
Understanding Identity Context............................................................................................
Working With the Identity Context Service.........................................................................
Using the Identity Context Dictionary ..........................................................................
Understanding Identity Context Runtime ....................................................................
Using the Identity Context API..............................................................................................
Configuring the Identity Context Service Components...................................................
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 ...................................
Validating Identity Context..................................................................................................

55-1
55-3
55-4
55-4
55-7
55-9
55-11
55-11
55-12
55-13
55-15
55-15
55-16
55-17
55-18

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.2
Components Required for SecurID Authentication ...........................................................
56.2.1
Supported Versions and Platforms ................................................................................
56.2.2
Required RSA Components ............................................................................................
56.2.3
Installation and Configuration Requirements..............................................................
56.3
SecurID Authentication Modes..............................................................................................
56.3.1
Standard SecurID Authentication ..................................................................................

xxxii

56-1
56-3
56-3
56-3
56-4
56-5
56-5

56.3.2
SecurID Next Tokencode Authentication .....................................................................
56.3.3
SecurID New PIN Authentication..................................................................................
56.4
Configuring Access Manager for RSA SecurID Authentication .......................................
56.5
Running a Custom RSA Plug-in ..........................................................................................

56-6
56-6
56-6
56-10

57 Configuring Access Manager for Windows Native Authentication
57.1
Introducing Access Manager with Windows Native Authentication..............................
57.1.1
Understanding Access Manager WNA Login and Fall Back Authentication .........
57.1.2
Understanding Supported Kerberos Authentication Modules .................................
57.2
Preparing Your Active Directory/Kerberos Topology ......................................................
57.3
Confirming Access Manager Operations ...........................................................................
57.4
Enabling the Browser to Return Kerberos Tokens ...........................................................
57.4.1
Enabling Kerberos Tokens in Internet Explorer.........................................................
57.4.2
Enabling Kerberos Tokens in Mozilla Firefox ............................................................
57.5
Integrating KerberosPlugin with Oracle Virtual Directory .............................................
57.5.1
Preparing Oracle Virtual Directory for Integration ...................................................
57.5.2
Registering Oracle Virtual Directory as the Default Store for WNA ......................
57.5.3
Setting Up Authentication with Access Manager KerberosPlugin and OVD .......
57.6
Integrating the KerberosPlugin with Search Failover ......................................................
57.6.1
Registering Microsoft Active Directory Instances with Access Manager ..............
57.6.2
Setting Up the KerberosPlugin for ADGCs ................................................................
57.7
Configuring Access Manager for Windows Native Authentication ..............................
57.7.1
Creating the Authentication Scheme for Windows Native Authentication ..........
57.7.2
Configuring Policies for Windows Native Authentication ......................................
57.7.3
Configuring WNA for NTLM Fallback .......................................................................
57.7.4
Verifying the Access Manager Configuration File.....................................................
57.8
Validating WNA with Access Manager Protected Resources ........................................
57.9
Configuring WNA For Use With DCC ...............................................................................
57.9.1
Initializing the Kerberos Protocol.................................................................................
57.9.2
Configuring Access Manager........................................................................................
57.10 Troubleshooting WNA Configuration................................................................................
57.10.1
Kinit Fails .........................................................................................................................
57.10.2
"An Incorrect Username or Password was Specified" Is Displayed ......................
57.10.3
User Identity Store is Not Registered Correctly.........................................................
57.10.4
Two BASIC Authentication Prompts Are Displayed ................................................

57-1
57-2
57-4
57-5
57-10
57-10
57-10
57-11
57-11
57-11
57-12
57-13
57-14
57-15
57-15
57-17
57-18
57-18
57-19
57-19
57-20
57-20
57-21
57-22
57-23
57-23
57-23
57-24
57-24

58 Integrating JBoss with Access Manager
58.1
Overview of JBoss Integration with Access Manager ........................................................
58.1.1
Understanding the Configuration of and Processing by the JBoss Agent ...............
58.1.2
Understanding the Configuration of and Processing by the Login Module ...........
58.1.3
Understanding the Login Module Process in usernamePassword Mode................
58.1.4
Understanding the Login Module Process in tokenBased Mode ..............................
58.2
Understanding the Integration Topology ...........................................................................
58.2.1
Topology: Access Manager with JBoss Agent .............................................................
58.2.2
Topology: JBoss Agent Behind Web Server Configured with WebGate ..................
58.2.3
Sample Integration Topology .........................................................................................

58-1
58-2
58-3
58-4
58-5
58-5
58-5
58-6
58-6

xxxiii

58.3
58.4
58.5
58.5.1
58.5.2
58.6
58.6.1
58.6.2
58.6.3
58.6.4
58.7
58.8
58.8.1
58.8.2
58.9
58.9.1
58.9.2
58.10
58.11

Preparing Your Environment for JBoss 6.x Integration .....................................................
Preparing Your Environment for JBoss 5.x Integration .....................................................
Protecting JBoss-Specific Resources ....................................................................................
Registering the JBoss Agent with Automatic Policy Creation .................................
Creating a Custom Policy for JBoss Resource Protection .........................................
Protecting Web Applications with the JBoss Agent..........................................................
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..................
Configuring JBoss Server to Access a Host Name (not localhost) ..................................
Configuring the Login Module to Secure EJBs..................................................................
Configuring the Server to Secure EJBs ........................................................................
Configuring the Client Side for Login Module to Secure EJBs ................................
Configuring the Login Module to Secure Web Service Access .......................................
Configuring the Server to Secure Web Services Access ............................................
Configuring the Client to Secure Web Services Access.............................................
Configuring Logging for the JBoss Agent and Login Module ........................................
Validating Your Configuration ............................................................................................

58-7
58-9
58-10
58-10
58-12
58-13
58-13
58-14
58-15
58-15
58-16
58-16
58-17
58-18
58-19
58-19
58-21
58-21
58-21

59 Integrating Microsoft SharePoint Server with Access Manager
59.1
What is Supported in This Release? ......................................................................................
59.2
Introduction to Integrating With the SharePoint Server ...................................................
59.2.1
About Windows Impersonation .....................................................................................
59.2.2
About Form Based Authentication With This Integration .........................................
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.3
Integration Requirements .......................................................................................................
59.3.1
Confirming Requirements ...............................................................................................
59.3.2
Required Access Manager Components .......................................................................
59.3.3
Required Microsoft Components ...................................................................................
59.4
Preparing for Integration With SharePoint Server..............................................................
59.5
Integrating With Microsoft SharePoint Server ..................................................................
59.5.1
Creating a New Web Application in Microsoft SharePoint Server .........................
59.5.2
Creating a New Site Collection for Microsoft SharePoint Server ............................
59.6
Setting Up Microsoft Windows Impersonation ...............................................................
59.6.1
Creating Trusted User Accounts ..................................................................................
59.6.2
Assigning Rights to the Trusted User..........................................................................
59.6.3
Binding the Trusted User to Your WebGate...............................................................
59.6.4
Adding an Impersonation Response to an Authorization Policy............................
59.6.5
Adding an Impersonation DLL to IIS ..........................................................................
59.6.6
Testing Impersonation ...................................................................................................
59.7
Completing the SharePoint Server Integration..................................................................
59.7.1
Configuring IIS Security ................................................................................................
59.8
Integrating With Microsoft SharePoint Server Configured With LDAP Membership
Provider 59-23

xxxiv

59-1
59-2
59-3
59-3

59-5
59-6
59-6
59-6
59-7
59-8
59-10
59-11
59-13
59-14
59-15
59-15
59-16
59-17
59-18
59-20
59-22
59-23

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
59.8.1

60

Integrating Access Manager with Outlook Web Application
60.1
60.2
60.2.1
60.2.2
60.2.3
60.2.4
60.3
60.3.1
60.3.2
60.3.3
60.3.4
60.3.5
60.3.6
60.3.7
60.4
60.4.1
60.4.2

What is New in This Release? ................................................................................................
Introduction to Integration with Outlook Web Application .............................................
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...................................................................................
Enabling Impersonation With a Header Variable...............................................................
Requirements for Impersonation with a Header Variable .........................................
Creating an Impersonator as a Trusted User................................................................
Assigning Rights to the Trusted User............................................................................
Binding the Trusted User to Your WebGate.................................................................
Adding an Impersonation Response to An Application Domain .............................
Adding an Impersonation DLL to IIS ............................................................................
Testing Impersonation .....................................................................................................
Setting Up Impersonation for Outlook Web Application (OWA)..................................
Prerequisites to Setting Impersonation for Outlook Web Application...................
Creating a Trusted User Account for Outlook Web Application ............................

60-1
60-1
60-2
60-2
60-2
60-3
60-3
60-3
60-4
60-5
60-6
60-6
60-7
60-8
60-10
60-10
60-11

xxxv

Assigning Rights to the Outlook Web Application Trusted User ...........................
Binding the Trusted Outlook Web Application User to Your WebGate ................
Adding an Impersonation Action to an Application Domain for Outlook Web
Application 60-12
60.4.6
Adding an Impersonation dll to IIS .............................................................................
60.4.7
Configuring IIS Security ................................................................................................
60.4.8
Testing Impersonation for Outlook Web Application ..............................................
60.5
Setting Up Access Manager WNA for Outlook Web Application .................................
60.4.3
60.4.4
60.4.5

60-11
60-11

60-13
60-13
60-14
60-15

61 Integrating Microsoft Forefront Threat Management Gateway 2010 with
Access Manager
61.1
61.2
61.2.1
61.2.2
61.3
61.3.1
61.3.2
61.3.3
61.4
61.4.1
61.4.2
61.5
61.5.1
61.5.2
61.5.3
61.6
61.7
61.8

What is New in This Release? ................................................................................................
Introduction to Integration with TMG Server 2010 ............................................................
About This Integration.....................................................................................................
About Confirming Certification Requirements............................................................
Creating a Forefront TMG Policy and Rules........................................................................
Creating a Custom Policy for Forefront TMG ..............................................................
Creating a Forefront TMG Firewall Policy Rule ..........................................................
Verifying Forefront TMG Proxy Configuration ...........................................................
Installing and Configuring 10g Webgate for Forefront TMG Server ..............................
Installing 10g Webgate with TMG Server .....................................................................
Changing /access Directory Permissions ....................................................................
Configuring the TMG 2010 Server for the ISAPI 10g Webgate.........................................
Registering Access Manager Plug-ins as TMG Server Web Filters ...........................
Ordering the ISAPI Filters ...............................................................................................
Verifying Form-based Authentication...........................................................................
Starting, Stopping, and Restarting the TMG Server ..........................................................
Removing Access Manager Filters Before WebGate Uninstall on TMG Server .............
Troubleshooting .......................................................................................................................

61-1
61-1
61-1
61-2
61-2
61-2
61-3
61-5
61-6
61-6
61-6
61-7
61-7
61-7
61-8
61-8
61-9
61-9

62 Integrating Access Manager with SAP NetWeaver Enterprise Portal
62.1
62.2
62.3
62.3.1
62.4
62.4.1
62.4.2
62.4.3
62.4.4
62.4.5
62.5
62.5.1
62.5.2
62.5.3
62.5.4
62.5.5
xxxvi

What is Supported in This Release? ......................................................................................
Supported Versions and Platforms .......................................................................................
Integration Architecture..........................................................................................................
Process Overview: Integration with SAP NetWeaver Enterprise Portal..................
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.0.x........
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 ...........................................
Configuring Oracle Access Management and NetWeaver Enterprise Portal 7.4.x........
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-1
62-1
62-2
62-2
62-3
62-3
62-4
62-5
62-6
62-7
62-8
62-8
62-8
62-10
62-11
62-13

62.6
62.7

Testing the Integration .......................................................................................................... 62-13
Troubleshooting the Integration .......................................................................................... 62-14

63 Integrating Oracle Access Manager with SAP NetWeaver Enterprise Portal
Using OpenSSO Policy Agent 2.2
63.1
63.2
63.3
63.3.1
63.4
63.5
63.6
63.7
63.8
63.9
63.10
63.11
63.12
63.13

What is Supported in This Release? ......................................................................................
Registering the OpenSSO Agent............................................................................................
Installing the OpenSSO Policy Agent 2.2 on SAP Enterprise Portal ................................
Post-Installation Steps ......................................................................................................
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
63-2
63-3
63-3
63-4
63-4
63-5
63-5
63-5
63-6
63-6
63-6
63-7
63-7

Part XVI Appendixes
A Integrating Oracle ADF Applications with Access Manager SSO
A.1
A.1.1
A.1.2
A.2
A.2.1
A.2.2
A.3
A.3.1
A.3.2
A.4

Introducing Oracle Platform Security Services and Oracle Application Developer
Framework A-1
Oracle Platform Security Services Single Sign-on Framework .................................... A-1
Oracle Application Developer Framework..................................................................... A-2
Integrating Access Manager With Web Applications Using Oracle ADF Security and the
OPSS SSO Framework A-3
Sample SSO Configuration for Access Manager............................................................ A-4
SSO Provider Configuration Details ................................................................................ A-6
Configuring Centralized Logout for Oracle ADF-Coded Applications ............................ A-7
About Centralized Logout Processing for Applications Coded to Oracle ADF
Standards A-7
Configuring Centralized Logout for ADF-Coded Applications with Access Manager....
A-8
Confirming Application-Driven Authentication During Runtime .................................. A-10

B Internationalization and Multibyte Data Support for 10g WebGates
B.1
B.1.1
B.1.2
B.1.3

Introduction to Internationalization and Multibyte Data Support ....................................
Languages For Localized Messages ................................................................................
Bi-directional Language Support .....................................................................................
UTF-8 Encoding ..................................................................................................................

B-1
B-1
B-3
B-3

C Securing Communication
C.1

Prerequisites ............................................................................................................................... C-1

xxxvii

C.2
C.2.1
C.2.2
C.2.3
C.3
C.4
C.4.1
C.4.2
C.4.3
C.4.4
C.4.5
C.4.6
C.4.7
C.5
C.5.1
C.5.2
C.5.3
C.5.4

Securing Communication Between OAM Servers and WebGates ..................................... C-1
About Certificates, Authorities, and Encryption Keys.................................................. C-3
About Security Modes and X509Scheme Authentication ............................................ C-4
About the Importcert Tool................................................................................................. C-4
Generating Client Keystores for OAM Tester in Cert Mode ............................................... C-5
Configuring Cert Mode Communication for Access Manager ........................................... C-6
About Cert Mode Encryption and Files .......................................................................... C-6
Generating a Certificate Request and Private Key for OAM Server ........................... C-7
Retrieving the OAM Keystore Alias and Password ..................................................... C-7
Importing the Trusted, Signed Certificate Chain Into the Keystore ........................... C-8
Adding Certificate Details to Access Manager Settings.............................................. C-10
Generating a Private Key and Certificate Request for WebGates ............................. C-11
Updating WebGate to Use Certificates.......................................................................... C-12
Configuring Simple Mode Communication with Access Manager ................................. C-13
About Simple Mode, Encryption, and Keys ................................................................. C-14
Retrieving the Global Passphrase for Simple Mode .................................................... C-14
Updating WebGate Registration for Simple Mode...................................................... C-15
Verifying Simple Mode Configuration.......................................................................... C-16

D Reviewing Bundled, Generated, and Migrated Artifacts
D.1
D.1.1
D.1.2
D.1.3
D.1.4
D.1.5
D.2
D.2.1
D.2.2
D.2.3
D.2.4
D.2.5
D.2.6
D.3
D.3.1
D.3.2
D.3.3
D.3.4
D.3.5
D.3.6
D.3.7
D.3.8

Bundled 10g IAMSuiteAgent Artifacts................................................................................... D-1
Pre-Registered 10g IAMSuiteAgent ................................................................................ D-1
IAMSuiteAgent Security Provider Settings, WebLogic Administration Console..... D-2
IAMSuiteAgent Registration............................................................................................. D-2
Resources Protected by IAMSuiteAgent ......................................................................... D-4
Pre-seeded IAM Suite Application Domain and Policies ............................................. D-5
Generated Artifacts: OpenSSO............................................................................................... D-10
Generated OpenSSOAgentAuthPlugin ......................................................................... D-10
Generated Host Identifier: OpenSSOAgent1................................................................ D-11
Generated Application Domain: OpenSSOAgent1 ..................................................... D-11
Generated Resources: OpenSSOAgent1 ........................................................................ D-12
Generated Authentication Policy: OpenSSOAgent Application Domain ................ D-12
Generated Authorization Policy: OpenSSOAgent Application Domain ................. D-13
Migrated Artifacts: OpenSSO................................................................................................. D-13
Migrated User Identity Store: OpenSSOAgent1 .......................................................... D-14
Migrated Agents: OpenSSOAgent1 ............................................................................... D-15
Migrated Authentication Module: OpenSSOAgent1 .................................................. D-16
Migrated Host Identifier: OpenSSOAgent1.................................................................. D-16
Migrated Application Domain: OpenSSOAgent1........................................................ D-16
Migrated Resources: OpenSSOAgent1 .......................................................................... D-17
Migrated Authentication Policy: OpenSSOAgent1 ..................................................... D-17
Migrated Authorization Policy: OpenSSOAgent1....................................................... D-18

E Troubleshooting
E.1
E.1.1
E.1.2
xxxviii

Introduction to Oracle Access Management Troubleshooting ........................................... E-2
About System Analysis and Problem Scenarios ............................................................ E-2
About LDAP Server or Identity Store Issues .................................................................. E-3

E.1.3
E.1.4
E.1.5
E.1.6
E.1.7
E.2
E.3
E.4
E.5
E.6
E.7
E.8
E.9
E.9.1
E.9.2
E.9.3
E.9.4
E.10
E.10.1
E.10.2
E.10.3
E.11
E.12
E.12.1
E.13
E.14
E.15
E.15.1
E.15.2
E.15.3
E.16
E.16.1
E.16.2
E.17
E.17.1
E.17.2
E.17.3
E.18
E.19
E.20
E.20.1
E.20.2
E.20.3
E.20.4
E.20.5
E.21

About OAM Server or Host Issues................................................................................... E-4
About Agent-Side Configuration and Load Issues........................................................ E-4
About Runtime Database (Audit or Session Data) Issues ............................................ E-5
About Change Propagation or Activation Issues .......................................................... E-5
About Policy Store Database Issues ................................................................................. E-6
Using My Oracle Support for Additional Troubleshooting Information .......................... E-6
Administrator Lockout.............................................................................................................. E-6
Error During Federation Configuration After Upgrade from PS1 to PS2 ......................... E-7
Oracle Access Management Console Inconsistent State ...................................................... E-7
AdminServer Won't Start if the Wrong Java Path Given with WebLogic Server Installation
E-8
Agent Naming Not Unique ...................................................................................................... E-8
Application URL Requirements............................................................................................... E-8
Authentication Issues ................................................................................................................ E-9
Anonymous Authentication Issues.................................................................................. E-9
X.509Scheme and SSL Handshake Issues........................................................................ E-9
X.509 Protected Resource and Single Sign Off ............................................................. E-10
X509CredentialExtractor Certificate Validation Error ................................................ E-11
Authorization Issues................................................................................................................ E-11
Authorization Condition Error ....................................................................................... E-11
LDAP Search Filter Test Results ..................................................................................... E-11
Authorization Header Response Names....................................................................... E-12
Cannot Access Authentication LDAP or Database............................................................. E-12
Cannot Find Configuration .................................................................................................... E-12
Configuration Does Not Exist ........................................................................................ E-12
Co-existence Between OSSO and Access Manager............................................................. E-13
Could Not Find Partial Trigger.............................................................................................. E-13
Denial of Service Attacks ........................................................................................................ E-13
Protecting the OAM Server from Crashing Under Load............................................ E-14
Compensating for Network Latency ............................................................................ E-15
Protecting OAM Servers from a Flood of HTTP Requests ......................................... E-15
Deployments with Freshly Installed 10g Webgates............................................................ E-15
Authentication Issues with 10g Webgates .................................................................... E-16
Logout Issues with 10g Webgates .................................................................................. E-16
Diagnosing Initialization and Performance Issues ............................................................. E-16
Diagnosing an Initialization Issue.................................................................................. E-16
Diagnosing a Performance Issue .................................................................................... E-17
Diagnosing Out-of-Memory Issues With a Heap Dump ............................................ E-17
Disabling Windows Challenge/Response Authentication on IIS Web Servers ............. E-18
Changing UserIdentityStore1 Type Can Lock Out Administrators................................. E-18
IIS Web Server Issues .............................................................................................................. E-18
Form Authentication or Pass-Through Not Working ................................................. E-19
IIS and General Web Component Guidelines .............................................................. E-19
Issues with IIS v6 Web Servers ....................................................................................... E-19
Page Cannot Be Displayed Error.................................................................................... E-20
Removing and Reinstalling IIS DLLs............................................................................. E-20
Import and File Upload Limits .............................................................................................. E-21

xxxix

jps Logger Class Instantiation Warning is Logged on Authentication ............................ E-21
Internationalization, Languages, and Translation .............................................................. E-21
Automatically Generated Descriptions Are Not Translated...................................... E-22
Console Looks Messy ...................................................................................................... E-22
Authentication Fails: Users with Non-ASCII Characters ........................................... E-22
Access Tester Does Not Work with Non-ASCII Agent Names ................................. E-22
Locales, Languages, and Oracle Access Management Console Login Page ............ E-22
Login Failure for a Protected Page ........................................................................................ E-23
OAM Metric Persistence Timer IllegalStateException: SafeCluster ................................ E-23
Partial Cluster Failure and Intermittent Login and Logout Failures ............................... E-24
RSA SecurID Issues and Logs ................................................................................................ E-24
Registration Issues ................................................................................................................... E-25
Rowkey does not have any primary key attributes Error.................................................. E-25
SELinux Issues.......................................................................................................................... E-25
Session Issues............................................................................................................................ E-26
Session Impersonation Not Enabled by Default .......................................................... E-26
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
E.22
E.23
E.23.1
E.23.2
E.23.3
E.23.4
E.23.5
E.24
E.25
E.26
E.27
E.28
E.29
E.30
E.31
E.31.1
E.31.2

xl

List of Figures
1–1
1–2
1–3
2–1
2–2
2–3
3–1
3–2
3–3
3–4
3–5
3–6
5–1
5–2
5–3
5–4
5–5
5–6
6–1
8–1
8–2
9–1
11–1
11–2
11–3
11–4
11–5
11–6
11–7
11–8
11–9
11–10
11–11
11–12
11–13
12–1
12–2
12–3
12–4
12–5
12–6
12–7
12–8
12–9
12–10
12–11
12–12
12–13
12–14
12–15
12–16
12–17
12–18
12–19

Oracle Access Management Overview .................................................................................... 1-2
Access Manager 11g Components and Services..................................................................... 1-5
Access Manager 11g Component Distribution....................................................................... 1-5
Oracle Access Management Administrator Launch Pad ...................................................... 2-6
Self Service Launch Pad ............................................................................................................. 2-7
SSO Agent Search Page ........................................................................................................... 2-11
Oracle Access Management Configuration Options ............................................................. 3-2
Available Services ....................................................................................................................... 3-3
Common Settings Page (Collapsed View)............................................................................... 3-5
Common Coherence Settings .................................................................................................... 3-7
Certificate Revocation List Dialog Box .................................................................................... 3-8
OCSP/CDP Settings ................................................................................................................... 3-9
Creating User Identity Store Registration .............................................................................. 5-9
System Store Registration ...................................................................................................... 5-12
Identity Directory Service Console Page .............................................................................. 5-16
Create IDS Profile Page ........................................................................................................... 5-18
Create IDS Repository Page ................................................................................................... 5-25
Add System Administrator Roles.......................................................................................... 5-27
OAM Server Registration Page with Proxy Tab Displayed ................................................. 6-5
Audit to Database Architecture ................................................................................................ 8-4
Common Settings: Auditing Configuration......................................................................... 8-23
Log-Level Activation in the Default Log Configuration File ............................................ 9-21
Server Processes Overview Page ........................................................................................... 11-3
OAM Server Metrics: Session Operations Monitoring Page ............................................. 11-4
OAM Server Metrics: Server Operations Tab ...................................................................... 11-5
OAM Server Metrics: WebGates Tab .................................................................................... 11-6
Webgate Metrics: Connectivity Table .................................................................................. 11-7
Webgate Metrics: Operations Overview Table ................................................................... 11-7
Webgate Metrics: Operations Detail Table .......................................................................... 11-7
Webgate Metrics: Detached Information Table .................................................................. 11-8
OSSO Agent Monitoring Page with Operation Details...................................................... 11-8
OSSO Agent Monitoring Process Overview Table ............................................................ 11-9
OSSO Agent Operation Details Table .................................................................................. 11-9
OAM Metrics Table ............................................................................................................... 11-12
Weblogic Metrics.................................................................................................................... 11-12
Fusion Middleware Control (AS-Control) Deployment Architecture ............................ 12-2
OAM Farm Page in Fusion Middleware Control................................................................ 12-4
Farm Navigation Tree in Fusion Middleware Control ...................................................... 12-5
Node Information Page in Fusion Middleware Control .................................................... 12-5
Application Deployment Summary for the Selected Internal Application..................... 12-6
Application Deployment Menu ............................................................................................. 12-6
WebLogic Server Domain Summary with Context Menu Exposed................................. 12-7
Cluster Page ............................................................................................................................. 12-9
Key Metrics for Server Page ................................................................................................ 12-10
Aggregated Access Manager Component Metrics for the Cluster ................................. 12-12
Access Manager Component Metrics for a Single OAM Server Instance ..................... 12-12
Aggregated STS Component Metrics for the Cluster ....................................................... 12-14
STS Component Metrics for an Individual OAM Server Instance ................................. 12-14
Performance Summary Command...................................................................................... 12-15
Performance Summary Page with Metric Palette ............................................................ 12-15
Access Manager Log Levels on the Log Configuration Tab............................................ 12-21
Log Levels for Security Token Service ............................................................................... 12-22
Log Files Configuration Page............................................................................................... 12-25
Typical Log Messages Page in Fusion Middleware Control ........................................... 12-29

xli

12–20
13–1
13–2
13–3
13–4
15–1
15–2
15–3
15–4
15–5
16–1
16–2
17–1
17–2
17–3
17–4
17–5
17–6
17–7
17–8
17–9
17–10
17–11
17–12
19–1
19–2
19–3
19–4
21–1
21–2
21–3
22–1
22–2
22–3
22–4
22–5
22–6
22–7
22–8
22–9
22–10
22–11
22–12
22–13
22–14
22–15
22–16
22–17
22–18
22–19
22–20
22–21
22–22
22–23
22–24

xlii

System MBean Browser and Attributes Tab ......................................................................
Access Manager Settings: Load Balancer .............................................................................
Access Manager Settings: Server Error Mode......................................................................
Access Manager Settings: SSO ...............................................................................................
Common Policy Evaluation Caches ....................................................................................
Create OAM 11g WebGate Page............................................................................................
Load Balanced Deployment .................................................................................................
Expanded 11g WebGate Page with Defaults ....................................................................
WebGate Search Controls and Create Button....................................................................
Key Generation.......................................................................................................................
Global Session Details: Common Settings Page ..................................................................
Common Configuration: Session Management Page.......................................................
Multi-Data Center System Architecture ...............................................................................
Active-Active Deployment Mode..........................................................................................
Active-Active Mode Failover .................................................................................................
Multi-Data Center Deployment .............................................................................................
Requests Served By Different Data Centers.......................................................................
Logout and Session Invalidation .........................................................................................
Stretch Cluster Deployment .................................................................................................
Traditional MDC Deployment .............................................................................................
Active-Active Topology ........................................................................................................
Active-Active Topology Across Multiple Data Centers...................................................
Load Balancing Access Manager Components .................................................................
Global Load Balancer Front Ends Local Load Balancer ...................................................
Replication Flow ......................................................................................................................
EnableMDCReplication Java Property .................................................................................
Starting Sequence Illustrated..................................................................................................
Applying Custom Transformation Rules ...........................................................................
Access Manager 11g Policy Model ......................................................................................
Access Manager Shared Policy Components.......................................................................
Anatomy of Access Manager Policies .................................................................................
Default HTTP Resource Type Definition .............................................................................
Default Resource Type wl_authen ........................................................................................
Default Resource Type TokenServiceRP Resource Type ...................................................
Create Host Identifier Page ..................................................................................................
Native Kerberos Authentication Module ...........................................................................
Native LDAP Authentication Module ................................................................................
Native X.509 Authentication Module .................................................................................
Access Manager Plug-ins for Customized Authentication Modules .............................
Creating Custom Authentication Modules: General .......................................................
Adding a Step and Associating a Plug-in...........................................................................
Plug-in Based Authentication Module Steps and Details ................................................
Steps Orchestration for Plug-in Based Authentication Modules....................................
KerberosPlugin.......................................................................................................................
Default KerberosPlugin Steps and Details .........................................................................
Default KerberosPlugin Steps and Orchestration .............................................................
LDAPPlugin............................................................................................................................
Default LDAPPlugin Steps and Details ..............................................................................
Default Orchestration of Steps for LDAPplugin ...............................................................
X509Plugin ..............................................................................................................................
X509Plugin Default Steps and Details ................................................................................
Default Orchestration for X509Plugin Steps ......................................................................
Password Policy Validation Module Plug-ins ...................................................................
Steps Orchestration: Password Policy Validation Plug-ins .............................................
Plug-ins Page ..........................................................................................................................

12-35
13-2
13-3
13-6
13-10
15-2
15-12
15-15
15-21
15-28
16-9
16-12
17-2
17-6
17-7
17-8
17-12
17-13
17-14
17-14
17-15
17-16
17-17
17-18
19-3
19-4
19-6
19-11
21-7
21-7
21-11
22-4
22-5
22-5
22-14
22-25
22-26
22-27
22-32
22-33
22-34
22-38
22-39
22-40
22-41
22-41
22-42
22-42
22-43
22-43
22-44
22-45
22-45
22-46
22-59

22–25
22–26
23–1
23–2
23–3
23–4
23–5
23–6
23–7
23–8
23–9
23–10
24–1
24–2
24–3
24–4
25–1
25–2
25–3
25–4
25–5
25–6
25–7
25–8
25–9
25–10
25–11
25–12
25–13
25–14
25–15
25–16
25–17
25–18
25–19
25–20
25–21
25–22
25–23
25–24
25–25
25–26
25–27
25–28
25–29
25–30
25–31
25–32
26–1
26–2
26–3
26–4
26–5
26–6
26–7

Plugin Details: Activation Status of Selected Plug-in .......................................................
Default LDAPScheme Page ..................................................................................................
SSO Log-in with Embedded Credential Collector and OAM Agents..............................
Example: Separate Resource WebGate and DCC WebGate Deployment ......................
Combined DCC and WebGate Configuration.....................................................................
SSO Login Processing with OSSO Agents and ECC...........................................................
OAP Tunneling with DCC....................................................................................................
Enable SSL...............................................................................................................................
Keystore Configuration.........................................................................................................
Add Private Key Alias...........................................................................................................
SSL Advanced Options .........................................................................................................
New X509 Scheme..................................................................................................................
Password Policy Configuration Page....................................................................................
Password Policy Validation Authentication Module with Orchestrated Plug-ins ......
Step Orchestration for Password Policy Validation Module...........................................
Server Error Mode for Password Management.................................................................
Application Domains Search Page ........................................................................................
Example Application Domain Summary Page....................................................................
Search Results for Resources in an Application Domain...................................................
Authentication Policies Tab....................................................................................................
Authentication Policy Page: Resources and Responses ....................................................
Authorization Policies Page ...................................................................................................
Individual Authorization Policy Page ..................................................................................
Individual Authorization Policy Resources tab ................................................................
Token Issuance Policies Page ...............................................................................................
Create Resource Page in the Application Domain............................................................
HTTP Resources, Query String Resource URL Controls .................................................
Resource Search within an Application Domain ..............................................................
Sample Authentication Policies Page in the Application Domain .................................
Sample Individual Authentication Policy Page ................................................................
Sample Individual Authorization Policy Page ..................................................................
Individual Authorization Policy Conditions Tab .............................................................
Add Condition Window ......................................................................................................
Condition Containers on the Authorization Policy Page.................................................
Add Identities Window .......................................................................................................
Identity Condition and Details ............................................................................................
Add Search Filter Controls ...................................................................................................
Identity Conditions: Details .................................................................................................
IP4 Range Conditions ............................................................................................................
Temporal Condition Type Details Page .............................................................................
Attribute Conditions Page ....................................................................................................
Add Attribute Condition Dialog ........................................................................................
Authorization Policy Rules Tab: Simple Mode .................................................................
Rules Tab: Expression Rule Mode .......................................................................................
Adding a Resource Prefix for Policy Ordering..................................................................
Authorization Policy Response in the Console .................................................................
Simple Response Samples.....................................................................................................
Complex Response Sample .................................................................................................
OAM Agent (PEP) and OAM Server (PDP) Inter-operability...........................................
User Interactions with the Access Tester..............................................................................
Access Tester Console ...........................................................................................................
Server Connection Panel in the Access Tester ...................................................................
Protected Resource URI Panel in the Access Tester..........................................................
Access Tester User Identity Panel .......................................................................................
Test Case Workflow...............................................................................................................

22-62
22-65
23-4
23-7
23-8
23-9
23-15
23-17
23-17
23-18
23-18
23-22
24-4
24-16
24-16
24-21
25-5
25-6
25-6
25-7
25-8
25-9
25-9
25-10
25-10
25-15
25-25
25-29
25-32
25-32
25-36
25-42
25-44
25-45
25-46
25-47
25-48
25-49
25-53
25-54
25-57
25-57
25-62
25-64
25-67
25-69
25-72
25-73
26-4
26-7
26-13
26-16
26-19
26-21
26-25

xliii

28–1
28–2
28–3
28–4
29–1
29–2
35–1
35–2
35–3
35–4
37–1
38–1
38–2
38–3
38–4
39–1
39–2
40–1
40–2
40–3
40–4
40–5
40–6
40–7
40–8
41–1
41–2
41–3
41–4
41–5
42–1
42–2
42–3
42–4
42–5
42–6
42–7
42–8
42–9
42–10
42–11
42–12
42–13
42–14
43–1
43–2
43–3
45–1
45–2
45–3
45–4
45–5
45–6
45–7
45–8

xliv

Typical Deployment with OpenSSO and Access Manager ...............................................
Create OpenSSO Agent Page ...............................................................................................
Expanded OpenSSO Web Agent Registration Page .........................................................
Expanded OpenSSO J2EE Agent Registration Page .........................................................
Create OSSO Agent Page ........................................................................................................
OSSO Agent Page and Confirmation Window ...................................................................
Second Factor Authentication Preferred Method Page......................................................
One Time Password Login Page............................................................................................
Access Request Notification Preferred Method Page .........................................................
Access Request Notification Wait Screen .............................................................................
Available Services Page.........................................................................................................
New Identity Provider Page, Service Details Loaded from Metadata .............................
New Identity Provider Page, Service Details entered Manually ......................................
Searching for Identity Providers............................................................................................
Attribute Sharing Plug-in Design ........................................................................................
Identity Federation Service Settings Page ............................................................................
Keystore Settings......................................................................................................................
FederationScheme....................................................................................................................
FederationPlugin Steps ...........................................................................................................
FederationPlugin Orchestration ............................................................................................
Setting Up the Authentication Policy with FederationScheme.........................................
OIFScheme ................................................................................................................................
OIFMTLDAPPlugin.................................................................................................................
Authorization Policy Response Tab ....................................................................................
Adding a Federation Response Attribute to an AuthZ Policy ........................................
Security Token Service Architecture .....................................................................................
Security Token Service Token Support.................................................................................
Token Translation at a Centralized Authority.....................................................................
Translating Tokens Behind a Firewall ................................................................................
Web Services SSO...................................................................................................................
Typical Token Ecosystem .......................................................................................................
Identity Propagation with the OAM Token.........................................................................
Process Flow During Identity Propagation..........................................................................
Identity Propagation Deployment.........................................................................................
Identity Propagation Processing ...........................................................................................
Required v1.0 WebLogic Server Identity Assertion Providers .........................................
IAP-Security Token Service Details.....................................................................................
LDAP Provider: IAP-DSEE ..................................................................................................
Default Identity Store Defined in Access Manager...........................................................
Token Issuance Policy for Identity Propagation ..............................................................
/wssuser Endpoint for Identity Assertion .........................................................................
Default Identity Store Defined for Access Manager .........................................................
Token Issuance Policy for Identity Propagation ...............................................................
/wss11user Endpoint for Identity Assertion .....................................................................
Default Endpoints, Policies, and Validation Templates.....................................................
WS-Security 1.0 and 1.1 Policies ............................................................................................
Security Token Service Page.................................................................................................
Validation Templates Search Controls .................................................................................
Issuance Template Search Controls.......................................................................................
Issuance Template: General Details and Defaults...............................................................
Issuance Properties: Username Token Type ........................................................................
Issuance Properties: SAML Token Types .............................................................................
Security Details: SAML Tokens .............................................................................................
New Validation Template page: General Page Defaults..................................................
New Validation Template: General Authentication Details............................................

28-7
28-11
28-13
28-14
29-7
29-9
35-2
35-3
35-5
35-6
37-15
38-3
38-4
38-9
38-19
39-2
39-5
40-2
40-3
40-4
40-6
40-7
40-8
40-10
40-12
41-8
41-8
41-9
41-10
41-11
42-2
42-3
42-3
42-4
42-4
42-9
42-10
42-11
42-12
42-12
42-13
42-19
42-20
42-20
43-5
43-7
43-10
45-3
45-3
45-6
45-6
45-7
45-9
45-14
45-16

45–9
45–10
45–11
45–12
45–13
45–14
45–15
45–16
45–17
45–18
45–19
45–20
45–21
46–1
46–2
46–3
46–4
46–5
46–6
46–7
46–8
46–9
48–1
48–2
48–3
48–4
48–5
48–6
48–7
48–8
48–9
48–10
48–11
48–12
49–1
49–2
49–3
50–1
52–1
52–2
52–3
53–1
53–2
53–3
53–4
54–1
54–2
54–3
54–4
54–5
54–6
54–7
54–8
54–9
55–1

Token Mapping: SAML2 WS-Security Validation Template ..........................................
Token Mapping, username-wstrust-validation-template................................................
Token Mapping: x509-wss-validation-template................................................................
Endpoints Page.......................................................................................................................
Token Issuance Policies and Conditions ............................................................................
Pre-defined Resource Type: TokenServiceRP ...................................................................
Search: Resource Type TokenServiceRP in Application Domain ...................................
New Custom Token Page .....................................................................................................
Custom Tokens Search Page and Controls ........................................................................
General Details: email-wstrust-valid-temp........................................................................
Token Mapping: email-wstrust-valid-temp.......................................................................
General Details: email-issuance-temp ................................................................................
Issuance Properties: email-issuance-temp .........................................................................
New Requester Partner Page..................................................................................................
New Relying Party Partners Page .........................................................................................
Partner Search Controls ..........................................................................................................
Requester Profile: General ......................................................................................................
Requester Profile: Token and Attributes ..............................................................................
Relying Party Profile Token and Attributes.......................................................................
Token and Attributes: Issuing Authority ..........................................................................
Issuing Authority Profile: Token Mapping Tab ................................................................
Search Partner Profiles Page: Requester Profiles...............................................................
First Time Device/Application Registration and Authentication Process....................
Mobile SSO Agent Requests Access Token from Access Manager ................................
Mobile SSO Agent Has Valid Access Token in Credential Store....................................
Mobile SSO Agent Does Not Have Valid Access Token in Credential Store................
User Authentication Using REST ........................................................................................
Authenticating User From Browser-based Web App on Registered Mobile Device...
..................................................................................................................................................
Authenticating a Returning User with a Local Account ..................................................
Authenticating a New User with No Local Account........................................................
Authenticating a User With an OAuth Identity Provider ...............................................
Authenticating a User with Access Manager.....................................................................
Authenticating a User Locally..............................................................................................
Using ODSM to create the PIN attribute in OUD .............................................................
Using ODSM to create the pinperson object class.............................................................
Using the OAM Console to create an IdentityStore..........................................................
Social Identity Account Linking ..........................................................................................
OAuth 3-Legged Flow Diagram ............................................................................................
Using a Split Request to get a Client Verification Code.....................................................
The Complete Mobile App Authorization Request Flow ..................................................
Mobile (top) and Federation (bottom) Identity Domain Screens......................................
Identity Federation DefaultDomain Configuration Page ..................................................
Mobile Security DefaultDomain Configuration Page ........................................................
OAuth Services Service Profile Configuration Page.........................................................
Password Generation Policies Search/Create Tab............................................................
New Password Generation Policy Summary Tab.............................................................
Password Constraints Tab of a Password Generation Policy .........................................
Add Applications Dialog ......................................................................................................
Credential Sharing Groups tab ............................................................................................
New Credential Sharing Group Page .................................................................................
Add Applications Dialog ......................................................................................................
Global Agent Settings Search tab.........................................................................................
New Global Agent Settings Page.........................................................................................
End to End Identity Context Process ....................................................................................

45-18
45-19
45-19
45-25
45-28
45-31
45-32
45-34
45-36
45-39
45-39
45-40
45-41
46-3
46-4
46-7
46-8
46-9
46-10
46-14
46-16
46-20
48-12
48-13
48-14
48-15
48-16
48-17
48-19
48-25
48-27
48-29
48-31
48-32
49-13
49-14
49-15
50-18
52-4
52-6
52-9
53-2
53-3
53-3
53-37
54-51
54-52
54-54
54-55
54-56
54-58
54-59
54-60
54-61
55-3

xlv

55–2
55–3
55–4
58–1
58–2
58–3
59–1
59–2
59–3
59–4
59–5
60–1
60–2
60–3
60–4
C–1
D–1
D–2
D–3
D–4
D–5
D–6
D–7
D–8
D–9
D–10
D–11
D–12
D–13
D–14
D–15
D–16
D–17
D–18
D–19
D–20
D–21
D–22
D–23
D–24

xlvi

End To End Identity Context Process Components ........................................................... 55-3
Identity Context Process Flow ............................................................................................... 55-8
OAM Authentication Provider Configuration .................................................................. 55-18
Various Clients Deployed on JBoss Application Server..................................................... 58-5
JBoss Agent Deployed with an Oracle HTTP Server WebGate ........................................ 58-6
Sample Integration Topology................................................................................................. 58-6
Setting up a Trusted User Account for Windows Impersonation .................................. 59-15
Configuring Rights for the Trusted User in Windows Impersonation .......................... 59-16
Registering the Impersonation Module.............................................................................. 59-19
Verifying Event Viewer Settings.......................................................................................... 59-21
Impersonation Authentication............................................................................................. 59-23
Setting up a Trusted User Account for Windows Impersonation .................................... 60-5
Configuring Rights for the Trusted User in Windows Impersonation ............................ 60-6
Verifying Event Viewer Settings............................................................................................ 60-9
Impersonation Authentication............................................................................................. 60-14
Communication Channels for OAM Servers and WebGates .............................................. C-2
IAMSuiteAgent Settings in the WebLogic Administration Console.................................. D-2
IAMSuiteAgent Registration .................................................................................................... D-3
Resources Protected by the IAMSuiteAgent.......................................................................... D-5
IAMSuite Authentication Policy: OAM Admin Console Policy ......................................... D-6
Protected HigherLevel Policy: Authentication, LDAP Scheme .......................................... D-7
Protected LowerLevel Policy: Authentication, OIMScheme .............................................. D-8
Public Policy: Authentication, AnonymousSheme ............................................................... D-8
IAM Suite Authorization Policy .............................................................................................. D-9
IAM Suite Token Issuance Policy and Resource URLs ........................................................ D-9
Generated Authentication Module: OpenSSOAgentAuthPlugin..................................... D-10
Generated Host Identifier: OpenSSOAgent1 ....................................................................... D-11
Generated Application Domain: OpenSSOAgent1............................................................. D-11
Application Domain Resources: OpenSSOAgent1 ............................................................. D-12
Generated Authentication Policy: OpenSSOAgent Application Domain ....................... D-12
Generated Authorization Policy: OpenSSOAgent Application Domain......................... D-13
Migrated User Identity Store.................................................................................................. D-14
Migrated Agent: OpenSSOAgent1 ........................................................................................ D-15
Migrated Authentication Module: OpenSSOAgent1.......................................................... D-16
Migrated Host Identifier: OpenSSOAgent1 ......................................................................... D-16
Migrated Application Domain: OpenSSOAgent1............................................................... D-16
Migrated Resources: OpenSSOAgent1 ................................................................................. D-17
Migrated Authentication Policy: OpenSSOAgent1 ............................................................ D-17
Migrated Authorization Policy2 Condition: OpenSSOAgent1 ......................................... D-18
Migrated Authorization Policy2: IP Condition Details ...................................................... D-18

xlvii

List of Tables
1–1
1–2
1–3
1–4
2–1
2–2
2–3
2–4
3–1
3–2
3–3
3–4
3–5
4–1
5–1
5–2
5–3
5–4
5–5
5–6
6–1
6–2
6–3
6–4
7–1
7–2
7–3
7–4
7–5
7–6
7–7
8–1
8–2
8–3
8–4
8–5
8–6
8–7
8–8
8–9
8–10
8–11
8–12
8–13
9–1
9–2
9–3
9–4
9–5
9–6
9–7
9–8
10–1

xlviii

Access Manager Deployment Types ....................................................................................... 1-6
Features in Access Manager 11.1.2 .......................................................................................... 1-7
Features Not Available In Access Manager 11.1.2 ................................................................ 1-9
Oracle Access Management Post-Installation Tasks.......................................................... 1-11
Language Codes For Login Pages ........................................................................................ 2-13
Oracle Access Management Language Selection Methods............................................... 2-14
OAM_LANG_PREF Cookie .................................................................................................. 2-15
Application Integration for Language Preference ............................................................. 2-15
Configuration Options .............................................................................................................. 3-2
Common Services ...................................................................................................................... 3-4
Common Settings....................................................................................................................... 3-5
Common Coherence Settings ................................................................................................... 3-7
.................................................................................................................................................... 3-13
Roles for Delegating Administration ...................................................................................... 4-2
Data Sources for Oracle Access Management ....................................................................... 5-1
Data Sources for Oracle Access Management Services ........................................................ 5-2
Components That Use Identity Stores .................................................................................... 5-8
User Identity Store Elements.................................................................................................... 5-9
Access Manager Keys and Storage....................................................................................... 5-32
Keystores for Access Manager and Security Token Service ............................................. 5-32
Conditions Requiring Server Restart ...................................................................................... 6-4
OAM Server Instance Settings ................................................................................................. 6-6
OAM Proxy Settings for an Individual OAM Server ........................................................... 6-6
Default Coherence Settings for Individual OAM Servers.................................................... 6-7
Logging Files............................................................................................................................... 7-2
Logging Defaults........................................................................................................................ 7-2
Oracle Access Management Server-Side Component Loggers ........................................... 7-3
Oracle Access Management Shared-Service Engine Component Loggers ....................... 7-4
Oracle Access Management Foundation API Component Loggers................................... 7-4
Mapping of ODL to Java Levels .............................................................................................. 7-5
Oracle Security Token Service and Identity Federation Loggers ....................................... 7-9
Oracle Business Intelligence Enterprise Edition Reports for OAM.................................... 8-5
Access Manager Administrative Audit Events ..................................................................... 8-6
Access Manager Run-time Audit Events................................................................................ 8-9
REST Run-Time Audit Events............................................................................................... 8-12
Mobile and Social Run-Time Audit Events......................................................................... 8-12
Categories of Audit Events for Identity Federation........................................................... 8-14
Identity Federation Session Management Events .............................................................. 8-14
Protocol Flow Events for Identity Federation..................................................................... 8-15
Server Configuration Identity Federation ........................................................................... 8-15
Security Events for Identity Federation............................................................................... 8-16
Security Token Service Configuration Management Operations .................................... 8-17
Security Token Service-specific Run-time Events .............................................................. 8-19
Audit Configuration Elements.............................................................................................. 8-23
Logging Levels ........................................................................................................................... 9-2
Log Configuration File Names for Components................................................................... 9-5
Log Writers .............................................................................................................................. 9-10
Global Parameters in the First Compound List.................................................................. 9-11
Factors that Determine Whether Logging Is Active .......................................................... 9-16
Mandatory Log Configuration File Parameters ................................................................. 9-17
Log Data File Configuration Parameters............................................................................. 9-18
ParamName Values You Can Configure for Per-Module Logging Threshold.............. 9-23
Accounts_Locked_Out Report Fields .................................................................................. 10-3

10–2
10–3
10–4
10–5
10–6
10–7
10–8
10–9
10–10
11–1
11–2
11–3
11–4
11–5
11–6
11–7
11–8
12–1
12–2
12–3
12–4
12–5
12–6
12–7
12–8
12–9
12–10
12–11
12–12
12–13
13–1
13–2
13–3
13–4
13–5
13–6
13–7
13–8
14–1
14–2
14–3
14–4
14–5
14–6
14–7
14–8
14–9
15–1
15–2
15–3
15–4
15–5
15–6
15–7
15–8

Authentication_statistics Report Fields ...............................................................................
AuthenticationFromIPByUser Report Fields ......................................................................
AuthenticationPerIP Report Fields ......................................................................................
AuthenticationStatisticsPerServer Report Fields ...............................................................
All Errors and Exceptions Report Fields .............................................................................
Authentication Failures Report Fields .................................................................................
Authentication History Report Fields..................................................................................
Authorization History Report Fields ...................................................................................
Multiple Logins From Same IP Report Fields.....................................................................
OAM Server Metrics: Server Processes Overview Tab .....................................................
OAM Server Metrics: Session Operations ...........................................................................
OAM Server Metrics: Server Operations Tab .....................................................................
OAM Proxy Metrics..............................................................................................................
OAM Proxy Tuning Parameters .........................................................................................
OpenSSO Proxy Server Events............................................................................................
OpenSSO Proxy Metrics: Server .........................................................................................
OpenSSO Proxy Metrics: Agent..........................................................................................
Farm Page Sections .................................................................................................................
Resulting Pages for Selected Nodes and Targets ...............................................................
Summary of Performance Overviews in Fusion Middleware Control.........................
Access Manager Component Metrics ................................................................................
STS Component-Specific Metrics........................................................................................
Status and Controls on Performance Summary Pages....................................................
OAM Log Availability and Functions in Fusion Middleware Control.........................
Log Levels Tab on Log Configuration Page......................................................................
Log Files Elements ................................................................................................................
OAM Log Message Search Controls in Fusion Middleware Control............................
System MBean Browser .......................................................................................................
MBeans that Access Manager and Security Token Service Deploy...............................
System MBean Browser .......................................................................................................
Access Manager Settings: Load Balancer ............................................................................
Server Error Mode ..................................................................................................................
Error Trigger Condition, Modes, and Message Codes ......................................................
External Error Codes, Trigger Conditions, and Recommended Messages ....................
Access Manager Settings: SSO ..............................................................................................
Summary: Simple and Cert Mode ........................................................................................
Server Common OAM Proxy Secure Communication Settings.......................................
Policy Evaluation Caches.....................................................................................................
Agent Types.............................................................................................................................
Agent Registration and SSO Support...................................................................................
Run Time Processing Overview for Access Manager........................................................
Keys and Policies Generated During Agent Registration.................................................
Artifacts Associated with Agent Registration ....................................................................
Copying Generated Artifacts ................................................................................................
Remote Registration Methods...............................................................................................
Remote Registration Does Not Support ..............................................................................
Agent Registration and Configuration Update Artifacts................................................
Elements on Create Pages for 11g and 10g OAM Agents .................................................
User-Defined WebGate Parameters .....................................................................................
Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages .....
Agent Search Controls..........................................................................................................
Environment Variables to Set within oamreg...................................................................
Remote Registration Command Arguments: mode ........................................................
Remote Registration Command Samples..........................................................................
Common Elements in Remote Registration Requests .....................................................

10-3
10-4
10-4
10-4
10-5
10-5
10-5
10-6
10-6
11-3
11-4
11-5
11-10
11-11
11-13
11-13
11-14
12-4
12-8
12-10
12-13
12-14
12-15
12-20
12-22
12-26
12-29
12-34
12-34
12-36
13-2
13-3
13-4
13-4
13-6
13-7
13-8
13-10
14-2
14-3
14-4
14-6
14-7
14-7
14-8
14-8
14-10
15-3
15-6
15-16
15-21
15-25
15-25
15-25
15-26

xlix

15–9
15–10
15–11
15–12
15–13
15–14
16–1
16–2
16–3
16–4
16–5
16–6
16–7
16–8
16–9
17–1
17–2
18–1
18–2
18–3
19–1
19–2
21–1
21–2
21–3
21–4
21–5
21–6
22–1
22–2
22–3
22–4
22–5
22–6
22–7
22–8
22–9
22–10
22–11
22–12
22–13
22–14
22–15
22–16
22–17
22–18
22–19
22–20
22–21
22–22
22–23
22–24
22–25
22–26
22–27

l

Remote Registration Request Templates for OAM Agents ............................................
Elements in Extended OAM Agent Remote Registration Requests ..............................
Variables Required for Remote Registration ....................................................................
Files Returned by in-band Administrator to out-of-band Administrator ....................
Remote Agent Update Modes and Input Files .................................................................
Delta: OAM Agent Update versus Registration Request................................................
Session Lifecycle States ..........................................................................................................
Session Checks for State Changes.........................................................................................
Session Removal......................................................................................................................
Application Domain-Specific Overrides..............................................................................
Session Content: Single Authentication Scheme ................................................................
Session Outcomes: Multiple Authentication Schemes ......................................................
Global Session Settings...........................................................................................................
Application-Specific Session Timing Overrides...............................................................
Session Management Controls and the Results Table.....................................................
Multi-Data Center Policy Configurations for Idle Timeout ...........................................
Session Synchronization and Failover Scenarios .............................................................
MDC Use Cases.......................................................................................................................
oamMDC.properties Properties..........................................................................................
partnerInfo.properties Properties.......................................................................................
Replication States ....................................................................................................................
Modifying Replication Agreement Properties..................................................................
Summary: SSO Components .................................................................................................
Introduction to SSO Implementations .................................................................................
Access Manager Global, Shared Policy Components........................................................
Access Manager Policy Components ...................................................................................
Condition Types....................................................................................................................
SSO Cookies ...........................................................................................................................
Comparison: Resource Types for Access Manager versus 10g ........................................
Resource Type Definition ......................................................................................................
Host Identifiers Examples......................................................................................................
Host Identifier Definitions...................................................................................................
Comparing the DCC and ECC ............................................................................................
Native Authentication Modules .........................................................................................
Native Kerberos Authentication Module Definition .......................................................
Native LDAP Authentication Modules Definition ..........................................................
X509 Authentication Module Definition ...........................................................................
Simple Form versus Multi-Step Authentication...............................................................
General tab .............................................................................................................................
Add New Step Entries, Steps Results Table, and Details Section..................................
Parameter Details for Various Plug-ins .............................................................................
Steps Orchestration Tab .......................................................................................................
X509 Step Details (KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT) ......................
Steps and Plug-ins in a Customized Step-up Authentication Module .........................
Managing Custom Plug-ins Actions ..................................................................................
Plugins Status Table..............................................................................................................
Example of Plugin Details Extracted from XML Metadata File.....................................
Authentication Scheme Definition .....................................................................................
Pre-configured Authentication Schemes ...........................................................................
Challenge Parameters in Pre-configured Schemes ..........................................................
User-Defined Challenge Parameters for Authentication Schemes................................
Advanced Rules Attributes .................................................................................................
Sample Advanced Rules ......................................................................................................
Request Context Data ...........................................................................................................
Location Context Data..........................................................................................................

15-29
15-30
15-33
15-35
15-37
15-37
16-3
16-4
16-4
16-5
16-7
16-8
16-9
16-10
16-12
17-19
17-20
18-2
18-11
18-13
19-3
19-14
21-2
21-3
21-8
21-9
21-13
21-14
22-3
22-5
22-8
22-15
22-20
22-24
22-25
22-26
22-27
22-31
22-33
22-34
22-35
22-39
22-44
22-51
22-60
22-61
22-62
22-65
22-68
22-75
22-76
22-84
22-85
22-86
22-87

22–28
22–29
22–30
22–31
22–32
22–33
22–34
22–35
22–36
22–37
23–1
23–2
24–1
24–2
24–3
24–4
24–5
24–6
24–7
24–8
24–9
25–1
25–2
25–3
25–4
25–5
25–6
25–7
25–8
25–9
25–10
25–11
25–12
25–13
25–14
25–15
25–16
25–17
25–18
25–19
25–20
25–21
25–22
25–23
25–24
25–25
25–26
25–27
25–28
25–29
25–30
25–31
25–32
25–33
26–1

Session Context Data ............................................................................................................
User Context Data.................................................................................................................
Challenge Parameters for 10g/11g Encrypted Cookies ..................................................
Resource Webgate Support of POST Data Preservation and Restoration....................
Credential Collector Support for POST Data Handling..................................................
Authentication Schemes Supporting POST Data Handling ...........................................
Parameters Required for Authentication POST Data Handling ....................................
ECC and DCC: Long URL Handling .................................................................................
Authentication Schemes Supporting Long URL Handling ............................................
Parameters Required for Long URL Handling.................................................................
Login Processing with Access Manager-Protected Resources .........................................
DCC Deployment Support ....................................................................................................
Password Policy Configuration Parameters .......................................................................
Password Policy Elements.....................................................................................................
Specifying Credential Collectors and Related Forms for Authentication ......................
Credential Collector Password Pages ..................................................................................
Password Management Forms and Functions ...................................................................
Location of Oracle-provided LDIFs for LDAP Providers ...............................................
Key Password Attributes in a Password Policy ...............................................................
User Password Step Details.................................................................................................
Included LDIF Schema Files................................................................................................
Resource Definition Elements .............................................................................................
HTTP Resources Sample URL Values................................................................................
Supported Wildcards in Resource URL Patterns (Precedence Order)..........................
Sample Resource URLs ........................................................................................................
Pattern Matching for Requested URLs ..............................................................................
Query String Matching: Examples .....................................................................................
Resource Evaluation Outcomes ..........................................................................................
Search Elements for a Resource in an Application Domain ...........................................
Authentication Policy Elements and Descriptions...........................................................
Authorization Policy Elements and Descriptions ............................................................
Authorization Policy Condition Tab..................................................................................
Add Condition Window Elements.....................................................................................
Add identities Elements.......................................................................................................
Add Search Filter Elements .................................................................................................
LDAP Search Filter Examples for Access Manager .........................................................
Temporal Condition Details ................................................................................................
Access Conditions that Require Attribute-Type Conditions..........................................
Attribute Condition Elements .............................................................................................
Attribute Names for Request Built-ins ..............................................................................
Attribute Names for Session Built-ins................................................................................
Attribute Condition Data (Aggregation of Conditions)..................................................
Authorization Policy Rules Elements ................................................................................
Rule Tab in Expression Mode .............................................................................................
Operators for Expressions in Authorization Rules ..........................................................
Response Elements ...............................................................................................................
Namespace Request Variables for Single Sign-On...........................................................
Namespace Session Variables for Single Sign-On............................................................
Namespace User Variables ..................................................................................................
Simple Responses and Descriptions...................................................................................
Complex Responses..............................................................................................................
Fresh OSSO Installation: Protected Policy Response (Header)......................................
Remote Policy Management Modes, Templates, and Flags ...........................................
Remote Management Template Elements.........................................................................
User Interactions: Tester Console Mode versus Command Line Mode Operations ....

22-87
22-87
22-88
22-90
22-91
22-92
22-92
22-96
22-96
22-96
23-3
23-6
24-3
24-4
24-6
24-9
24-9
24-13
24-14
24-17
24-25
25-15
25-18
25-19
25-21
25-22
25-23
25-26
25-29
25-32
25-36
25-42
25-44
25-47
25-48
25-49
25-55
25-56
25-57
25-58
25-58
25-59
25-62
25-64
25-64
25-69
25-71
25-71
25-71
25-72
25-73
25-75
25-78
25-81
26-7

li

26–2
26–3
26–4
26–5
26–6
26–7
26–8
26–9
26–10
26–11
26–12
26–13
26–14
27–1
27–2
28–1
28–2
28–3
28–4
28–5
28–6
28–7
28–8
28–9
28–10
28–11
28–12
28–13
29–1
29–2
29–3
29–4
29–5
29–6
29–7
29–8
29–9
30–1
30–2
30–3
30–4
30–5
33–1
35–1
35–2
36–1
36–2
37–1
37–2
37–3
37–4
37–5
37–6
37–7
37–8

lii

Access Tester Supported System Properties .......................................................................
Access Tester Console Panels..............................................................................................
Command Buttons in Access Tester Panels ......................................................................
Additional Access Tester Buttons.......................................................................................
Access Tester Menus.............................................................................................................
Connection Panel Information ............................................................................................
Protected Resource URI Panel Fields and Controls.........................................................
Access Tester User Identity Panel Fields and Controls...................................................
Access Tester Capture Request Options............................................................................
Generate Script Command ..................................................................................................
Test Script Control Parameters ...........................................................................................
Run Test Script Commands.................................................................................................
Mismatched Results Reasons in the Statistics Document ...............................................
Centralized Logout Circumstances ......................................................................................
Logout Details After Registration (ObAccessClient.xml) .................................................
Features: OpenSSO Agents with Access Manager.............................................................
OpenSSO Policy Migration....................................................................................................
OpenSSO Reliance on Access Manager ...............................................................................
Access Manager Processing with OpenSSO .......................................................................
Elements on the New OpenSSO Agent Page ....................................................................
Relocating OpenSSO Artifacts ............................................................................................
Expanded OpenSSO Agent Registration Elements..........................................................
OpenSSO Request Files for Remote Registration.............................................................
OpenSSO Agent Remote Registration Request ................................................................
J2EE Request File Mappings to the Properties File ..........................................................
Mapping the Web Request File to the Properties File .....................................................
Delta: OpenSSO Remote Registration versus Remote Updates.....................................
Other OpenSSO Information in this Guide.......................................................................
OSSO Agents with Access Manager ....................................................................................
11g Access Manager SSO versus OSSO 10g Component Summary ...............................
Create OSSO Agent Page Elements......................................................................................
Relocating OSSO Artifacts .....................................................................................................
Expanded OSSO Agent Elements.........................................................................................
OpenSSO Request Files for Remote Registration.............................................................
OSSO-Specific Elements in a Remote Registration Request ...........................................
Delta: OSSO Remote Registration versus Remote Updates ...........................................
Other OSSO Information in this Guide .............................................................................
Installation Comparison with 10g WebGates .....................................................................
Comparison: Access Manager 11g versus 10g....................................................................
Comparing Access Manager 11g Policy Model versus 10g ..............................................
Preparing for 10g WebGate Installation with Access Manager 11g ..............................
Sample end_url Parameter Specifications .........................................................................
IIS 7 Webgate Windows Server 2008....................................................................................
Adaptive Authentication Plugin Properties .......................................................................
Server Side Configuration for Adaptive Authentication Service ....................................
Location URL Parameter Definitions ...................................................................................
Offline Configuration URL Parameters...............................................................................
Supported SAML 2.0 NameID Formats...............................................................................
SAML 2.0 URLs for Identity Federation Acting As Identity Provider............................
SAML 2.0 URLs for Identity Federation Acting as Service Provider ..............................
Supported SAML 1.1 NameID Formats.............................................................................
SAML 1.1 URLs for Identity Federation Acting As Identity Provider..........................
SAML 1.1 URL for Identity Federation Acting as Service Provider..............................
OpenID 2.0 URLs for Identity Federation Acting As Identity Provider.......................
OpenID 2.0 URLs for Identity Federation Acting as Service Provider .........................

26-9
26-13
26-14
26-14
26-15
26-17
26-19
26-21
26-26
26-27
26-28
26-29
26-32
27-2
27-3
28-2
28-3
28-5
28-8
28-11
28-12
28-15
28-22
28-23
28-24
28-25
28-27
28-29
29-2
29-3
29-7
29-8
29-9
29-12
29-13
29-15
29-18
30-4
30-6
30-8
30-14
30-26
33-6
35-8
35-9
36-2
36-3
37-7
37-9
37-9
37-10
37-11
37-11
37-13
37-13

37–9
37–10
38–1
38–2
38–3
38–4
38–5
38–6
38–7
38–8
38–9
38–10
38–11
38–12
39–1
39–2
39–3
39–4
40–1
40–2
40–3
40–4
40–5
40–6
40–7
40–8
41–1
41–2
41–3
43–1
43–2
44–1
44–2
44–3
44–4
44–5
45–1
45–2
45–3
45–4
45–5
45–6
45–7
45–8
45–9
45–10
45–11
45–12
45–13
45–14
45–15
46–1
46–2
46–3

Configuring Identity Federation Settings.......................................................................... 37-14
Implementing Identity Federation .................................................................................... 37-14
Default Partner Profiles.......................................................................................................... 38-2
Identity Provider Partner Settings........................................................................................ 38-4
Attributes for Google OpenID Partner ............................................................................... 38-7
Attributes for Yahoo OpenID Partner................................................................................. 38-8
Elements Used for IdP Provider Search ............................................................................. 38-9
Service Provider Partner Settings ....................................................................................... 38-10
Sample SP Attribute Mappings........................................................................................... 38-13
Attribute Mapping Value Expressions .............................................................................. 38-13
Sample IdP Attribute Mappings......................................................................................... 38-15
Default Federation Authentication Method and Access Manager Authentication Scheme
Mappings 38-16
Configuration Parameters for Attribute Sharing Plug-in ............................................... 38-22
Session Attributes Accessible To Attribute Sharing Plug-in .......................................... 38-22
Federation Settings in the Console ....................................................................................... 39-2
General Federation Settings .................................................................................................. 39-3
Federation Proxy Settings ...................................................................................................... 39-4
Keystore Settings for Federation........................................................................................... 39-5
FederationScheme Element Definitions............................................................................... 40-2
FederationPlugin Steps .......................................................................................................... 40-4
Orchestration of FederationPlugin...................................................................................... 40-4
OIFScheme Definition ............................................................................................................ 40-7
OIFMTLDAPPlugin Steps ..................................................................................................... 40-8
Policy Response Elements ................................................................................................... 40-10
Message Attribute Mapping................................................................................................ 40-22
Office 365 Service Provider Attribute Values ................................................................... 40-22
Security Token Service 11g Infrastructure .......................................................................... 41-3
Security Token Service Terms ............................................................................................... 41-4
Integrated Oracle Web Services Manager ........................................................................... 41-7
Security Token Service Settings .......................................................................................... 43-10
Configuring a Non-Oracle WSM Client for WSS Kerberos Policies.............................. 43-18
Security Token Service Public Keys Used at Run Time .................................................... 44-2
Keystore Mbeans..................................................................................................................... 44-2
Partner Keys for WS-Trust Communications ..................................................................... 44-7
Conditions for Security Token Service Certificate Validation.......................................... 44-9
Successful Certificate Validation Requirements................................................................. 44-9
Search Validation Template .................................................................................................. 45-4
Issuance Template Requirements ......................................................................................... 45-5
Issuance Template: General Details ..................................................................................... 45-6
Issuance Properties: Username Token Type ....................................................................... 45-6
Issuance Properties: SAML Token Types ............................................................................ 45-8
Security Details: SAML Tokens ............................................................................................ 45-9
Issuance Template: Attribute Mapping, SAML Token ................................................... 45-10
Validation Template Protocols............................................................................................ 45-14
New Validation Template: General Details ...................................................................... 45-15
New Validation Template: Authentication Details.......................................................... 45-16
New Validation Template: Token Mapping ..................................................................... 45-20
Endpoints Page...................................................................................................................... 45-26
Conditions tab: Token Issuance Policy .............................................................................. 45-28
New Custom Token Elements............................................................................................. 45-34
Custom Tokens Search Elements and Controls................................................................ 45-36
Security Token Service Partners ........................................................................................... 46-1
Security Token Service Clients.............................................................................................. 46-2
Security Token Service Partner Entry .................................................................................. 46-2

liii

46–4
46–5
46–6
46–7
46–8
46–9
46–10
46–11
48–1
48–2
48–3
48–4
48–5
49–1
49–2
49–3
49–4
49–5
49–6
49–7
49–8
49–9
49–10
49–11
49–12
49–13
49–14
49–15
49–16
49–17
49–18
49–19
49–20
49–21
49–22
50–1
50–2
50–3
50–4
50–5
50–6
50–7
50–8
51–1
52–1
52–2
53–1
53–2
53–3
53–4
53–5
53–6
55–1

liv

Security Token Service Partner Profile Data....................................................................... 46-2
Partner Elements for Partner Types ..................................................................................... 46-3
Elements for Security Token Service Partners .................................................................... 46-4
Profile: General........................................................................................................................ 46-8
Requester Profile: Token and Attributes ............................................................................. 46-9
Relying Party Profile Requirements................................................................................... 46-11
Token and Attributes Elements: Issuing Authority......................................................... 46-15
Issuing Authority Token Mapping Elements ................................................................... 46-17
Features in Mobile and Social Based on the Companion Services Installed .................. 48-3
Mobile and Non-Mobile Authentication Service Providers in Mobile and Social Services....
48-7
Android, iOS, and Java Features of the Mobile and Social Services Client SDK........... 48-9
Token Requirements for the Mobile and Social Server ................................................... 48-20
Identity Providers That Mobile and Social Natively Supports ...................................... 48-23
Pre-configured Authentication Service Providers ............................................................. 49-6
Access Manager Authentication Service Provider Default Attributes............................ 49-8
Webgate Agent for Authentication Service Provider Default Attributes....................... 49-9
JWT Authentication Service Provider Default Attributes............................................... 49-10
JWT-OAM Authentication Service Provider Default Attributes ................................... 49-10
Access Manager Authorization Service Provider Default Attributes ........................... 49-17
Webgate Agent for Authorization Service Provider Default Attributes ...................... 49-18
User Profile Service Provider Default Attribute Names and Values ............................ 49-19
User Profile Service Provider Default Attribute Names and Values ............................ 49-20
Authentication Service Profile Default General Properties ............................................ 49-23
Token Support and URI Category Information Default Properties .............................. 49-23
Authorization Service Profile Default General Properties.............................................. 49-24
User Profile Service Profile Default General Properties.................................................. 49-25
Security Handler Plug-in General Properties ................................................................... 49-27
Application Profile General Properties.............................................................................. 49-28
Service Domain General Properties ................................................................................... 49-30
Application Profile Selection Properties............................................................................ 49-31
Service Profile Selection Properties .................................................................................... 49-32
User Profile Service Protection Properties ........................................................................ 49-33
Authorization Service Protection Properties .................................................................... 49-33
OAAM Policies Supported By Mobile and Social............................................................ 49-42
Mapping Terms Between OAAM and Mobile and Social .............................................. 49-43
OpenID Protocol Attributes .................................................................................................. 50-4
OAuth Protocol Attributes .................................................................................................... 50-5
User Attributes Returned By Google ................................................................................... 50-6
User Attributes Returned By Yahoo..................................................................................... 50-6
User Profile Attributes Returned By Foursquare............................................................... 50-7
User Profile Attributes Returned By Windows Live ......................................................... 50-7
Service Provider Interface Information Properties .......................................................... 50-12
Account Linking Properties................................................................................................. 50-19
Attribute Settings for an Oracle Access Manager 11gR1 PS1 Authentication Service
Provider 51-2
Default User Profile Services Endpoint Operations ........................................................ 52-14
User Profile Resource Server - Scope Settings .................................................................. 52-15
OAuth Service Profile Configuration Attributes................................................................ 53-8
Web Client Attributes Names and Values ........................................................................ 53-14
OAuth Service Provider Attributes for Access Manager ................................................ 53-19
User Profile Service Attributes............................................................................................ 53-24
OAuth Server Settings Attributes....................................................................................... 53-29
Default OAuth JKS Keystore File and Settings File ......................................................... 53-31
Identity Context Schema Attributes..................................................................................... 55-4

55–2
56–1
56–2
56–3
57–1
58–1
59–1
59–2
59–3
59–4
60–1
62–1
62–2
63–1
63–2
63–3
A–1
B–1
C–1
D–1

Mapping Identity Context Operations ................................................................................ 55-9
Access Manager Support for RSA Features ........................................................................ 56-2
RSA Features Not Supported ................................................................................................ 56-2
Installation and Configuration Guidelines ......................................................................... 56-4
Sample Naming....................................................................................................................... 57-6
JBoss Agent Composition ...................................................................................................... 58-3
Component Requirements..................................................................................................... 59-6
Microsoft Requirements for this Integration....................................................................... 59-7
Create Web Application Options for Microsoft SharePoint Server............................... 59-11
Create a Web Application to Host a Site Collection for SharePoint Server.................. 59-13
Requirements for Impersonation with a Header Variable ............................................... 60-3
Login Module Stacks for using Header Variables ............................................................. 62-6
Login Module Stacks for using Header Variables ........................................................... 62-13
.................................................................................................................................................... 63-3
.................................................................................................................................................... 63-4
Ticket Authentication Values ................................................................................................ 63-6
addOAMSSOProvider Command-line Arguments............................................................. A-4
Languages for Localized Messages ........................................................................................ B-2
importcert Command Syntax.................................................................................................. C-4
Comparing IAMSuiteAgent with 11g and 10g Webgates................................................... D-4

lv

List of Examples
3–1
3–2
7–1
9–1
9–2
9–3
9–4
9–5
9–6
9–7
9–8
15–1
15–2
18–1
18–2
18–3
19–1
19–2
19–3
19–4
26–1
26–2
26–3
26–4
26–5
30–1
38–1
38–2
42–1
42–2
49–1
53–1
53–2
53–3
53–4
53–5
55–1
55–2
55–3
55–4
57–1
59–1
A–1

lvi

Certificate Validation Module Configuration...................................................................... 3-10
Multiple OCSP Responder Configuration ........................................................................... 3-12
Configuring Access Manager Loggers and Log Handlers.................................................... 7-4
The Default Log Configuration File with Comments ........................................................... 9-6
Simple Lists with Global Settings (First Compound List in oblog_config_wg.xml)...... 9-12
FILTER_LIST Masks Sensitive Attributes in Log Files....................................................... 9-15
Valid Name/Value List........................................................................................................... 9-15
Another Valid Name/Value List........................................................................................... 9-15
Opening tag for a Name/Value List ..................................................................................... 9-16
Opening tag for a Name/Value List ..................................................................................... 9-16
A Default Log Configuration File Without Embedded Comments ................................ 9-19
rreg registration Sample Output.......................................................................................... 15-34
Updates for the 11g WebGate in mod_wl_ohs.conf ......................................................... 15-45
DCMaster.properties for Master............................................................................................ 18-4
DCClone1.properties for Clone ............................................................................................. 18-4
Sample oamMDCProperty.properties File......................................................................... 18-12
Default Transformation Rules................................................................................................ 19-9
Modified PrimaryServerList Transformation Rule........................................................... 19-10
Modified Transformation Rule for Different Agents........................................................ 19-11
Replication Rules XML File .................................................................................................. 19-11
Connection Configuration File............................................................................................. 26-32
Generated Input Test Script.................................................................................................. 26-33
Output File Generated During a Test Run ......................................................................... 26-35
Sample Statistics Document ................................................................................................. 26-36
Execution Log ......................................................................................................................... 26-38
logout.html Script .................................................................................................................. 30-24
Sample SOAP Attribute Request ......................................................................................... 38-20
Sample SOAP Attribute Response ...................................................................................... 38-20
Sample exchange: Request Security Token Sent By the Client ....................................... 42-21
Request Security Token Response sent by the Security Token Service ......................... 42-22
Sample merge-creds.xml....................................................................................................... 49-40
Creating the Keystore............................................................................................................ 53-33
Loading the Certificates ........................................................................................................ 53-33
Update jps-config.xml ........................................................................................................... 53-34
Adding the new Service Instance ........................................................................................ 53-34
Creating Credential Store Entries ........................................................................................ 53-35
Working with Identity Context Dictionary.......................................................................... 55-9
Using WLST To Grant Attribute Service Access To Application ................................... 55-10
Working with Identity Context Runtime ........................................................................... 55-10
Custom Function Creating Identity Context ..................................................................... 55-15
oam-config.xml....................................................................................................................... 57-19
Sample .ASP Page Code........................................................................................................ 59-22
Sample SSO Configuration for Access Manager ................................................................... A-5

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:
lvii

■
■

■

■

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:

lviii

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.

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

lix

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.

lx

■

Introduction to Application Domain and Policy Creation

■

Administering Identity Federation As An Identity Provider

■

Managing Oracle Access Management Oracle Access Portal

■

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

lxi

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.

■

■

lxii

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"

■

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.
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.

Access Management Services
Several previously separate access products of the Oracle Identity Management
portfolio are combined into one product: Oracle Access Management.

lxiii

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"

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.
See Also: Chapter 26, "Validating Connectivity and Policies Using
the Access Tester"

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.
See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40

■

A new condition type: Attribute.
See Also:

■

"About Attribute Conditions" on page 25-56

Use of Implied Constraints option in policies is replace, allowing you to create
particular condition types by instantiating those and selecting rules.
See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40

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:
■

■

lxiv

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.

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.
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"

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.
See Also:
■

Oracle Fusion Middleware Developer's Guide for Oracle Access
Management

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).
See Also:

Chapter 55, "Using Identity Context"

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:
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"

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.

lxv

See Also: "About LDAP Search Filter Support in Identity
Conditions" on page 25-47

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.
See Also:
■

"Example: Leveraging SubjectAltName Extension Data and
Integrating with Multiple OCSP Endpoints" on page 22-46

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.
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social"

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.
See Also:
■
■

"Using Multiple Identity Stores" on page 5-6
"Orchestrating Multi-Step Authentication with Plug-in Based
Modules" on page 22-29

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:
■
■

lxvi

Chapter 28, "Registering and Managing Legacy OpenSSO Agents"
Oracle Fusion Middleware Upgrade Guide for Oracle Identity and
Access Management

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.
See Also:
■

"Managing Global Password Policy"

■

"Configuring 11g WebGates and Authentication Policy for DCC"

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:
See Also:
■

"About Query String Name and Value Parameters for Resource
Definitions" on page 25-21

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).
See Also: "Managing TokenServiceRP Type Resources in
Application Domains" on page 45-32

RESTful Services
Oracle Access Management supports programmatic RESTful services.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management

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.
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.

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:

lxvii

■

■

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)
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management

Token Issuance Policy for Mobile and Social
A Token Issuance Policy is required for clients for Mobile and Social performing
authentication and authorization.
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social" for details about Mobile and Social Authentication Service

Tuning Performance
A survey of topics is provided to help tune a deployed Oracle Access Management
environment to ensure optimal performance and stability.
See Also: Oracle Fusion Middleware Performance and Tuning
Guide

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.
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

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.
Item
Services

In Oracle Access Management 11.1.2

In Oracle Access Management 11.1.1

Access Manager

Access Manager

Identity Federation

N/A

Security Token Service

Security Token Service

Mobile and Social

N/A

Identity Context (always enabled)
Agents

lxviii

WebGate (OAM Agent)

WebGate (OAM Agent)

Access Client (OAM Agent)

Access Client (OAM Agent)

OSSO Agent

OSSO Agent

OpenSSO Agent

N/A

Item

In Oracle Access Management 11.1.2

In Oracle Access Management 11.1.1

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

Oracle Access Management Console

Oracle Access Manager Console
Remote registration tool

Policy Creation

Remote registration tool for automated Agent
registration, Application Domain creation with
default security policies.

Authorization

Conditions and Rules

Constraints

lxix

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

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.

[2]

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.

Introducing Oracle Access Management

1-1

Understanding Oracle Access Management Services

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

1-2 Administrator's Guide for Oracle Access Management

Understanding Oracle Access Management Access Manager

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.

Introducing Oracle Access Management

1-3

Understanding Oracle Access Management Access Manager

For information on the differences between Access Manager
11g, 10g and other software, see:

Note:
■
■

■

"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

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.
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:

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).
This section does not illustrate or discuss all Access Manager
components.

Note:

1-4 Administrator's Guide for Oracle Access Management

Understanding Oracle Access Management Access Manager

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.

Introducing Oracle Access Management

1-5

Understanding Oracle Access Management Access Manager

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

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
In an existing WebLogic Server domain, the WebLogic
Administration Server is already installed and operational.

Note:

■

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
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.

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.
See Also:

■

"Managing the Policy and Session Database" on page 5-29

Identity Store: The default Embedded LDAP data store is set as the primary user
identity store for Access Manager.
See Also: "Registering and Managing User Identity Stores" on
page 5-4

■

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.
See Also:

"Managing the Policy and Session Database" on page 5-29

1-6 Administrator's Guide for Oracle Access Management

About Access Manager 11.1.2.3.0

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
Enables secure, central management of enterprise identities.
Management Infrastructure
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.
OAM Server (installed on a WebLogic Managed Sever),

Server-side components

■

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.

Proxy

Provides support for legacy systems

Back channel protocols: Authenticated clients can perform session operations using enhancements
in the Oracle Access Protocol (OAP).

■

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."

Introducing Oracle Access Management

1-7

About Access Manager 11.1.2.3.0

Table 1–2 (Cont.) Features in Access Manager 11.1.2
Access Manager 11g

Description

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.
■

■

■

■

Keys storage

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.

■

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

Introduces client-side cryptography and ensures that cryptography is performed at both the agent
Encryption / Decryption
(The process of converting and server ends:
encrypted data back into its
1.
Webgate encrypts obrareq.cgi using the agent key.
original form)
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

Response token replay
prevention

■

■

Maintains this client's age, and includes it in the host-based cookie: OAMAuthnCookie for 11g
Webgate (or ObSSOCookie for 10g Webgate)
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.

1-8 Administrator's Guide for Oracle Access Management

About System Requirements and Certification

Table 1–2 (Cont.) Features in Access Manager 11.1.2
Access Manager 11g

Description

Multiple network domain
support

Access Manager 11g supports cross-network-domain single sign-on out of the box.

Cookies

Oracle recommends you use Oracle Federation for this situation.
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.

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.
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

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

Introducing Oracle Access Management

1-9

Understanding Oracle Access Management Installation

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

1-10 Administrator's Guide for Oracle Access Management

Understanding Oracle Access Management Installation

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
Access Manager

Requirements
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

Introducing Oracle Access Management 1-11

Understanding Oracle Access Management Installation

1-12 Administrator's Guide for Oracle Access Management

2
Getting Started with Oracle Access
Management
2

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.

[3]

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.

Getting Started with Oracle Access Management

2-1

Starting and Stopping Servers in Your Deployment

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
See Also:

Oracle WebLogic Server Administrator Guide for details.

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
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.

1.

Navigate to your $DOMAIN_HOME/bin.

2.

Start AdminServer:

3.

■

Unix: ./startWebLogic.sh

■

Windows: run startWebLogic.cmd

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
2-2 Administrator's Guide for Oracle Access Management

About Oracle Access Management Administrators

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.
Unless explicitly stated, the term Administrator in this guide
refers to the Oracle Access Management System Administrator.

Note:

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

Getting Started with Oracle Access Management

2-3

About the Oracle Access Management Console and the Policy Manager Console

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

2-4 Administrator's Guide for Oracle Access Management

Understanding the Oracle Access Management Console

REST endpoints, WLST and the RREG servlet are available
only on AdminServer.

Note:

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
The Oracle Access Management Console is designed for
optimal display at a resolution of 1024x768.

Note:

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.
Some of these services are disabled by default and would need
to be enabled under the Configuration Launch Pad.

Note:

Getting Started with Oracle Access Management

2-5

Understanding the Oracle Access Management Console

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

2-6 Administrator's Guide for Oracle Access Management

Logging Into the Oracle Access Management Console

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)

Getting Started with Oracle Access Management

2-7

Logging Into the Oracle Access Management Console

■

/oamconsole/ refers to the Oracle Access Management Console Log In page
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:

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)
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.
Note:

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.
See Also: "About Oracle Access Management Administrators" on
page 2-3

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/

2-8 Administrator's Guide for Oracle Access Management

Using the Oracle Access Management Console

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: keystores/adapters.jks
server.os_xml: keystores/adapters.jks
keystores/adapters.jks
New_Password

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.

Getting Started with Oracle Access Management

2-9

Using the Oracle Access Management Console

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:

4.

–

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.

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.

2-10 Administrator's Guide for Oracle Access Management

Logging, Auditing, Reporting and Monitoring Performance

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.
Note:

The search tool is case insensitive.

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.
See Also:

■

Chapter 15, "Registering and Managing OAM 11g Agents"

Upgrade Assistant (UA) enables you to transfer OSSO 10g configuration to Oracle
Access Management
See Also:
■

■

Oracle Fusion Middleware Upgrade Guide for Oracle Identity and
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.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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.

Getting Started with Oracle Access Management 2-11

Configuring Oracle Access Management Login Options

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".
See Also: Oracle Fusion Middleware Performance and Tuning
Guide

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

2-12 Administrator's Guide for Oracle Access Management

Configuring Oracle Access Management Login Options

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

el

Greek

en

English

English

es

Spanish

Spanish

fi

Finnish

fr

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

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

German

French

Brazilian Portuguese

Getting Started with Oracle Access Management 2-13

Configuring Oracle Access Management Login Options

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.
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.

Note:

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.
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.

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.

2-14 Administrator's Guide for Oracle Access Management

Configuring Oracle Access Management Login Options

Language Selection is only available in the ECC login page; it
is not currently available in the DCC login page.

Note:

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.
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.

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.
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".

Getting Started with Oracle Access Management 2-15

Configuring Oracle Access Management Login Options

Table 2–4 (Cont.) Application Integration for Language Preference
Method

Description

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.

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.)
If the Application Domain 'Session Idle Timeout' is specified,
Persistent Login cannot be enabled.

Note:

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

2-16 Administrator's Guide for Oracle Access Management

Configuring Oracle Access Management Login Options

■

■

■

■

–

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.

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

4.

Click the Application Domains link in the Launch Pad.
Getting Started with Oracle Access Management 2-17

Configuring Oracle Access Management Login Options

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.
Note:

6.

The Public Resource Policy should not be modified.

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.

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.
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: 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.

2-18 Administrator's Guide for Oracle Access Management

Configuring Oracle Access Management Login Options

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.

3.

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.

Change to the OID directory and run ldapmodify.
$ setenv ORACLE_HOME 
$ cd $ORACLE_HOME/bin
$ ./ldapmodify -h  -p  -D  -w 
-v -f oam_user_write_acl_users_obpsftid_template.ldif

Getting Started with Oracle Access Management 2-19

Configuring Oracle Access Management Login Options

2-20 Administrator's Guide for Oracle Access Management

Part II
Part 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

This chapter explains how to configure properties that are used in common by the
services integrated into Oracle Access Management.

[4]

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.

Managing Common Services and Certificate Validation 3-1

Configuring 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.

Settings > Social Identity

Provides access to configurations for the Social Identity features of
Oracle Access Management Mobile and Social.

See "Managing Common and System Configurations"

See "Managing Oracle Access Management Mobile and Social"

3-2 Administrator's Guide for Oracle Access Management

Enabling or Disabling Available Services

Table 3–1 (Cont.) Configuration Options
Node

Description

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 Provides access to configurations for Oracle Access Management
Service
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"

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

Managing Common Services and Certificate Validation 3-3

Enabling or Disabling Available Services

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.
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"

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).

3-4 Administrator's Guide for Oracle Access Management

Managing Common Settings

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 Services and Certificate Validation 3-5

Managing Common Settings

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.

6.

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".

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.

3-6 Administrator's Guide for Oracle Access Management

Managing Certificate Validation and Revocation

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.
Oracle strongly recommends that you do not alter these
settings without the assistance of Oracle Support.

Note:

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.

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
Managing Common Services and Certificate Validation 3-7

Managing Certificate Validation and Revocation

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.

3-8 Administrator's Guide for Oracle Access Management

Managing Certificate Validation and Revocation

5.

Proceed to "Enabling OCSP Certificate Validation".
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.

Note:

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.

Managing Common Services and Certificate Validation 3-9

Managing Certificate Validation and Revocation

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



/scratch/maymaria/installed/wlsHome/user_projects/
domains/base_domain/config/fmwconfig/amcrl.jar
/scratch/maymaria/installed/wlsHome/user_projects/
domains/base_domain/config/fmwconfig/amtruststore
jks
false
false
false


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)

3-10 Administrator's Guide for Oracle Access Management

Managing Certificate Validation and Revocation

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.

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))

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.

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",

Managing Common Services and Certificate Validation

3-11

Managing Certificate Validation and Revocation

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





false
...


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.


emailAddress=sagar@pspl.com,CN=ps2436,OU=OBLIX-QA,O=PSPL,
L=PUNE,ST=MAHA,C=MY


■

(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.

3-12 Administrator's Guide for Oracle Access Management

Managing Certificate Validation and Revocation

Table 3–5

Configuration

OCSP
CRL Configuration JDK/OAM OCSP
Configuration
(certpathvalidationo (certpathvalidation Configuration
(useJDKOCSP)
crlenabled)
cspenabled)

No OCSP Checking

False

False

False

True

True/False

False

Simple certificate validation
is performed during OAM
X-509 authentication
OAM OCSP
X-509 authentication
performs certificate
validation with OCSP
checking using the new
OAM OCSP Checker.
JDK OCSP

(does not matter)

True

True

True

X-509 authentication
performs certificate
validation with OCSP
checking using the JDK
OCSP Checker.

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.

Managing Common Services and Certificate Validation

3-13

Managing Certificate Validation and Revocation

3-14 Administrator's Guide for Oracle Access Management

4
Delegating Administration
4

[5Delegating
]
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 Administration

4-1

Delegating the Identity Store

Administrator can create and edit Resources, Authentication Policies and
Authorization Policies. These rights are scoped to one or more Application Domains.
Only the System Administrator can assign roles to users; users
cannot further delegate that role to others.

Note:

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.
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.

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.

4-2 Administrator's Guide for Oracle Access Management

Using the Container Security Framework and MBeans

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:

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.
Roles can be assigned only to users or groups from the
system/default store.

Note:

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.
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.

Note:

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

Delegating Administration

4-3

Using the Remote Registration Utility

■

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."

4-4 Administrator's Guide for Oracle Access Management

5
Managing Data Sources
5

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.

[6]

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.

Managing Data Sources

5-1

About the Data Sources

Table 5–1 (Cont.) Data Sources for Oracle Access Management
Data Source

Description

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 contains the Oracle Access Management services and links to information
about the data sources used for each.
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:

Identity Federation

■

"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 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"

5-2 Administrator's Guide for Oracle Access Management

About the Data Sources

Table 5–2 (Cont.) Data Sources for Oracle Access Management Services
Service

Description

Security Token Service

Mobile and Social

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 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

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):

11.1.1.3

Managing Data Sources

5-3

Registering and Managing User Identity Stores

2


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
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:

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.
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.

Note:

5-4 Administrator's Guide for Oracle Access Management

Registering and Managing User Identity Stores

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.
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.

Note:

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:

Managing Data Sources

5-5

Registering and Managing User Identity Stores

■

■

■

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.
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.
Note:

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."

5-6 Administrator's Guide for Oracle Access Management

Registering and Managing User Identity Stores

–

■

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
There is no way to flush a user's group memberships
information to force Oracle Access Management to recalculate it at a
later date.

Note:

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.

Managing Data Sources

5-7

Registering and Managing User Identity Stores

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

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.

5-8 Administrator's Guide for Oracle Access Management

Registering and Managing User Identity Stores

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.

Managing Data Sources

5-9

Registering and Managing User Identity Stores

Table 5–4 (Cont.) User Identity Store Elements
Elements

Description

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=

■

javax.net.ssl.keyStore=keystore.p12

■

javax.net.ssl.keyStoreType=pkcs12

■

javax.net.ssl.keyStorePassword=

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.

5-10 Administrator's Guide for Oracle Access Management

Registering and Managing User Identity Stores

Table 5–4 (Cont.) User Identity Store Elements
Elements

Description

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.

Group Cache Size

Integer for the group cache size.

Default: true

Default: 10000
Group Cache
Time-to-Live (seconds)

Integer (in seconds) for Time to Live for group cache elements.

Connection Details

Description

Minimum Pool Size

The smallest size set for the connection pool.

Default: 0

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

Managing Data Sources 5-11

Registering and Managing User Identity Stores

Table 5–4 (Cont.) User Identity Store Elements
Elements

Description

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.

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

See Also: Details about classifying users in Chapter 25, "Managing
Policies to Protect Resources and Enable SSO"

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

5-12 Administrator's Guide for Oracle Access Management

Registering and Managing User Identity Stores

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.

Test Connection: 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 Data Sources 5-13

Managing the Identity Directory Service User Identity Stores

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.
You cannot delete the Default Store or System Store
registration.

Note:

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

5-14 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

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
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.

Note:

Figure 5–3 is a screen capture of the Identity Directory Service console page.

Managing Data Sources 5-15

Managing the Identity Directory Service User Identity Stores

Figure 5–3 Identity Directory Service Console Page

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.

Note:

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)

5-16 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

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 Data Sources 5-17

Managing the Identity Directory Service User Identity Stores

Figure 5–4 Create IDS Profile Page

4.

Provide the following values for the new Identity Directory Service profile.

5-18 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

■
■

5.

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.

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 Test
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 Data Sources 5-19

Managing the Identity Directory Service User Identity Stores

Follow this procedure to add the SSL certificates required for
setting the TLS connection.

Note:
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

■

■

■

■

6.

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.

Configure the User properties to configure the LDAP User object in Mobile and
Social User Profile services.
Note: These fields are read-only if using an existing Identity
Directory Service connection.

■

■

■

■

■

7.

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.

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.

5-20 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

■

■

■

8.

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.

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 Data Sources 5-21

Managing the Identity Directory Service User Identity Stores

■

■

–

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.

5-22 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

–

■

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.

–

■

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.

*

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 Data Sources 5-23

Managing the Identity Directory Service User Identity Stores

■

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.

5-24 Administrator's Guide for Oracle Access Management

Managing the Identity Directory Service User Identity Stores

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.

Managing Data Sources 5-25

Understanding Administrator Roles

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

5-26 Administrator's Guide for Oracle Access Management

Understanding Administrator Roles

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).

Managing Data Sources 5-27

Understanding Administrator Roles

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.
2.

3.

4.

5.

Search the System Store to find configured administrators.

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.

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.

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.

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.

5-28 Administrator's Guide for Oracle Access Management

Managing the Policy and Session Database

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.
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:

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
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

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).
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.

Note:

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.

Managing Data Sources 5-29

Managing the Policy and Session Database

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.
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management

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.
In this rare instance, Oracle recommends that you carefully
edit oam-config.xml as described in Step 2f.

Note:

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:

5-30 Administrator's Guide for Oracle Access Management

Introduction to Oracle Access Management Keystores


jdbc:oracle:thin://amdb.example.
com:2001/AM
amuser
password
jdbc/oamds


To:

jdbc:oracle:thin://amdb.example.
com:2001/AM
amuser
password
jdbc/oamsession

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.

Managing Data Sources 5-31

Introduction to Oracle Access Management Keystores

Table 5–5

Access Manager Keys and Storage

Keys and Storage
Access Manager
Cryptographic keys

Description
■

One global shared secret key used by all your 10g Webgates
■

Key storage

One per agent secret key shared between 11g Webgate and OAM Server

■

■

One OAM Server key
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.

Keystores are not accessible using the Oracle Access Management Console. You can
manage keystores and certificates as described in Appendix C, "Securing
Communication".
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

■

5.6.2 About Access Manager Keystores
Table 5–6 provides a summary of keystores used for Access Manager.
Table 5–6

Keystores for Access Manager and Security Token Service

Keystore

Description

System Keystore / Partner
Keystore

The container for keys and certificates associated with OAM
Server instances (OAM secret keys and Security Token Service
private keys for signing and encryption).

.oamkeystore

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"

5-32 Administrator's Guide for Oracle Access Management

Introduction to Oracle Access Management Keystores

Table 5–6 (Cont.) Keystores for Access Manager and Security Token Service
Keystore

Description

Trust Keystore

The Trust Keystore is used to validate keys and certificates
presented by clients to establish trust in entities interacting
with OAM Server instances.

amtrustkeystore

$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:
■

■

Certificate Revocation Lists
(CRL)
amcrl.jar

"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 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:
■

■

Oracle WSM Agent Keystore
default-keystore.jks

"Managing Certificate Validation and Revocation" on
page 3-7
"Managing Certificate Revocation Lists" on page 44-10

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.

Managing Data Sources 5-33

Integrating a Supported LDAP Directory with Oracle Access Manager

Table 5–6 (Cont.) Keystores for Access Manager and Security Token Service
Keystore

Description

.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.

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.
See Also:
■

■

"About Communication Between OAM Servers and WebGates" on
page 6-4
"Defining Keystore Settings for Federation" on page 39-4

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

5-34 Administrator's Guide for Oracle Access Management

Integrating a Supported LDAP Directory with Oracle Access Manager

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.

Managing Data Sources 5-35

Integrating a Supported LDAP Directory with Oracle Access Manager

5-36 Administrator's Guide for Oracle Access Management

6
Managing Server Registration
6

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.

[7]

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 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.

Note:

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.

Managing Server Registration 6-1

Understanding OAM Server Registration and 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.
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management.

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
See Also: Table 1–3 for a comparison of Access Manager 11g versus
Oracle Access Manager 10g.

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.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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

6-2 Administrator's Guide for Oracle Access Management

Understanding OAM Server Registration and Management

–
■

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.
See Also: "About 11g SSO, Legacy 10g SSO in Combination with
OSSO 10g"

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).
An Access Manager 11g ObSSOCookie created by OAM Proxy
is compatible with the 10g ObSSOCookie created by Access Server.

Note:

For more information, see "OAM Proxy Settings" on page 6-6.

Managing Server Registration 6-3

Understanding OAM Server Registration and 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.
See Also:

Appendix C, "Securing Communication"

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.
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.

6-4 Administrator's Guide for Oracle Access Management

Managing Individual OAM Server Registrations

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.
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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.

Managing Server Registration 6-5

Managing Individual OAM Server Registrations

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

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)
For Access Clients, Access Manager 11g provides
authentication and authorization functionality only. Policy
modification through Access Clients is not supported.

Note:

OAM Proxy settings are documented in Table 6–3.
Table 6–3

OAM Proxy Settings for an Individual OAM Server

OAM Proxy Setting
Port

Value
The unique port on which this OAM Proxy instance is listening.
On a default installation, the port is 5575.

6-6 Administrator's Guide for Oracle Access Management

Managing Individual OAM Server Registrations

Table 6–3 (Cont.) OAM Proxy Settings for an Individual OAM Server
OAM Proxy Setting

Value

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.

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.
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.

Managing Server Registration 6-7

Managing Individual OAM Server Registrations

Table 6–4 (Cont.) Default Coherence Settings for Individual OAM Servers
Coherence
Module

Type of Entry

Description and Default Values

LogLimit

String

The Coherence log limit

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.
Note: Each OAM Server must be registered to communicate with
agents.

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.

6.

On the Create: OAM Server page, enter details for your instance, as described in
Table 6–2:
■

Server name

■

Host

■

Port

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)
See Also:

7.

Appendix C if you are using Simple or Cert mode

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.
See Also:

"Using Coherence" on page E-29

6-8 Administrator's Guide for Oracle Access Management

Managing Individual OAM Server Registrations

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.
See Also:
■

■

Oracle Fusion Middleware Installation Guide for Oracle Identity
and Access Management
"About the OAM Server Registration Page" on page 6-5

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.
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

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.
See Also:

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.
See Also:

7.

Appendix C if you are using Simple or Cert mode

"Using Coherence" on page E-29

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.

Managing Server Registration 6-9

Managing Individual OAM Server Registrations

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.

6-10 Administrator's Guide for Oracle Access Management

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

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).
[8]

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-1

Logging Component Event Messages

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.
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.

Note:

Oracle Access Management makes use of the files in Table 7–1.
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.
Logged information is stored in the following location:

Log File

$DOMAIN_HOME/servers/SERVER-NAME/logs/
SERVER-NAME-diagnostics.log

Oracle Access Management uses the WebLogic container's logging defaults in
Table 7–2.
Table 7–2

Logging Defaults
Description

Events

The following events are logged automatically:
■
■

Levels

OAM Server events (managed run-time servers)
Administrative events (generated for configuration changes made
using the console)

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).

For more information, see:
■

About Component Loggers

■

Sample Logger and Log Handler Definition

■

About Logging Levels
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

7-2 Administrator's Guide for Oracle Access Management

Logging Component Event Messages

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

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"

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-3

Logging Component Event Messages

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.

7.2.2 Sample Logger and Log Handler Definition
This topic provides a sample for Access Manager only.
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.

Note:

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











7-4 Administrator's Guide for Oracle Access Management

Configuring Logging for 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.

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
 in the file logging.xml with the following format:


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:
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)

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.
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.

Note:

7.3 Configuring Logging for Access Manager
This section describes tasks for only Access Manager.

Logging Component Event Messages

7-5

Configuring Logging for Access Manager

See Also: "Configuring Logging for Security Token Service and
Identity Federation"

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.
Note:

Use the WLST command help("fmw diagnostics").

See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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
| 
oracle.oam.admin.foundation.configuration
| 
oracle.oam.agent-default
| 
oracle.oam.audit
| 
oracle.oam.binding
| 
oracle.oam.commonutil
| 
oracle.oam.config
| 
oracle.oam.controller
| 
oracle.oam.default
| 

7-6 Administrator's Guide for Oracle Access Management

Configuring Logging for Access Manager

oracle.oam.diagnostic
oracle.oam.engine.authn
oracle.oam.engine.authz
oracle.oam.engine.policy
oracle.oam.foundation.access
oracle.oam.idm
oracle.oam.idm
oracle.oam.idm
oracle.oam.user.identity.provider
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
| 
oracle.oam.admin.foundation.configuration
| 
oracle.oam.agent-default
| 
oracle.oam.audit
| 
oracle.oam.binding
| 
oracle.oam.commonutil
| 
oracle.oam.config
| 
oracle.oam.controller
| TRACE:32
oracle.oam.default
| 
oracle.oam.diagnostic
| 
oracle.oam.engine.authn
| 
oracle.oam.engine.authz
| 
oracle.oam.engine.policy
| 
oracle.oam.foundation.access
| 
oracle.oam.idm
| 
oracle.oam.idm
| 
oracle.oam.idm
| 
oracle.oam.user.identity.provider
| 

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.
Logging Component Event Messages

7-7

Configuring Logging for Security Token Service and Identity Federation

Note: Use the WLST command help("fmw diagnostics") to get
more information.

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
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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:

7-8 Administrator's Guide for Oracle Access Management

Configuring Logging for Security Token Service and Identity Federation

■

■

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.
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

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
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

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:









3.

Save the file.

4.

Proceed with "Defining Log Level and Log Details for Security Token Service or
Identity Federation".

Logging Component Event Messages

7-9

Configuring Logging for Security Token Service and Identity Federation

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.
Note:

Use the WLST command help("fmw diagnostics").

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
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

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.

7-10 Administrator's Guide for Oracle Access Management

Validating Run-time Event Logging Configuration

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.

Logging Component Event Messages 7-11

Validating Run-time Event Logging Configuration

7-12 Administrator's Guide for Oracle Access Management

8
Auditing Administrative and Run-time Events
8

[9In
]
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

Auditing Administrative and Run-time Events 8-1

Understanding Oracle Access Management Auditing

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:

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.
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:

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.
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.

Note:

8-2 Administrator's Guide for Oracle Access Management

Understanding Oracle Access Management Auditing

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.
See Also:
■

"Access Manager Events You Can Audit" on page 8-6

■

"Security Token Service Events You Can Audit" on page 8-16

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.
The preferred mode in production environments is writing
audit records to a stand-alone RDBMS database for audit data only.

Note:

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

Auditing Administrative and Run-time Events 8-3

Understanding Oracle Access Management Auditing

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

See Also:
■

■

"Configuring and Managing Auditing" in the Oracle Fusion
Middleware Application Security Guide
"Setting Up the Audit Database Store" on page 8-21

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
8-4 Administrator's Guide for Oracle Access Management

Understanding Oracle Access Management Auditing

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.
See Also: Using Audit Analysis and Reporting in the Oracle Fusion
Middleware Security Guide

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.
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

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,

Auditing Administrative and Run-time Events 8-5

Access Manager Events You Can Audit

MessageText, ECID, RID ContextFields, SessionId, TargetComponentType,
ApplicationName, and EventCategory.
See Also: The topic on audit logs in the chapter on configuring and
managing auditing in the Oracle Fusion Middleware Security Guide

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
See Also:
■

Identity Federation Events You Can Audit on page 8-14

■

Security Token Service Events You Can Audit on page 8-16

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.
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.
Note:

Table 8–2

Access Manager Administrative Audit Events

Administrative Event
Oracle Access Management Console Login
success/failure

Authentication Policy Creation

Authentication Policy Modification

8-6 Administrator's Guide for Oracle Access Management

Event Data Include
■

User name

■

Remote IP

■

Roles

■

Policy name

■

Authentication scheme details

■

Resource details

■

Policy type (authentication or authorization)

■

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

Table 8–2 (Cont.) Access Manager Administrative Audit Events
Administrative Event

Event Data Include

Authentication Policy Removal

■

Policy name

■

Authentication scheme details

■

Resource details

■

Policy type (authentication or authorization

■

Resource name

■

URI

■

Operation

■

Resource type

■

Resource name

■

URI

■

Operation

■

Resource type

■

Old Resource name

■

Old URI

■

Old Operation

■

Resource name

■

URI

■

Operation

■

Resource type

■

Scheme name

■

Authentication modules

■

Level

■

Scheme name

■

Authentication modules

■

Level

■

Old Scheme name

■

Old Authentication modules

■

Old Level

■

Scheme name

■

Authentication modules

■

Level

■

Response name

■

Response key

■

Data source

■

Response Type

■

Response name

■

Response key

■

Data source

■

Response Type

■

Old Response name

■

Old Response key

■

Old Data source

■

Response name

■

Response key

■

Data source

■

Response Type

Resource Creation

Resource Modification

Resource Removal

Authentication Scheme Creation

Authentication Scheme Modification

Authentication Scheme Removal (Delete)

Response Creation

Response Modification

Response Removal (Delete)

Auditing Administrative and Run-time Events 8-7

Access Manager Events You Can Audit

Table 8–2 (Cont.) Access Manager Administrative Audit Events
Administrative Event

Event Data Include

Partner Addition

■

Partner name

■

Partner ID

■

Partner URL

■

Logout URL

■

Partner name

■

Partner ID

■

Partner URL

■

Logout URL

■

Old Partner name

■

Old Partner URL

■

Old Logout URL

■

Partner name

■

Partner ID

■

Partner URL

■

Logout URL

■

Condition Name

■

Condition type

■

Condition data

■

Condition Name

■

Condition type

■

Condition data

■

Old Condition name

■

Old Condition type

■

Old Condition data

■

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

Partner Modification

Partner Removal

Conditions creation

Conditions Modification

Conditions Removal

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.

8-8 Administrator's Guide for Oracle Access Management

Access Manager Events You Can Audit

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.
Note:

Table 8–3

Access Manager Run-time Audit Events

Run-time Event

Issued When

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.

Authentication
Success

Authentication
Failure

Session Creation

Session Destroy

Event Details Include

A client submits credentials and credential
validation is successful.

A client submits credentials and credential
validation fails.

Authentication succeeds.

Authentication succeeds.

■

Remote IP

■

Resource ID

■

Partner ID

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Remote IP

■

User Name

■

User DN

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Partner ID

■

Remote IP

■

User Name

■

User DN

■

Resource ID

■

Authentication Scheme ID

■

Failure Error Code

■

Retry count

■

Authentication Policy ID

■

Partner ID

■

SSO Session ID

■

User Name

■

User DN

■

Remote IP

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

SSO Session ID

■

User Name

■

User DN

■

Partner ID

Auditing Administrative and Run-time Events 8-9

Access Manager Events You Can Audit

Table 8–3 (Cont.) Access Manager Run-time Audit Events
Run-time Event

Issued When

Login success

A client finishes the login procedure and it
is forwarded to the agent.

Login failure

Logout success

Logout failure

Credential
Collection

Credential Submit

Authorization
Success

Authorization
Failure

Server Start Up

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.

A client finishes the logout procedure and
is forwarded to the agent.

A client fails to logout.

A client is redirected to the credential
collection page.

A client submits credentials.

A client has been authorized to access a
resource.

A client has not been authorized to access a
resource.

The server starts up.

8-10 Administrator's Guide for Oracle Access Management

Event Details Include
■

Remote IP

■

User Name

■

User DN

■

Authentication level

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Partner ID

■

Remote IP

■

User Name

■

Authentication level

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Partner ID

■

Remote IP

■

User DN

■

Authentication level

■

SSO Session ID

■

Partner ID

■

Remote IP

■

User DN

■

SSO Session ID

■

Failure details

■

Partner ID

■

Remote IP

■

Resource Name

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Remote IP

■

User Name

■

Resource ID

■

Authentication scheme ID

■

Authentication Policy ID

■

Remote IP

■

User DN

■

Resource ID

■

Authorization Policy ID

■

Remote IP

■

User DN

■

Resource ID

■

Authorization Policy ID

■

Date and time

■

Instance Name

■

Application Name

■

User Name

Mobile and Social Events You Can Audit

Table 8–3 (Cont.) Access Manager Run-time Audit Events
Run-time Event

Issued When

Event Details Include

Server Shut Down

The server shuts down.

■

Date and time

■

Instance Name

■

Application Name

■

User Name

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
Oracle recommends that you avoid auditing, logging, or
tracing sensitive user attributes, such as user passwords.

Note:

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.

Auditing Administrative and Run-time Events 8-11

Mobile and Social Events You Can Audit

Table 8–4

REST Run-Time Audit Events

Run-time Event

Issued When

Partner Security Validation
Event

Partner credentials are
validated using the
appropriate security
mechanism. The event is
logged for both success and
failure scenarios.

Event Details Include
■

■

Remote IP

■

Security Mechanism

■

■

Create Token

Terminate Token

Get Token

A token is created.

A token is terminated.

A token is obtained/read.

Partner ID (or any unique
partner var)

Service Instance
(Endpoint or name)
Event Status
(success/fail)

■

Event Status

■

Caller Attribute

■

Subject Attribute

■

Filter Subject Attribute

■

Token Attribute

■

Opcode Attribute

■

Message Text

■

Event Status

■

Caller Attribute

■

Subject Attribute

■

Filter Subject Attribute

■

Token Attribute

■

Opcode Attribute

■

Message Text

■

Event Status

■

Caller Attribute

■

Subject Attribute

■

Filter Subject Attribute

■

Token Attribute

■

Opcode Attribute

■

Message Text

8.4.2 Mobile and Social Audit Events
You can audit the runtime events in the following table.
Table 8–5

Mobile and Social Run-Time Audit Events

Run-Time Event

Issued When

IDP Login

A user attempts to log in
using an identity provider

8-12 Administrator's Guide for Oracle Access Management

Event Details Include
■

Event status

■

Application ID

■

Identity provider name

■

Event message

Mobile and Social Events You Can Audit

Table 8–5 (Cont.) Mobile and Social Run-Time Audit Events
Run-Time Event

Issued When

IDP Rest Access

The REST service for identity
providers is accessed

IDP User Profile

The user profile related to a
user authenticated by an
identity provider is obtained

Event Details Include
■

Event status

■

Application ID

■

Protocol

■

Event message

■

Event status

■

Application ID

■

User attributes

■

Identity provider name

■

Local Registration

Security Validation

OpenID Authentication
Request

OAuth Authentication
Request

OAuth Access Token Request

Local Login

A user registers locally by
providing registration info

The security mechanism on
the Identity Provider REST
Services for Relying Party
(RP) is validated
An OpenID authentication
request is initiated

An OAuth authentication
request is initiated

An OAuth access token
request is initiated

User logs in locally

Event message (optional
attributes)

■

Event status

■

User ID

■

First name

■

Last name

■

E-mail

■

Location

■

Time zone

■

Event message

■

Security mechanism

■

Client principal

■

Remote IP address

■

Event message

■

Event status

■

Request ID

■

IDP login URL

■

Request attributes

■

Message text

■

Event status

■

Request ID

■

Return URL

■

IDP attributes

■

Message text

■

Event status

■

Request ID

■

Token

■

Message text

■

Event status

■

Application ID

■

User ID

■

Token

■

Message text

Auditing Administrative and Run-time Events 8-13

Identity Federation Events You Can Audit

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.
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

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–7

Identity Federation Session Management Events

Auditable Events

Auditing Not Supported in This Release for ...

CreateUserSession –

CreateUserFederation –

Creation of a session after a successful login

Creation of a user federation between two remote servers

8-14 Administrator's Guide for Oracle Access Management

Identity Federation Events You Can Audit

Table 8–7 (Cont.) Identity Federation Session Management Events
Auditable Events

Auditing Not Supported in This Release for ...

DeleteUserSession –

UpdateUserFederation -

Deletion of a session after logout

Updating the user federation between two remote servers

CreateActiveUserFederation –

DeleteUserFederation –

Creation of an active federation after
successful login

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

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.
Table 8–8

Protocol Flow Events for Identity Federation

Auditable Events

Auditing Not Supported in This Release for ...

IncomingMessage

AssertionCreation

Message being received by Identity Federation

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)

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.
Table 8–9

Server Configuration Identity Federation

Auditable Events

Auditing Not Supported in This Release for ...

CreateConfigProperty

SetDataStoreType

Adding a new configuration property (Success only) Changing the type of a data store (Success only)
ChangeConfigProperty

ChangeDataStore

Changing the value of an existing configuration
property (Success only)

Setting of the federation data store (Success only)

DeleteConfigProperty
Deleting a configuration property (Success only)

Auditing Administrative and Run-time Events 8-15

Security Token Service Events You Can Audit

Table 8–9 (Cont.) Server Configuration Identity Federation
Auditable Events

Auditing Not Supported in This Release for ...

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)

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.
Table 8–10

Security Events for Identity Federation

Auditable Events

Auditing Not Supported in This Release for ...

CreateSignature

n/a

Creation of a digital signature by Identity
Federation
VerifySignature
Verification of a digital signature by Identity
Federation
EncryptData
Encryption of data by Identity Federation
DecryptData
Decryption of data by 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

8-16 Administrator's Guide for Oracle Access Management

Security Token Service Events You Can Audit

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

■

■
■

■

■

■

Create Validation Template

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.

Audit event recorded for the creation of a Validation Template
referenced by CreateValidationTemplate.
Attributes:

Update Validation Template

■

TemplateID

■

NewSettings

Audit event recorded for the update of a Validation Template
referenced by UpdateValidationTemplate.
Attributes:

Delete Validation Template

■

TemplateID

■

OldSettings

■

NewSettings

Audit event recorded for the delete event of a Validation Template
referenced by DeleteValidationTemplate.
Attributes:

Create Issuance Template

■

TemplateID

■

OldSettings

Audit event recorded for the creation of an Issuance Template
referenced by CreateIssuanceTemplate.
Attributes:
■

TemplateID

■

NewSettings

Auditing Administrative and Run-time Events 8-17

Security Token Service Events You Can Audit

Table 8–11 (Cont.) Security Token Service Configuration Management Operations
Security Token Service
Configuration Operations
Update Issuance Template

Description
Audit event recorded for the update of an Issuance Template
referenced by UpdateIssuanceTemplate.
Attributes:

Delete Issuance Template

■

TemplateID

■

OldSettings

■

NewSettings

Audit event recorded for the delete event of an Issuance Template
referenced by DeleteIssuanceTemplate.
Attributes:

Create Partner Profile

■

TemplateID

■

OldSettings

Audit event recorded for the creation of Partner Profile referenced by
CreatePartnerProfile.
Attributes:

Update Partner Profile

■

ProfileID

■

NewSettings

Audit event recorded for the update of a Partner Profile referenced by
UpdatePartnerProfile.
Attributes:

Delete Partner Profile

■

ProfileID

■

OldSettings

■

NewSettings

Audit event recorded for the delete event of Partner Profile referenced
by DeletePartnerProfile.
Attributes:

Create Partner

■

ProfileID

■

OldSettings

Audit event recorded for the creation of Partner Profile referenced by
CreatePartner.
Attributes:

Update Partner

■

PartnerID

■

NewSettings

Audit event recorded for the update of a Partner Profile referenced by
UpdatePartner.
Attributes:

Delete Partner

■

PartnerID

■

OldSettings

■

NewSettings

Audit event recorded for the delete event of Partner Profile referenced
by DeletePartner.
Attributes:

Generic Admin Creation

■

PartnerID

■

OldSettings

Audit event recorded for the generic create administrative operation
referenced by GenericAdminCreation.
Attributes:
■

SettingsID

■

NewSettings

8-18 Administrator's Guide for Oracle Access Management

Security Token Service Events You Can Audit

Table 8–11 (Cont.) Security Token Service Configuration Management Operations
Security Token Service
Configuration Operations
Generic Admin Update

Description
Audit event recorded for the update of a generic update
administrative operation referenced by GenericAdminUpdate.
Attributes:

Generic Admin Removal

■

SettingsID

■

OldSettings

■

NewSettings

Audit event recorded for generic delete administrative operation
referenced by GenericAdminDeletion.
Attributes:
■

SettingsID

■

OldSettings

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.
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

■

■
■

■

Incoming Message

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 RSTR message received by Security Token Service
referenced by OutgoingMessage.
Attributes populated for this event, if available:

Outgoing Message

■

Requester

■

RelyingParty

■

Message

Outgoing RSTR message received by Security Token Service
referenced by IncomingMessage.
Attributes populated for this event, if available:
■

Requester

■

RelyingParty

■

Message

Auditing Administrative and Run-time Events 8-19

Setting Up Auditing for Oracle Access Management

Table 8–12 (Cont.) Security Token Service-specific Run-time Events
Token Operations

Description

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:

Token Generation

■

Requester

■

RelyingParty

■

Token

■

TokenType

■

TokenContext

■

Status

Audit event for token generation in Security Token Service
referenced by TokenGeneration.
Attributes populated for this event, if available:

LDAP User Authentication

■

Requester

■

RelyingParty

■

Token

■

TokenType

■

TokenContext

■

UserID

Audit event for local user authentication with the LDAP
Directory referenced by LDAPUserAuthentication.
Attributes populated for this event, if available:

Generic Runtime Operation

■

UserID

■

Status

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

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.

8-20 Administrator's Guide for Oracle Access Management

Setting Up Auditing for Oracle Access Management

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.
See Also:
■

■

Oracle Fusion Middleware Application Security Guide for details on
managing the audit store
Oracle Fusion Middleware Repository Creation Utility User's
Guide

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:
■
■

4.

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.

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:











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.

Auditing Administrative and Run-time Events 8-21

Setting Up Auditing for Oracle Access Management

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

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.
See Also:

"Validating Auditing and Reports" on page 8-25

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.

8-22 Administrator's Guide for Oracle Access Management

Setting Up Auditing for Oracle Access Management

Figure 8–2 Common Settings: Auditing Configuration

The Auditing section provides settings for the Log Directory, Filter Settings, and Audit
Configuration Users.
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.

Note:

Table 8–13 describes the elements in the Audit Configuration page.
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 filejps-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 filejps-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.

Auditing Administrative and Run-time Events 8-23

Setting Up Auditing for Oracle Access Management

Table 8–13 (Cont.) Audit Configuration Elements
Elements

Description

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.

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.
Auditable events for each filter preset are fixed in the
read-only component_events.xml file. Editing or customizing this file
is not supported.
Note:

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.

8-24 Administrator's Guide for Oracle Access Management

Validating Auditing and Reports

8.8 Validating Auditing and Reports
Use the following procedure to test your run-time event auditing configuration. Before
you begin:
■

■
■

1.

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.
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.

2.

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.

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.

3.

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.

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.

Auditing Administrative and Run-time Events 8-25

Validating Auditing and Reports

b.
4.

Repeat Steps here to confirm auditing is working.

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.

8-26 Administrator's Guide for Oracle Access Management

9
Logging WebGate Event Messages
9

[10Each
]
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)
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.

Note:

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

Logging WebGate Event Messages 9-1

About Logging, Log Levels, and Log Output

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

Level
LOGLEVEL_
FATAL

Logging Levels
Number of
Events
Reported
> 60

Description
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.

9-2 Administrator's Guide for Oracle Access Management

About Logging, Log Levels, and Log Output

Table 9–1 (Cont.) Logging Levels
Number of
Events
Reported

Level

Description

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.

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.
The Trace and Debug3 level logs can contain sensitive
information. For more information about sensitive information, see
"Filtering Sensitive Attributes" on page 9-26.

Note:

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:

Logging WebGate Event Messages 9-3

About Log Configuration File Paths and Contents

2007/06/01@00:50:56.859000
2007/06/01@00:50:56.859000
2007/06/01@00:50:56.859000
2007/06/01@00:50:56.859000
2007/06/01@00:50:56.859000

5932
5932
5932
5932
5932

2672
2672
2672
2672
2672

DB_RUNTIME
DB_RUNTIME
LDAP
LDAP
LDAP

DEBUG3
TRACE
DEBUG1
TRACE
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"
Connection available^true
"Function entered"

Server^dlsun4072

Port^389

Server Priority^1

_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.
See Also:

"Log Configuration File Contents" on page 9-5

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.

9-4 Administrator's Guide for Oracle Access Management

About Log Configuration File Paths and Contents

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.
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.

Note:

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.
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.
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

Logging WebGate Event Messages 9-5

About Log Configuration File Paths and Contents

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.
See Also:

The log configuration file on your system.

The commented default configuration file is shown here:
Comments can span one or multiple lines. Comments look similar to the following:

-->
-->
-->

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




-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->

About Log Configuration File Paths and Contents





























































Logging WebGate Event Messages 9-7

About Log Configuration File Paths and Contents























































-->



-->

-->

9-8 Administrator's Guide for Oracle Access Management

About Directing Log Output to a File or the System File








-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->

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"

Logging WebGate Event Messages 9-9

Structure and Parameters of the Log Configuration File

on page 9-13 for details.
The log writers are described in Table 9–3.
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.

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

9-10 Administrator's Guide for Oracle Access Management

Structure and Parameters of the Log Configuration File

9.4.1 About The Log Configuration File Header
At the beginning of the log configuration file there is an XML file header:


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:

. . .


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:

. . .


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

Logging WebGate Event Messages 9-11

Structure and Parameters of the Log Configuration File

Table 9–4 (Cont.) Global Parameters in the First Compound List
Parameter

Description

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.

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)












9-12 Administrator's Guide for Oracle Access Management

Structure and Parameters of the Log Configuration File





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:

. . .


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:

. . .


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:


■

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:


■

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:


Logging WebGate Event Messages 9-13

Structure and Parameters of the Log Configuration File

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:


■

A buffer size, as follows:


■

A a file size that determines when a new log file is generated, as follows:


■

A time in minutes that determines the interval at which a new log file is generated,
as follows:


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

9-14 Administrator's Guide for Oracle Access Management

Structure and Parameters of the Log Configuration File

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

xmlns="http://www.oblix.com"
ListName="FILTER_LIST">








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





Example 9–5 Another Valid Name/Value List






Logging WebGate Event Messages 9-15

About Activating and Suppressing Logging Levels

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

Example 9–7 Opening tag for a Name/Value List


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.
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.

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.
9-16 Administrator's Guide for Oracle Access Management

Understanding the Mandatory Log-Handler Configuration Parameters

9.6 Understanding the Mandatory Log-Handler Configuration Parameters
At minimum, each log-handler definition contains five parameters listed in Table 9–6.
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.

If you specify FileLogWriter or MPFileLogWriter as the value for the LOG_WRITER
parameter, the four parameters in Table 9–7 are relevant.

Logging WebGate Event Messages 9-17

Understanding the Mandatory Log-Handler Configuration Parameters

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.

oblog.log

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.
BUFFER_SIZE

Optional. This is the size of the buffer, in bytes, for
logged data as it is being written to the log file.

65535
(64KB)

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.
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

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.

86400

(512KB)

(1 day, in
seconds)

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.

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.

9-18 Administrator's Guide for Oracle Access Management

Understanding the Mandatory Log-Handler Configuration Parameters

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



























Logging WebGate Event Messages 9-19

Understanding the Mandatory Log-Handler Configuration Parameters





















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

9-20 Administrator's Guide for Oracle Access Management

Understanding the Mandatory Log-Handler Configuration Parameters

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

Logging WebGate Event Messages 9-21

Configuring Different Threshold Levels for Different Types of Data

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:


. . .


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:





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.

9-22 Administrator's Guide for Oracle Access Management

Configuring Different Threshold Levels for Different Types of Data

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.




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.

Logging WebGate Event Messages 9-23

Configuring Different Threshold Levels for Different Types of Data

Table 9–8 (Cont.) ParamName Values You Can Configure for Per-Module Logging
ParamName Value

Logging Threshold That This Parameter Sets

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:




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.

9-24 Administrator's Guide for Oracle Access Management

Configuring Different Threshold Levels for Different Types of Data

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:



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:


You can specify multiple ValNamePair elements within the ValNameList.
A complete per-module logging threshold section is illustrated in bold in the
following example:









. . .


-->

-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->

Logging WebGate Event Messages 9-25

Filtering Sensitive Attributes





-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->








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.
Each value added to FILTER_LIST increases the runtime cost
of using Secure Logging.

Note:

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.
See Also:

1.

■

"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

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:

9-26 Administrator's Guide for Oracle Access Management

Filtering Sensitive Attributes

a.

Confirm that secure logging is active. For example:




b.

Locate the FILTER_LIST parameter at the end of the file. For example:







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:



For testing, set the LOG_THRESHOLD_LEVEL and LOG_SECURITY_
THRESHOLD_LEVEL to TRACE. See Step 6a.

Note:

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:



...




e.
3.

Save the oblog_config_wg.xml file.

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:

...




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:

...

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:



5.

Repeat Steps 1 through 6 for each component in your deployment with one or
more masked attributes.

9-28 Administrator's Guide for Oracle Access Management

10
Reporting
10

[1Oracle
]
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
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.

Note:

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

Reporting 10-1

Accessing Oracle Access Management Reports

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

10-2 Administrator's Guide for Oracle Access Management

Reports for Access Manager

■

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.
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

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–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

Reporting 10-3

Reports for Access Manager

10.4.2.2 AuthenticationFromIPByUser
This report contains details regarding failed and successful authentications from a
particular IP address.
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

10.4.2.3 AuthenticationPerIP
This report contains details regarding failed and successful authentications 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)

10.4.2.4 AuthenticationStatisticsPerServer Report
This report contains details regarding failed and successful authentications from a
particular server instance.
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

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.
10-4 Administrator's Guide for Oracle Access Management

Reports for Access Manager

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

10.4.3.2 Authentication Failures
This report contains details regarding failed and successful authentications.
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

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.
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

10.4.3.5 Authorization History
This report contains details regarding failed and successful authorizations.

Reporting 10-5

Creating Reports Using Third-Party Software

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

10.4.3.6 Multiple Logins From Same IP
This report contains details regarding multiple logins from the same IP address.
Table 10–10

Multiple Logins From Same IP Report Fields

Field

Description

IP Address

IP address

Usernames Used

Identifiers of users

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.

10-6 Administrator's Guide for Oracle Access Management

11
Monitoring Performance and Health
11

[12Monitoring
]
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
See Also:
■

Chapter 12 if you are using Oracle Enterprise Manager Fusion
Middleware Control

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.

Monitoring Performance and Health

11-1

Monitoring Server Metrics Using Oracle Access Management Console

■

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.
3.

Proceed to "Reviewing Server Metrics."

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.

11-2 Administrator's Guide for Oracle Access Management

Monitoring Server Metrics Using Oracle Access Management Console

Figure 11–1 Server Processes Overview Page

Server Processes Overview provides the following OAM Server events, organized in
individual columns on the 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

Figure 11–2 shows the Session Operations tab.

Monitoring Performance and Health

11-3

Monitoring Server Metrics Using Oracle Access Management Console

Figure 11–2 OAM Server Metrics: Session Operations Monitoring Page

OAM Server Session Operations metrics include:
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

Figure 11–3 shows the Server Operations tab.

11-4 Administrator's Guide for Oracle Access Management

Monitoring Server Metrics Using Oracle Access Management Console

Figure 11–3 OAM Server Metrics: Server Operations Tab

OAM Server Operations metrics include those in Table 11–3.
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

Figure 11–4 shows the OAM Server Metrics: WebGates tab with all available metrics
showing.

Monitoring Performance and Health

11-5

Monitoring SSO Agent Metrics Using Oracle Access Management Console

Figure 11–4 OAM Server Metrics: WebGates Tab

WebGate performance metrics include:
■

Agent Name

■

Agent Status

■

Version

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

11-6 Administrator's Guide for Oracle Access Management

Monitoring SSO Agent Metrics Using Oracle Access Management Console

■

Operations Detail

■

Information
See Also: Oracle Fusion Middleware Performance and Tuning
Guide

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

Monitoring Performance and Health

11-7

Monitoring SSO Agent Metrics Using Oracle Access Management Console

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.

11-8 Administrator's Guide for Oracle Access Management

Monitoring SSO Agent Metrics Using Oracle Access Management Console

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

Monitoring Performance and Health

11-9

Introduction to OAM Proxy Metrics and Tuning

11.4 Introduction to OAM Proxy Metrics and Tuning
This section provides the following topics:
■

About OAM Proxy Metrics

■

OAM Proxy Server Tuning Parameters
See Also:
■

"OpenSSO Proxy Events and Metrics: Server" on page 11-13

■

Oracle Fusion Middleware Performance and Tuning Guide

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.
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 Count of how many Peer Compatibility Check Failures have
ount
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 Number of active threads doing security mode negotiation
ve

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.
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.

Note:

Table 11–5 provides the tuning parameters for the OAM Proxy.
11-10 Administrator's Guide for Oracle Access Management

Monitoring Metrics Using the DMS 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

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:// /oracle_common/bin/orapki wallet add
-wallet $DOMAIN_HOME/output/$Agent_Name/cwallet.sso -trusted_cert
-cert  -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
See Also:

"About Run Time Resource Evaluation" on page 25-26

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.
Configuring Access Manager Settings 13-9

Managing Run Time Policy Evaluation Caches

Figure 13–4 Common Policy Evaluation Caches

Table 13–8 outlines these global settings that apply to all servers and requests.
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:

Authorization Result Cache

■

Maximum Size 100000

Zero disables the cache

■

Time to Live (seconds) 3600

Zero disables Time to Live

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

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.
See Also:

Guide

■

Oracle Fusion Middleware High Availability Guide

■

Oracle Fusion Middleware Performance and Tuning Guide

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).

13-10 Administrator's Guide for Oracle Access Management

14
Introduction to Agents and Registration
14

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 Agents and Registration

14-1

Introduction to Policy Enforcement Agents

Table 14–1

Agent Types

Agent Type

Description

OAM Agents

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:

Note: Unless explicitly
stated, the terms Webgate
and Access Client are used
interchangeably.

■

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_
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

■

IAMSuiteAgent
a Pre-registered OAM 10g
Agent

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.

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:

14-2 Administrator's Guide for Oracle Access Management

Introduction to Policy Enforcement Agents

Table 14–1 (Cont.) Agent Types
Agent Type

Description

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 introduces Access Manager features that support agent registration,
configuration, management, and single-sign on. Links to topics providing more
information are included.
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.

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"

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.

Table 14–3 provides run time processing information for OAM Agents.
See Also:

"Understanding Credential Collection and Login"

Introduction to Agents and Registration

14-3

Introduction to Policy Enforcement Agents

Table 14–3

Run Time Processing Overview for Access Manager

Agent Type

Description

11g WebGates

After installation and registration, 11g WebGates communicate with Access Manager
using the OAM Proxy to "sanitize" the request and respond identically for all agents.

11g Access Clients

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.

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

14-4 Administrator's Guide for Oracle Access Management

Introduction to Agent Registration

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.
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"

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

Introduction to Agents and Registration

14-5

Introduction to Agent Registration

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.
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:

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.
You can register multiple WebGates or Access Clients under a
single host identifier, with the same Application Domain and policies,
as follows:

Note:

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.

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.
Table 14–4

Keys and Policies Generated During Agent Registration

Keys and Policies

Accessible to

One key per 11g WebGate Agent

■

OAM Server

One key for all 10g Agents

Accessible through
■

■

One key per OpenSSO Agent stored in
local Agent bootstrap file

Client-side: Secure local storage
on the client host (a local wallet
file)
Server side: The Java Keystore

One key per OSSO Agent
See Also: "About Key Use, Generation,
Provisioning, and Storage" on page 15-27
Partner key for the application

■

11g WebGate

Client-side

Administrators can view, modify, or
remove a registered agent using either
the Oracle Access Management
Console or custom WLST commands
for Access Manager

Oracle Access Management Console
Policy Configuration
Application Domains
DomainName

(None for OpenSSO Agents)
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

■

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

14-6 Administrator's Guide for Oracle Access Management

Introduction to Agent Registration

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.
Table 14–5

Artifacts Associated with Agent Registration

Registration Artifact

Generated for ...

All WebGates or Access Client

All WebGates/Access Clients on the console host (AdminServer).

ObAccessClient.xml

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 WebGates, regardless of the transport security mode.

11g WebGate only
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"

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–6

Copying Generated Artifacts

Agent Type & Artifacts

Copy Generated Artifacts to Agent Installation Directory ...

ObAccessClient.xml

Before agent startup, copy the ObAccessClient file (and cwallet.sso) from the
generated location (AdminServer (Console) host) to the agent installation directory.

(and 11g WebGate cwallet.sso)

See: Chapter 15, "Registering and Managing OAM 11g Agents"
11g WebGate or Access Client
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 Agents and Registration

14-7

Introduction to Remote Registration

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.
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.

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.
Registration of legacy Agents (10g WebGate, OpenSSO, and
OSSO 10g) is also supported.

Note:

Table 14–8 describes functionality that is not 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

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.

14-8 Administrator's Guide for Oracle Access Management

Introduction to Remote Registration

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.
■

■

■

2.

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).

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.

3.

–

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.

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 Agents and Registration

14-9

Introduction to Remote Registration

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.
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.
See Also:
■
■

"Updating Agent Configuration Files" on page 14-10
"Understanding the Remote Registration Tool, Modes, and
Process" on page 15-24

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.
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"

14-10 Administrator's Guide for Oracle Access Management

15
Registering and Managing OAM 11g Agents
15

[14This
]
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"

Registering and Managing OAM 11g Agents 15-1

Understanding OAM Agent Registration Parameters in the Console

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.

15-2 Administrator's Guide for Oracle Access Management

Understanding OAM Agent Registration Parameters in the Console

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

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.

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:

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 User-Defined WebGate Parameters" on page 15-5.

See Also: "About Virtual Web Hosting" on page 22-10.

Registering and Managing OAM 11g Agents 15-3

Understanding OAM Agent Registration Parameters in the Console

Table 15–1 (Cont.) Elements on Create Pages for 11g and 10g OAM Agents
OAM WebGate Element

Description

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

15-4 Administrator's Guide for Oracle Access Management

Understanding OAM Agent Registration Parameters in the Console

Table 15–1 (Cont.) Elements on Create Pages for 11g and 10g OAM Agents
OAM WebGate Element

Description

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
/myfinancial
/**

yields Resource URL /financial/**
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"

To help streamline WebGate registration, some elements are concealed during the
create operation and default values are applied.
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.

Note:

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.

Registering and Managing OAM 11g Agents 15-5

Understanding OAM Agent Registration Parameters in the Console

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

15-6 Administrator's Guide for Oracle Access Management

Understanding OAM Agent Registration Parameters in the Console

Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter

Description

serverRequestCacheType

Authentication post-data preservation parameter by the embedded credential collector
(ECC).

ECC Only

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:
"" in its web.xml, the Agent validates the incoming request.
If the application does not specify 'CLIENT-CERT' as part of the construct:
"" in its web.xml, the Agent does not validate the incoming request.
Instead, the Agent lets the request go through to the application.

Registering and Managing OAM 11g Agents 15-7

Understanding OAM Agent Registration Parameters in the Console

Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter

Description

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): _
:_
Enabled UniqueCookieNames format (rfc2109-compliant cookie name restriction):
_:_
Disabled: Cookie name format is _. No : and No
_ is added to the cookie name.
Any other value is treated as the default legacy format: _:_


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.

15-8 Administrator's Guide for Oracle Access Management

Understanding OAM Agent Registration Parameters in the Console

Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter
ssoCookie

Description
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.

Registering and Managing OAM 11g Agents 15-9

Understanding OAM Agent Registration Parameters in the Console

Table 15–2 (Cont.) User-Defined WebGate Parameters
User-Defined WebGate Parameter

Description

OAMAuthAuthenticationServiceLoca Activates non-browser client functionality and defines the location of the authentication
tion
service.
11g WebGate non-browser client
functionality

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."

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.

15-10 Administrator's Guide for Oracle Access Management

Understanding OAM Agent Registration Parameters in the Console

■

■

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.
Access Manager now supports Internet Protocol version 6
(IPv6) as well as IPv4.

Note:

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).

Registering and Managing OAM 11g Agents

15-11

Understanding OAM Agent Registration Parameters in the Console

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

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.
Note:

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"

15-12 Administrator's Guide for Oracle Access Management

Registering an OAM Agent Using the Console

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.
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"

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.
Note:

If you are creating an OAM 10g Agent, also see Chapter 30.

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".

Registering and Managing OAM 11g Agents

15-13

Configuring and Managing Registered OAM Agents Using the Console

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:
Agent & Artifacts

Artifacts

11g WebGate/Access Client

From the AdminServer (Console) host:

ObAccessClient.xml and
cwallet.sso
10g WebGate/Access Client
ObAccessClient.xml

$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/

Note: Go to Chapter 30 before To the Agent host:
completing this task.
$10gWG_install_dir/oblix/lib/
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.

15-14 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OAM Agents Using the Console

Figure 15–3 Expanded 11g WebGate Page with Defaults

There are only a few differences between 11g and 10g WebGate registration pages.
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.
Note:

Table 15–3 describes elements on an expanded registration. Additional settings
revealed here are used by the OAM Proxy.

Registering and Managing OAM 11g Agents

15-15

Configuring and Managing Registered OAM Agents Using the Console

Table 15–3

Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages

Element

Description

Name

See: Table 15–1, " Elements on Create Pages for 11g and 10g OAM Agents".

Version
Description
Access Client Password
Security
User-defined Parameters

See Also: "About User-Defined WebGate Parameters" on page 15-5

IP Validation

See Also: "About IP Address Validation for WebGates" on page 15-10.

Primary Cookie Domain

This parameter describes the Web server domain on which the Agent is deployed,
for instance,.example.com.

10g WebGate only, Chapter 30

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

Specifies whether this registration is enabled or disabled.

Only in the console.

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

15-16 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OAM Agents Using the Console

Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element

Description

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.

Registering and Managing OAM 11g Agents

15-17

Configuring and Managing Registered OAM Agents Using the Console

Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element

Description

Idle Session Timeout

Default: 3600

10g WebGate only, Chapter 30

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

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.

10g and 11g WebGates

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)"

15-18 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OAM Agents Using the Console

Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element

Description

Logout Target URL

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.

11g WebGate only

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

These settings apply only to WebGates and control the browser's cache.

Cache Control Header

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.

WebGate only (not Access Clients)

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

Oracle recommends enabling Deny On Not Protected.

WebGates only (not Access Clients)

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

Registering and Managing OAM 11g Agents

15-19

Configuring and Managing Registered OAM Agents Using the Console

Table 15–3 (Cont.) Elements on Expanded 11g and 10g WebGate/Access Client Registration Pages
Element

Description

Allow Credential Collector Operations

Activates WebGate detached credential collector functionality for simple-form or
dynamic multi-factor authentication.

11.1.2.0.0 and later WebGate only

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

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.

10g WebGate only, Chapter 30

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

■

Secondary Server List

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).)

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).)

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).

15-20 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OAM Agents Using the Console

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

Click to open a fresh WebGate registration page.

Create OSSO Agent

Click to open a fresh OSSO Agent registration page.

Create OpenSSO Agent

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.

Version

Choose a WebGate version to narrow the search and results:

(Webgates tab only)

■

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

Choose a state to narrow the search and results:

(Webgates tab only)

■

Enabled

■

Disabled

Primary Server

Enter the entire (or partial with a wild card (*)) Primary Server name.

(Webgates tab only)
Secondary Server

Enter the entire (or partial with a wild card (*)) Secondary Server name.

(Webgates tab only)
Agent ID

Enter the entire (or partial with a wild card (*)) Agent ID value.

(OSSO Agents tab only)

Registering and Managing OAM 11g Agents

15-21

Configuring and Managing Registered OAM Agents Using the Console

Table 15–4 (Cont.) Agent Search Controls
Control

Description

Agent Type

Select the target Agent type:

(OpenSSO Agents tab only)

■

J2EE

■

Web

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 Version All, 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 Version 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:
■

■

■
■

6.

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.

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.)

15-22 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OAM Agents Using the Console

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.

Note:

Before you begin, the agent must be registered and available in the Oracle Access
Management Console.
See Also:
■

1.

About Create OAM WebGate Page and Parameters

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:
Agent & Artifacts

Artifacts

11g WebGate/Access Client

From the AdminServer (Console) host:

ObAccessClient.xml and
cwallet.sso
10g WebGate/Access Client
ObAccessClient.xml

$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config.
From the AdminServer (Console) host:
$DOMAIN_HOME/output/$Agent_Name/

Note: Go to Chapter 30 before To the Agent host
completing this task.
$10gWG_install_dir/oblix/lib/ObAccessClient.xml
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.
Deleting an agent registration removes only the registration
(not the associated host identifier, Application Domain, resources, or
the agent itself).

Note:

Registering and Managing OAM 11g Agents

15-23

Understanding the Remote Registration Tool, Modes, and Process

See Also:
■

Understanding OAM Agent Registration Parameters in the
Console

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.

2.

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.

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

15-24 Administrator's Guide for Oracle Access Management

Understanding the Remote Registration Tool, Modes, and Process

See Also:

"Introduction to Remote Registration" on page 14-8

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.
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.)

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.
Table 15–6

Remote Registration Command Arguments: mode

Arguments

Description

mode

Either:

input/filename.xml

■

inband

■

outofband

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

The sample commands illustrated in Table 15–7 presume the location of the tool to be
$OAM_REG_HOME on a Linux system.
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

Registering and Managing OAM 11g Agents

15-25

Understanding the Remote Registration Tool, Modes, and Process

Table 15–7 (Cont.) Remote Registration Command Samples
Command Type

Sample (on Linux)

[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

After launching the script, Administrators are prompted for a
username and password (unless -noprompt is used as shown in
Table 15–7.)
Note:

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.
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



http://{oam_admin_ser
ver_host}:{oam_admin_server_port}




RREG_OAM



RREG_HostId11G


Extended Templates Only


http://{web_server_
host):(web_server_port}


15-26 Administrator's Guide for Oracle Access Management

Understanding the Remote Registration Tool, Modes, and Process

Table 15–8 (Cont.) Common Elements in Remote Registration Requests
Element

Example



true




RREG_OAM11G




false

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_
_.
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.

Registering and Managing OAM 11g Agents

15-27

Understanding the Remote Registration Tool, Modes, and Process

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).
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.

Note:

■

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).

15-28 Administrator's Guide for Oracle Access Management

Understanding Remote Registration Templates: OAM Agents

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/.
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

For a look at these specialized tasks and templates, see:

Update Agent

■

Create Policies, Update Policies

■

Out-of-band Response

■

"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

Despite being nearly identical for both 10g and 11g WebGates,
be sure to copy and use the appropriate request for your release.

Note:

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.
Note:

Descriptions of elements in Table 15–10 are in Table 15–3.

Registering and Managing OAM 11g Agents

15-29

Understanding Remote Registration Templates: OAM Agents

Table 15–10

Elements in Extended OAM Agent Remote Registration Requests

Element

Example



See Table 15–8, " Common Elements in Remote Registration Requests".












host1
7777

host2
7778






/





/public/index.html






/excluded/index.html





{client_domain}


10g Request Only
In OAMRequest.xml (10g WebGates)
 is also used as preferred HTTP
host


100000




1800



3600


11g Request Only

10g WebGate only, Chapter 30

3600




1



24



3600>


1


-

-1




60



false

15-30 Administrator's Guide for Oracle Access Management

Understanding Remote Registration Templates: OAM Agents

Table 15–10

(Cont.) Elements in Extended OAM Agent Remote Registration Requests

Element

Example



open

1




false/



no-cache




no-cache


0




10,11,11,11
10,11,11,12
10,11,11,13





/logout1.html
/logout2.html




/oam_logout_success


11g Request Only

11g Request Only
User-Defined Parameter Names

end_url

Examples


...
...


MaxPostDataLength



MaxPostDataLength
750000


maxSessionTimeUnits


maxSessionTimeUnits
hours


useIISBuiltinAuthentication


useIISBuiltinAuthentication

false


idleSessionTimeoutLogic


idleSessionTimeoutLogic

leastComponentIdleTimeout



10g WebGates only

URLInUTF8Format


URLInUTF8Format
true


Registering and Managing OAM 11g Agents

15-31

Performing Remote Registration for OAM Agents

Table 15–10

(Cont.) Elements in Extended OAM Agent Remote Registration Requests

Element

Example

inactiveReconfigPeriod


inactiveReconfigPeriod
10


Shared secret applies to only 10g WebGate
Configuration applies to only 11g WebGate.
WaitForFailover


WaitForFailover
-1


proxySSLHeaderVar


proxySSLHeaderVar
IS_SSL


client_request_retry_attempts


client_request_retry_attempts 
1


ContentLengthFor401Response


ContentLengthFor401Response

0


SUN61HttpProtocolVersion


SUN61HttpProtocolVersion

1.0


impersonationCredentials


username:password

cred


UseWebGateExtForPassthrough


UseWebGateExtForPassthrough

false


syncOperationMode


syncOperationMode
false


filterOAMAuthnCookie


filterOAMAuthnCookie
true


11g Request only.

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

15-32 Administrator's Guide for Oracle Access Management

Performing Remote Registration for OAM Agents

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
Oracle Recommends using the latest tool and files by applying
the latest bundle patch and untarring RREG.tar.gz again as described
here.

Note:

For remote registration, two variables are required: JAVA_HOME and OAM_REG_
HOME, as described in Table 15–11.
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
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.
4.

Set OAM_REG_HOME to the exploded_dir_for_RREG.tar/rreg based on your
environment (client side or server side Table 15–11).

Proceed with "Creating Your Remote Registration Request".

Registering and Managing OAM 11g Agents

15-33

Performing Remote Registration for OAM Agents

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:
■
■

4.

Table 15–9, " Remote Registration Request Templates for OAM Agents"
Table 15–10, " Elements in Extended OAM Agent Remote Registration
Requests"

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.
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management chapter "Installing and Configuring
Oracle HTTP Server 11g WebGate for OAM"

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

15-34 Administrator's Guide for Oracle Access Management

Performing Remote Registration for OAM Agents

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.
5.

Restart the OAM Server hosting the agent.

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.

Registering and Managing OAM 11g Agents

15-35

Performing Remote Registration for OAM Agents

Table 15–12

(Cont.) Files Returned by in-band Administrator to out-of-band

File

Description

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

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
See Also: Oracle Fusion Middleware Installation Guide for Oracle
Identity and Access Management chapter "Installing and Configuring
Oracle HTTP Server 11g WebGate for OAM"

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."
See Also: Part VII, "Registering and Using Agents with Access
Manager", if needed.
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

15-36 Administrator's Guide for Oracle Access Management

Introduction to Updating Agents Remotely

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   [prompt_flag] [component.oam.config_file] 
value
Table 15–13

Remote Agent Update Modes and Input Files

Mode and Input Files

Description and Syntax

agentUpdate mode

Allows Administrators to update existing agent attributes, regardless
OAM11GUpdateAgentRequest.xml of agent type:
./bin/oamreg.sh agentUpdate input/*UpdateAgentRequest.xml
OAMUpdateAgentRequest.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

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–14

Delta: OAM Agent Update versus Registration Request

Delta

Element

Adds



Registering and Managing OAM 11g Agents

15-37

Updating Agents Remotely

Table 15–14

(Cont.) Delta: OAM Agent Update versus Registration Request

Delta

Element

Omits





 and application domain-related elements



See Also:
■

Table 15–3, " Elements on Expanded 11g and 10g WebGate/Access
Client Registration Pages"

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."
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

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:

3.

■

OAM11GUpdateAgentRequest.xml

■

OAMUpdateAgentRequest.xml (10g) Chapter 30

■

OSSOUpdateAgentRequest.xml Chapter 29

■

OpenSSOUpdateAgentRequest.xml Chapter 28

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.

15-38 Administrator's Guide for Oracle Access Management

Updating Agents Remotely

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!
Registering and Managing OAM 11g Agents

15-39

Validating Remote Registration and Resource Protection

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.
Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"

See Also:

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

15-40 Administrator's Guide for Oracle Access Management

Validating Remote Registration and Resource Protection

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:
■

■

9.

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.

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.

Registering and Managing OAM 11g Agents

15-41

Replacing the IAMSuiteAgent with an 11g WebGate

Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"

See Also:

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

15-42 Administrator's Guide for Oracle Access Management

Replacing the IAMSuiteAgent with an 11g WebGate

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.
See Also:
■

Chapter 15 for more information about the remote registration
tool, processing, and request files

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.
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.

Note:

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:

http://ruby.uk.example.com:7001
11g4IAM
11g4IAM
false
/oamsso/logout.html
...retain defaults for remaining elements...
...
...


Registering and Managing OAM 11g Agents

15-43

Replacing the IAMSuiteAgent with an 11g WebGate

See Also: "Creating Your Remote Registration Request" on
page 15-34
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.
See Also:

b.

"Searching for an OAM Agent Registration" on page 15-20

Double-click the agent's name to display the registration page and review the
details. For example:
If you install a fresh WebGate, enter matching details during
installation.

Note:

c.

5.

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.

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".

15-44 Administrator's Guide for Oracle Access Management

Replacing the IAMSuiteAgent with an 11g WebGate

Agent & Artifacts

Artifacts

11g WebGate/Access Client

From the AdminServer (Console) host:

ObAccessClient.xml and
cwallet.sso

6.

$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/WebGate/config

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.
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:

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



SetHandler weblogic-handler
WebLogicHost ruby.uk.example.com
WebLogicPort
6162


SetHandler weblogic-handler
WebLogicHost ruby.uk.example.com
WebLogicPort
6162

...


You need similar Location entries for each of the URIs for all
the applications that were earlier accessed directly on the WebLogic
Server.

Note:

Registering and Managing OAM 11g Agents

15-45

Replacing the IAMSuiteAgent with an 11g WebGate

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.
Skip this step if you do not have Access Manager 11g
integrated with Oracle Identity Manager 11g.

Note:

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.
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.

Note:

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.
See Also:

"Searching for a Host Identifier Definition" on page 22-16

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.

15-46 Administrator's Guide for Oracle Access Management

Replacing the IAMSuiteAgent with an 11g WebGate

Skip this step if you do not have Access Manager 11g
integrated with Oracle Identity Manager 11g.

Note:

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.

Registering and Managing OAM 11g Agents

15-47

Replacing the IAMSuiteAgent with an 11g WebGate

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.

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.
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.

Note:

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.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

15-48 Administrator's Guide for Oracle Access Management

Replacing the IAMSuiteAgent with an 11g WebGate

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

5.

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

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.

Registering and Managing OAM 11g Agents

15-49

Replacing the IAMSuiteAgent with an 11g WebGate

6.

7.

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.

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:

15-50 Administrator's Guide for Oracle Access Management

Managing the Preferred Host in 10g WebGates

-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"
See Also:
■

■

"Validating Authentication and Authorization in an Application
Domain" on page 25-76
Chapter 26, "Validating Connectivity and Policies Using the
Access Tester"

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.
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.

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.

Registering and Managing OAM 11g Agents

15-51

Managing the Preferred Host in 10g WebGates

Use the setAllowEmptyHostIdentifier WLST command, described in the following
section, to manage this feature.

15-52 Administrator's Guide for Oracle Access Management

setAllowEmptyHostIdentifier

setAllowEmptyHostIdentifier
Enables and disables the use of an empty preferred host parameter.

Description
15

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.
AUTO_UPDATE_HOSTID
true

Syntax
15

setAllowEmptyHostIdentifier(enable="true/false")

Argument

Definition

enable

Set to true or false to allow for an empty host identifier or not.

Sample
15

setAllowEmptyHostIdentifier(enable ="true")

Registering and Managing OAM 11g Agents

15-53

setAllowEmptyHostIdentifier

15-54 Administrator's Guide for Oracle Access Management

16
Maintaining Access Manager Sessions
16

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

Maintaining Access Manager Sessions 16-1

Understanding Server-Side Session 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.
Cookie-based sessions can be accessed only from a browser
request context and not directly from the server.

Note:

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.
See Also: Oracle Fusion Middleware Administrator's Guide for
details about configuring secure communications between Oracle
Fusion Middleware components using SSL.

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.

16-2 Administrator's Guide for Oracle Access Management

Understanding Server-Side Session Management

–

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
Idle Timeout can also be implemented as application-specific
settings, as described later.

Note:

Session lifecycle states include those in Table 16–1.
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).

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

Maintaining Access Manager Sessions 16-3

Understanding Server-Side Session 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.
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.

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.
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.

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.

16-4 Administrator's Guide for Oracle Access Management

Understanding Server-Side Session Management

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.
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.

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.

Maintaining Access Manager Sessions 16-5

Understanding Server-Side Session Management

Oracle strongly recommends that you change the value of the
Idle Timeout parameter when using the OAM_GITO cookie:

Note:
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.

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.

16-6 Administrator's Guide for Oracle Access Management

Server-Side Session Enforcement Examples

■
■

■

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.
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 Level 2, authentication
satisfied
time 67

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

Maintaining Access Manager Sessions 16-7

Configuring the Server-Side Session Lifecycle

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.
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)

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
16-8 Administrator's Guide for Oracle Access Management

Configuring the Server-Side Session Lifecycle

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).

Maintaining Access Manager Sessions 16-9

Configuring the Server-Side Session Lifecycle

Table 16–7 (Cont.) Global Session Settings
Setting

Description

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.

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.
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

16-10 Administrator's Guide for Oracle Access Management

Configuring the Server-Side Session Lifecycle

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.
See Also:

"About Global Session Lifecycle Settings"

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.
See Also: "About Application-Specific Session Overrides" on
page 16-10
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):
■

5.

Idle Timeout

Click Apply to submit the changes (or close the page without applying changes).
Maintaining Access Manager Sessions

16-11

Managing Active Server-Side Sessions

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.

16-12 Administrator's Guide for Oracle Access Management

Managing Active Server-Side Sessions

Table 16–9 (Cont.) Session Management Controls and the Results Table
Name

Description

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:
■

■

Detach: Expands the results table to a full-screen view

■

Attach: Restores the Session Management page view.

■

Delete

Columns: Displays a menu with the following options you can use
to hide or display specific details in the table:

Reorder Columns: Specifies a new order for columns containing
session data in the results table.

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.

Maintaining Access Manager Sessions

16-13

Managing Active Server-Side Sessions

Table 16–9 (Cont.) Session Management Controls and the Results Table
Name

Description

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

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.
See Also:

"About the Session Management Pages"

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).

16-14 Administrator's Guide for Oracle Access Management

Validating Server-Side Session Operations

d.
8.

9.

Notify the user, if needed.

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.

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.

2.

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".

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:

5.

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.

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.

Maintaining Access Manager Sessions

16-15

Understanding Client-Side Session 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="")

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.

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.
16-16 Administrator's Guide for Oracle Access Management

Using WLST To Configure Session Management

16.8.2.2 Syntax
configSSOSessionType(type="",
cookieDomain="",domainHome="")

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.

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")

Maintaining Access Manager Sessions

16-17

Using WLST To Configure Session Management

16-18 Administrator's Guide for Oracle Access Management

Part V
Part 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

[15Oracle
]
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.
Access Manager 11g supports scenarios where applications are
distributed across two or more data centers.

Note:

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.

Understanding Multi-Data Centers

17-1

Introducing the Multi-Data Center

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

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.

Note:

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

17-2 Administrator's Guide for Oracle Access Management

Introducing the Multi-Data Center

■

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.

Understanding Multi-Data Centers

17-3

Introducing the Multi-Data Center

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.

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
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.
Note:

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

17-4 Administrator's Guide for Oracle Access Management

Introducing the Multi-Data Center

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.
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.

Note:

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.

Understanding Multi-Data Centers

17-5

Introducing the Multi-Data Center

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).
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.

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.

17-6 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Deployments

Figure 17–3 Active-Active Mode Failover

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.

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.
Understanding Multi-Data Centers

17-7

Understanding Multi-Data Center Deployments

■

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
Note: The OAP connection used for back channel communication
does not support load balancing or failover so a load balancer needs to
be used.

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.

17-8 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Deployments

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 Centers

17-9

Understanding Multi-Data Center Deployments

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.

17-10 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Deployments

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 Centers

17-11

Understanding Multi-Data Center Deployments

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.

17-12 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Deployments

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

Understanding Multi-Data Centers

17-13

Deploying Active-Active Multi-Data Center Topology

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.
17-14 Administrator's Guide for Oracle Access Management

Deploying Active-Active Multi-Data Center Topology

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.

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.

Understanding Multi-Data Centers

17-15

Load Balancing Between Access Management Components

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.

Note:

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.

17-16 Administrator's Guide for Oracle Access Management

Load Balancing Between Access Management Components

■

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.
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."

Note:

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.

Understanding Multi-Data Centers

17-17

Understanding Time Outs and Session Syncs

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.

17-18 Administrator's Guide for Oracle Access Management

Understanding Time Outs and Session Syncs

Table 17–1

Multi-Data Center Policy Configurations for Idle Timeout

OAM_GITO Set

Multi-Data Center Policies

Yes

SessionMustBeAnchoredToDataCenterServicingUser=

Idle timeout will be
SessionDataRetrievalOnDemand=true
calculated from the latest
Reauthenticate=false
OAM_GITO cookie
SessionDataRetrievalOnDemandMax_retry_attempts=
SessionDataRetrievalOnDemandMax_conn_wait_
time=
SessionContinuationOnSyncFailure=
MDCGitoCookieDomain=
No

SessionMustBeAnchoredToDataCenterServicingUser=false

Idle time out will be
calculated from the
OAM_ID cookie because
OAM_GITO is not
available

SessionDataRetrievalOnDemand=true
Reauthenticate=false
SessionDataRetrievalOnDemandMax_retry_attempts=
SessionDataRetrievalOnDemandMax_conn_wait_
time=
SessionContinuationOnSyncFailure=
#MDCGitoCookieDomain= This setting should be commented or
removed

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

Understanding Multi-Data Centers

17-19

Understanding Time Outs and Session Syncs

synchronization and failover scenarios. The parameters in this table are explained in
greater detail in Section 18–3, " partnerInfo.properties Properties."
Table 17–2

MDC
Deployment
Active-Active

Session Synchronization and Failover Scenarios

MDC Policy

Validate
Remote
Session

SessionMustBeAnchoredToDataCen Yes
terServicingUser=true
SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=
SessionDataRetrievalOnDemandMa
x_conn_wait_time=
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=

17-20 Administrator's Guide for Oracle Access Management

Session
Synchronized
in DC
Terminate
Servicing
Remote
User From
Session
User Challenged
Remote DC
Yes

Yes

When a valid
session could not
be located in a
remote DC

Understanding Time Outs and Session Syncs

Table 17–2 (Cont.) Session Synchronization and Failover Scenarios

MDC
Deployment
Active-Active

MDC Policy

Validate
Remote
Session

SessionMustBeAnchoredToDataCen Yes
terServicingUser=false

Session
Synchronized
in DC
Servicing
Terminate
User From
Remote
Remote DC
Session
User Challenged
Yes

No

When a valid
session could not
be located in a
remote DC

No, since the
remote DC is
down

Could not
terminate
as the
remote
DC is
down

Yes

No, since the
remote DC is
down

Could not
terminate
as the
remote
DC is
down

No

SessionDataRetrievalOnDemand=tr
ue
Reauthenticate=false
SessionDataRetrievalOnDemandMa
x_retry_attempts=
SessionDataRetrievalOnDemandMa
x_conn_wait_time=
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=
Active-Standby SessionMustBeAnchoredToDataCen Could
terServicingUser=true
not
validate
SessionDataRetrievalOnDemand=tr
as the
ue
remote
Reauthenticate=false
DC is
down
SessionDataRetrievalOnDemandMa
x_retry_attempts=
SessionDataRetrievalOnDemandMa
x_conn_wait_time=
SessionContinuationOnSyncFailure
= false
MDCGitoCookieDomain=
Active-Standby SessionMustBeAnchoredToDataCen Could
terServicingUser=true
not
validate
SessionDataRetrievalOnDemand=tr
as the
ue
remote
Reauthenticate=false
DC is
down
SessionDataRetrievalOnDemandMa
x_retry_attempts=

Provides seamless
access by creating
a local session
from the details
available in the
valid cookie

SessionDataRetrievalOnDemandMa
x_conn_wait_time=
SessionContinuationOnSyncFailure
= true
MDCGitoCookieDomain=

Understanding Multi-Data Centers

17-21

Replicating a Multi-Data Center Environment

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."
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.

Note:

17.7 Multi-Data Center Recommendations
This section contains recommendations regarding the Multi-Data Center functionality.
■

Using a Common Domain

17-22 Administrator's Guide for Oracle Access Management

Multi-Data Center Recommendations

■

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.
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:

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.
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.

Note:

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."

Understanding Multi-Data Centers

17-23

Multi-Data Center Recommendations

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.
Failover between primary and secondary OAM servers is
supported in the current release of 11g SDK APIs.

Note:

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.
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.

Note:

17-24 Administrator's Guide for Oracle Access Management

18
Configuring Multi-Data Centers
18

[16The
]
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

Configuring Multi-Data Centers

18-1

Understanding the Primary Use Cases

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.
Table 18–1

MDC
Deployment
Active-Active

MDC Use Cases

MDC Policy

Validate
Remote
Session

SessionMustBeAnchoredToDataCenterServ Yes
icingUser=false

Session
Synchroni
zed in DC
Servicing
User From
Remote
DC

Terminate
Remote
Session

Yes

No

When a valid
session could
not be
located in a
remote DC

Could not
terminate
as the
remote DC
is down

No

SessionDataRetrievalOnDemand=true
Reauthenticate=false

User
Challenged

SessionDataRetrievalOnDemandMax_
retry_attempts=
SessionDataRetrievalOnDemandMax_
conn_wait_time=
SessionContinuationOnSyncFailure= false
MDCGitoCookieDomain=
Active-Standb
y

SessionMustBeAnchoredToDataCenterServ Could not No, since
icingUser=false
validate
the remote
DC is down
as the
SessionDataRetrievalOnDemand=true
remote
Reauthenticate=false
DC is
down
SessionDataRetrievalOnDemandMax_
retry_attempts=
SessionDataRetrievalOnDemandMax_
conn_wait_time=
SessionContinuationOnSyncFailure= true

Provides
seamless
access by
creating a
local session
from the
details
available in
the valid
cookie

MDCGitoCookieDomain=

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.
Before beginning this procedure, ensure that you have
completed the points documented in "Before Setting Up a Multi-Data
Center."

Note:

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."

18-2 Administrator's Guide for Oracle Access Management

Setting Up a Multi-Data Center

■

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.
To explicitly set the DC type as Master or Clone, use the
setMultiDataCenterType WLST command documented in
Section 18.6.5, "setMultiDataCenterType."
Note:

c.

Validate the MDC configuration by running the validateMDCConfig WLST
command.
See Section 18.6.8, "validateMDCConfig."

d.
2.

Restart the Admin server.

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.
These registrations can be performed in the Master DC and the
configurations will be applied to all clones created using T2P process.

Note:

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.

Configuring Multi-Data Centers

18-3

Setting Up a Multi-Data Center

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://:

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

18-4 Administrator's Guide for Oracle Access Management

Setting Up a Multi-Data Center

SecondaryHostPort=dc2.example.com:5576
oamMdcSecurityMode=OPEN
trustStorePath=NA
keyStorePath=NA
globalPassPhrase=NA
keystorePassword=NA
agentVersion=11g
RESTEndpoint=https://

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.
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.

Note:

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.
■

■

1.

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.
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

Configuring Multi-Data Centers

18-5

Setting Up a Multi-Data Center

-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.
Note:

Backup the original Moveplan.xml before editing.

cp $T2P_HOME/moveplan/moveplan.xml $T2P_
HOME/moveplan/moveplan.xml.org

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")

This step may be skipped if it was already done through the
T2P process.

Note:

18-6 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Security Modes

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.
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.

Note:

The following sections have details about the security modes.
■

OPEN Security Mode

■

SIMPLE Security Mode

■

CERT Security Mode

Configuring Multi-Data Centers

18-7

Understanding Multi-Data Center Security Modes

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=

oamMdcAgentId=

PrimaryHostPort=
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=
oamMdcSecurityMode=OPEN
agentVersion=
#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=

oamMdcAgentId=
PrimaryHostPort=
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=
oamMdcSecurityMode=SIMPLE
agentVersion=
#Copy the oamclient-truststore.jks & oamclient-keystore.jks from
#/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=
keyStorePath=
#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=
keystorePassword=

18-8 Administrator's Guide for Oracle Access Management

Understanding Multi-Data Center Security Modes

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.
3.

Copy the output into a text editor and save it as aaa_cert.pem.

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

Configuring Multi-Data Centers

18-9

WLST Commands for Multi-Data Centers

/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=

oamMdcAgentId=
PrimaryHostPort=
for example:PrimaryHostPort=adc.example.com:5575
SecondaryHostPort=
for example:SecondaryHostPort=adc.example.com:5577
AccessClientPasswd=
oamMdcSecurityMode=CERT
agentVersion=
trustStorePath=
keyStorePath=
globalPassPhrase=NA
#use keystore password used for generating keystore in the previous step
keystorePassword=

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

18-10 Administrator's Guide for Oracle Access Management

WLST Commands for Multi-Data Centers

■

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.
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.
Note:

18.6.1.2 Syntax
enableMultiDataCentreMode(propfile="../MDC_properties/oamMDCProperty.properties")
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 Takes a value of True (Invalidate) or False
User
(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.

Configuring Multi-Data Centers 18-11

WLST Commands for Multi-Data Centers

Table 18–2 (Cont.) oamMDC.properties Properties
Property

Definition

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.

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 

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.

18-12 Administrator's Guide for Oracle Access Management

WLST Commands for Multi-Data Centers

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.
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.

Note:

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")
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 documents the properties that comprise partnerInfo.properties. See
Understanding Multi-Data Center Security Modes for properties file samples.
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

Configuring Multi-Data Centers 18-13

WLST Commands for Multi-Data Centers

Table 18–3 (Cont.) partnerInfo.properties Properties
Property

Definition

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].

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=("")
Argument

Definition

cluster_ID

Mandatory. Takes a string value equal to the cluster ID.

18-14 Administrator's Guide for Oracle Access Management

WLST Commands for Multi-Data Centers

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="")
Argument

Definition

DataCenterType

Mandatory. Takes a string value of Master or 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="")
Argument

Definition

WriteEnabledFlag

Mandatory. Takes a string value of true or false.

18.6.6.3 Example
The following example protects the Clone Data Center from accidental overwrites.
setMultiDataCenterWrite(WriteEnabledFlag = "false")

Configuring Multi-Data Centers 18-15

WLST Commands for Multi-Data Centers

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="")
Argument

Definition

clusterName

Mandatory. Takes a string equal to the cluster name.

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=" '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

19-4 Administrator's Guide for Oracle Access Management

Syncing Master and Clone Metadata

b.

Stop and start the Access Manager AdminServer.

c.

Validate that the REST endpoints are enabled by running the following
command.
curl -u  '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.

Synchronizing Data In A Multi-Data Center 19-5

Syncing Master and Clone Metadata

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  -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"}

19-6 Administrator's Guide for Oracle Access Management

Syncing Master and Clone Metadata

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)".

Note:

For example, "BASIC base64(weblogic:welcome1)" is specified as
"BASIC d2VibG9naWM6d2VsY29tZTE=" in the following command.
curl -u  -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.
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  -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 
'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 
'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.

Synchronizing Data In A Multi-Data Center 19-7

Syncing Master and Clone Metadata

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  -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  -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.

19-8 Administrator's Guide for Oracle Access Management

Using and Customizing Transformation Rules

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






${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}


${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverprotocol}
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverport}


${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverprotocol}
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS
erverProfile/OAMSERVER/serverhost}
${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMS

Synchronizing Data In A Multi-Data Center 19-9

Using and Customizing Transformation Rules

erverProfile/OAMSERVER/serverport}

















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



${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Instance/oam_server1/host”}



${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Instance/oam_server2/host”}




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
19-10 Administrator's Guide for Oracle Access Management

Modifying a Rule Document

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



${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/OAMServerProfile/OAMSERVER/serverhost”}



${”/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
Profile/OAMServerProfile/OAMSERVER/serverhost”}



■

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




Synchronizing Data In A Multi-Data Center 19-11

Modifying a Rule Document





${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}



${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverprotocol}

${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}

${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverport}



${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverprotocol}

${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverhost}

${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile
/OAMServerProfile/OAMSERVER/serverport}

















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
19-12 Administrator's Guide for Oracle Access Management

Using REST API for Replication Agreements

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  node and
saving the file to the clone’s file system will modify Available Services.


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.
Synchronizing Data In A Multi-Data Center 19-13

Replicating Domains in Identity Manager Deployments

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  -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.
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  -H 'Content-Type: application/json' -X PUT
'https://master.example.com/oam/services/rest/_
replication/'
-d '{"batchSize":"100","replicaType":"SUPPLIER"}'

User Context In rare instances, the user context for replication poll may need to be modified.
curl -u  -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.

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.

19-14 Administrator's Guide for Oracle Access Management

Best Practices for Replication

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

Synchronizing Data In A Multi-Data Center 19-15

Best Practices for Replication

point, you can edit the replication agreement with the latest user identity and
password using the following command.
curl -u  -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="}}}'

19-16 Administrator's Guide for Oracle Access Management

20
Setting Up the Multi-Data Center: A Sequence
02

[18The
]
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 the Multi-Data Center: A Sequence

20-1

Setting Up a Multi-Data Center

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 ().

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:

6.

7.

■

a new WebLogic domain

■

an Oracle Access Management Administration Server

■

an Oracle Access Management Managed Server

■

Oracle Access Manager

Run the configureSecurityStore.py script on Data Center 1, Node 1 to configure
the Database Security Store.
a.

/oracle_common/common/bin/wlst.sh

b.

/Oracle_IDM1/common/tools/configureSecurityStore.py
-c IAM -d /user_projects/domains/OAMDomain
-p Oracle123 -m create -v

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.
8.

Save setDomainEnv.sh.

Create and run a cConfig.sh script in the MDC folder on Data Center 1, Node 1.

20-2 Administrator's Guide for Oracle Access Management

Setting Up a Multi-Data Center

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
export
export
export

b.

JAVA_HOME=/u01/app/jdk1.7.0_60;
MW_HOME=/u01/app/Middleware;
T2P_HOME=/u01/bits/MDC;
WL_DOMAIN_HOME=$MW_HOME/user_projects/domains/OAMDomain;

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 /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 the Multi-Data Center: A Sequence

20-3

Setting Up a Multi-Data Center

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 /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="”)

20-4 Administrator's Guide for Oracle Access Management

Setting Up a Multi-Data Center

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 the Multi-Data Center: A Sequence

20-5

Setting Up a Multi-Data Center

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 .
/u01/bits/final/MDC/t2p_domain_pass.txt

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
Comment out all keystore <> tags in the moveplan if there is
an issue.

Note:

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.

20-6 Administrator's Guide for Oracle Access Management

Setting Up a Multi-Data Center

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 /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 /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 /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="”)

Setting Up the Multi-Data Center: A Sequence

20-7

Setting Up a Multi-Data Center

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()

20-8 Administrator's Guide for Oracle Access Management

Enabling Automated Policy Synchronization

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=“”)

e.

exportPolicy(pathTempOAMPolicyFile=“”)

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=“”)

l.

importPartners(pathTempOAMPartnerFile=“”)

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:

Setting Up the Multi-Data Center: A Sequence

20-9

Enabling Automated Policy Synchronization

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.




${DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/

20-10 Administrator's Guide for Oracle Access Management

Troubleshooting the Multi-Data Center Setup

serverhost}




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'
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.

Note:

■

Select * from FINALDC1_OAM.AM_REPLICATION_SETTINGS;

■

Select * from FINALDC2_OAM.AM_REPLICATION_SETTINGS;

Alternately:

4.

■

Delete from FINALDC1_OAM.AM_REPLICATION_SETTINGS;

■

Delete from FINALDC2_OAM.AM_REPLICATION_SETTINGS;

commit;

Setting Up the Multi-Data Center: A Sequence 20-11

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

[19This
]
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
Unless explicitly stated, information in this chapter is the same
for all agent types and Access Manager credential collectors.

Note:

For details about single log-out, see Chapter 27, "Configuring
Centralized Logout for Sessions Involving 11g WebGates".

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.

Understanding Single Sign-On with Access Manager 21-1

Introducing Access Manager Single Sign-On

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:

Table 21–1 summarizes the components that support or enforce Access Manager
policies, and where to find more information about these, if needed.
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.

Note:

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"

21-2 Administrator's Guide for Oracle Access Management

Introducing Access Manager Single Sign-On

Table 21–1 (Cont.) Summary: SSO Components
Component

Description

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.

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.

Note:

Single sign-on can be implemented as introduced in Table 21–2, which includes
pointers to additional information.
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.

Multiple Network Domain SSO

Access Manager 11g supports cross-network-domain single sign-on
out of the box.

Single Network Domain SSO is the subject of this book.

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

Understanding Single Sign-On with Access Manager 21-3

Introducing Access Manager Single Sign-On

Table 21–2 (Cont.) Introduction to SSO Implementations
SSO Type

Description

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.

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.
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.

Note:

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

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

21-4 Administrator's Guide for Oracle Access Management

Introducing Access Manager Single Sign-On

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.
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:

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.
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.

Note:

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.

Understanding Single Sign-On with Access Manager 21-5

Introducing Access Manager Single Sign-On

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:

21-6 Administrator's Guide for Oracle Access Management

Understanding the Access Manager Policy Model

■

■

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

Access Manager

Authentication
Schemes

Application
Domains

Resource
Types

Host
Identifiers

Authentication
Modules

Policies

Resources
Legend
Relationship: One-to-Many

Authentication
Policies

Authorization
Policies

Token Issuance
Policies

Relationship: Many-to-Many
External Dependencies
Relationship: Containment

Identities

Contextual Data

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

Access Manager

Authentication
Schemes

Resource
Types

Host
Identifiers

Authentication
Modules

Table 21–3 describes the global, shared components in an Access Manager policy.

Understanding Single Sign-On with Access Manager 21-7

Understanding the Access Manager Policy Model

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:

Host Identifiers

■

Chapter 22: Managing Resource Types

■

Chapter 45: Managing TokenServiceRP Type Resources

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

21-8 Administrator's Guide for Oracle Access Management

Understanding the Access Manager Policy Model

Table 21–3 (Cont.) Access Manager Global, Shared Policy Components
Component

Description

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

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.
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.

Understanding Single Sign-On with Access Manager 21-9

Anatomy of an Application Domain and Policies

Table 21–4 (Cont.) Access Manager Policy Components
Component

Description

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.

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.

21-10 Administrator's Guide for Oracle Access Management

Anatomy of an Application Domain and Policies

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.
Only resources defined in the Resources container can be
associated with policies in the Application Domain.

Note:

For more information, see "Adding and Managing Policy Resource Definitions" on
page 25-13.
To protect pieces of content on a page, Oracle recommends
using Oracle Entitlements Server.

Note:

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

Understanding Single Sign-On with Access Manager

21-11

Anatomy of an Application Domain and Policies

■

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
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

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.
OracleAS SSO 10g does not provide authorization; OSSO
Agents do not use Access Manager 11g Authorization Policies.

Note:

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.

21-12 Administrator's Guide for Oracle Access Management

Introduction to Policy Conditions and Rules

■

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.
See Also:

"Introduction to Policy Conditions and Rules"

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.
During automatic policy generation, no Token Issuance
Policies are created; only the container for Token Issuance Policies is
generated automatically.

Note:

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.
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.

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).

Understanding Single Sign-On with Access Manager

21-13

Understanding SSO Cookies

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 !.
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.

Note:

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.
Table 21–6

SSO Cookies

SSO Cookie Set at
User Login
OAM_ID cookie

OAMAuthnCookie

Set By

Description

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.

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.

See Also: "OAM_ID cookie" on page 21-16.

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.

21-14 Administrator's Guide for Oracle Access Management

Understanding SSO Cookies

Table 21–6 (Cont.) SSO Cookies
SSO Cookie Set at
User Login

Set By

Description

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

OHS-host-port

Detached
Credential
Collector

For detached credential collector (DCC)--similar to OAM_REQ
created by embedded credential collector (ECC).
See "DCCCtxCookie" on page 21-18

Oracle HTTP Set only when OSSO Agents (mod_osso) are contacted on Oracle
Server
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.

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

Understanding Single Sign-On with Access Manager

21-15

Understanding SSO Cookies

■

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__ 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.

21-16 Administrator's Guide for Oracle Access Management

Understanding SSO Cookies

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.
You must invoke the WLST script from the Oracle Common
home. See "Using Custom WLST Commands" in the Oracle Fusion
Middleware Administrator's Guide.

Note:

See Also:
■

■

Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference
Table 21–6, " SSO Cookies"

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.

Understanding Single Sign-On with Access Manager

21-17

Understanding SSO Cookies

–

■

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: RequestContextCookieExpTime in Table 15–2,
" User-Defined WebGate Parameters"

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.
See Also: "Configuring 11g WebGates and Authentication Policy for
DCC"

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.

21-18 Administrator's Guide for Oracle Access Management

Understanding SSO Cookies

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:

OssoIpCheck off
OssoIdleTimeout off
OssoSecureCookies on
OssoConfigFile osso/osso.conf

require valid-user
AuthType Basic



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

Understanding Single Sign-On with Access Manager

21-19

Introduction to Configuration Tasks for Single Sign-On

■

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:

4.

■

Chapter 14, "Introduction to Agents and Registration"

■

Chapter 15, "Registering and Managing OAM 11g Agents"

Proceed to manage resource types, host identifiers, authentication schemes, and
modules:
■

5.

Chapter 22, "Managing Authentication and Shared Policy Components"

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"

21-20 Administrator's Guide for Oracle Access Management

22
Managing Authentication and Shared Policy
Components
22

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 Authentication and Shared Policy Components 22-1

Managing Resource Types

See Also: Chapter 21, "Understanding Single Sign-On with Access
Manager"

Task overview: Configuring shared policy components
1.

Confirm that the desired resource type is defined, as described in this chapter:
■

2.

Confirm that a host identifier definition named for the agent was created during
agent registration, (or create one yourself), as described in:
■

3.

5.

6.

7.

Managing Host Identifiers

Gain comprehension about credential collection with Access Manager:
■

4.

Managing Resource Types

Understanding Authentication Methods and Credential Collectors

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

Create and manage authentication schemes that you can add to authentication
policies, as described in:
■

Managing Authentication Schemes

■

Configuring Challenge Parameters for Encrypted Cookies

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

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

22-2 Administrator's Guide for Oracle Access Management

Managing Resource Types

■

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.
Changes to the operation list of a resource type is not allowed
if a resource of that type exists.

Note:

Table 22–1 compares resource types and operations.
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.

HTTP: The HTTP resource type is read-only.

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.

Operations: Oracle-provided resource types
are read-only; associated operations are
pre-defined. Policies developed and applied
to the resource apply to all operations.

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

■

Get

■

Post

■

Put

■

Head

■

Delete

■

Trace

■

Options

■

Connect

■

Other

See Also: "About the Resource Type Page" on page 22-4.
wl_authen: Resources for representing WebLogic Authentication schemes is also
read-only (default operations cannot be modified or deleted.)

N/A

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.

Managing Authentication and Shared Policy Components 22-3

Managing Resource Types

Table 22–1 (Cont.) Comparison: Resource Types for Access Manager versus 10g
Access Manager 11g

Oracle Access Manager 10g

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.

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.

A custom "EJB" resource type can be created on demand for use in SSO
integrations.

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.

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.
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.

Note:

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

22-4 Administrator's Guide for Oracle Access Management

Managing Resource Types

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 Authentication and Shared Policy Components 22-5

Managing Resource Types

Table 22–2 (Cont.) Resource Type Definition
Element

Description

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.

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.
See Also:

"Conducting A Search"

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.

22-6 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

■

■
■

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.
See Also:
■

"About Resource Types and Their Use" on page 22-2

■

"Defining Resources in an Application Domain" on page 25-27

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

Managing Authentication and Shared Policy Components 22-7

Managing Host Identifiers

■

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.
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.

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.
Each resource should be unique across all Application
Domains; each resource and host identifier combination must be
unique across all Application Domains.

Note:

22-8 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

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.
If you enter a host name in the Challenge Redirect field of an
authentication scheme, it must be defined as a Host Identifier.

Note:

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.

Managing Authentication and Shared Policy Components 22-9

Managing Host Identifiers

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 information here is the same for both 11g and 10g
Webgates.

Note:

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/

22-10 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

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.
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.

Note:

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.

Managing Authentication and Shared Policy Components

22-11

Managing Host Identifiers

■

■

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
See Also:
■

http://www.simpledns.com/kb.aspx?kbid=1149

■

http://support.microsoft.com/kb/q190008/

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.

22-12 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

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.
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.

Note:

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.
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
Managing Authentication and Shared Policy Components

22-13

Managing Host Identifiers

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.
Each host identifier must be unique. You cannot use the same
host name and port in any other host identifier definition.

Note:

Figure 22–4 Create Host Identifier Page

22-14 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

Table 22–4 describes the host identifier definitions.
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

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.
If you copy an existing definition to use as a template, you
must modify all unique identifiers in the copy.

Note:

See Also:
■

"About Host Identifiers" on page 22-8

■

"About Virtual Web Hosting" on page 22-10

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).

Managing Authentication and Shared Policy Components

22-15

Managing Host Identifiers

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.
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"

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
After viewing settings, you can either close the page or modify
settings as needed.

Note:

See Also:

"About the Host Identifier Page" on page 22-14

22-16 Administrator's Guide for Oracle Access Management

Managing Host Identifiers

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.
If the Host Identifier is associated with a resource, you are
alerted. Without any association, the Host Identifier is deleted.

Note:

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.
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.

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.

Managing Authentication and Shared Policy Components

22-17

Understanding Authentication Methods and Credential Collectors

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.
See Also:

"Multi-Step Authentication"

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.

22-18 Administrator's Guide for Oracle Access Management

Understanding Authentication Methods and Credential Collectors

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.
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.

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.
The DCC is the recommended approach for credential
collection. See Chapter 23, "Understanding Credential Collection and
Login" for more details.

Note:

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.

Managing Authentication and Shared Policy Components

22-19

Understanding Authentication Methods and Credential Collectors

■

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:
Table 22–5

"Understanding Credential Collection and Login"

Comparing the DCC and ECC

Deployment

DCC

ECC

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:

The Embedded Credential Collector is deployed
with, and integral to, the OAM Server and part of
the protocol binding layer.

■

■

■

DMZ Deployment

Stands alone (detached from the OAM
Server and does not require an application
server).

The ECC supports RSA SecurID passcode
verification, get next token, create new pin
workflows.

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.

Yes.

No.

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.
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.

22-20 Administrator's Guide for Oracle Access Management

ECC communicates with both the user and the
OAM Server across HTTP/HTTPS.

Understanding Authentication Methods and Credential Collectors

Table 22–5 (Cont.) Comparing the DCC and ECC

DCC login, error, and
password pages

DCC

ECC

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:

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: /oamsso-bin/login.pl

■

Logout: /oamsso-bin/logout.pl

■

■

Login page: /pages/login.jsp

■

Logout page: /pages/logout.jsp

■

Error page: /pages/servererror.jsp

■

Multi-step: /pages/mfa_login.jsp

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.
Perl Scripts for
DCC-based Login and
Logout

Perl Scripts for DCC-based Login and Logout

N/A

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.

Password policy
enforcement

Yes.

Yes

See Configuring 11g WebGates and
Authentication Policy for DCC

See: Managing Global Password Policy

Authentication scheme
collection methods

DCC supports only Form Based Authentication.

Custom Authentication
Plug-ins and Challenge
Methods

Yes; same as ECC.

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.
All challenge methods and multi-step
authentication (Password Policy and other
custom authentication plugins) are supported.

Managing Authentication and Shared Policy Components

22-21

Understanding Authentication Methods and Credential Collectors

Table 22–5 (Cont.) Comparing the DCC and ECC

Single Step (Simple
Form) Authentication

DCC

ECC

Yes; same as ECC.

Yes. Both the DCC and ECC handle this, where:
■

■

■

Multi-Step
Authentication

Yes. Both the DCC and ECC handle complex
multi-factor (multi-step, iterative, and variable)
Authentication processing.

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

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
Authentication
Processing

The DCC does not restrict authentication
functionality of the OAM Server in any way as
compared to the ECC.

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.

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; 4.
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.

22-22 Administrator's Guide for Oracle Access Management

The ECC interacts with the client, accepts the
data, and submits this to the PBL.

Managing Native Authentication Modules

Table 22–5 (Cont.) Comparing the DCC and ECC

Overriding the ECC

DCC

ECC

To deploy the DCC and override the ECC, an
Administrator must perform the following tasks
to specify the relevant DCC URLs and forms.

N/A

■

■

■

■

■
■

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
Logout Configuration

See "Configuring Logout When Using Detached
Credential Collector-Enabled WebGate" on
page 27-6

Cookie/Token

See "Configuring Centralized Logout for 11g
WebGates" on page 27-4

■

DCCCtxCookie

■

11g Webgate: OAMAuthnCookie

■

11g WebGate: OAMAuthnCookie

■

11g Webgate: OAM_REQ

■

11g WebGate: OAMRequestContext

■

11g Webgate: OAM_ID

■

10g Resource WebGate: ObSSOCookie

■

11g Webgate: OAMRequestContext

■

10g Webgate: ObSSOCookie

See: "About Single Sign-On Cookies During User
Login" on page 21-14

See: "About Single Sign-On Cookies During User
Login" on page 21-14

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.
See Also:
■

Chapter 7, "Logging Component Event Messages"

■

Chapter 8, "Auditing Administrative and Run-time Events."

■

Chapter 11, "Monitoring Performance and Health"

22.6 Managing Native Authentication Modules
In Access Manager, each authentication scheme requires an authentication module.

Managing Authentication and Shared Policy Components

22-23

Managing Native Authentication Modules

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.

Note:

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.
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.

22-24 Administrator's Guide for Oracle Access Management

Managing Native Authentication Modules

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

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.
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).

22.6.1.2 Native LDAP Authentication Modules
Oracle provides two LDAP authentication modules:
■

LDAP

■

LDAPNoPasswordAuthModule

Managing Authentication and Shared Policy Components

22-25

Managing Native Authentication Modules

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.
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.

Note:

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.

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

22-26 Administrator's Guide for Oracle Access Management

Managing Native Authentication Modules

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.
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.

Note:

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 Authentication and Shared Policy Components

22-27

Managing Native Authentication Modules

Table 22–9 (Cont.) X509 Authentication Module Definition
Element

Description

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.

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.
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.
Note:

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

22-28 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

■

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.
Oracle strongly recommends using authentication plug-ins to
create custom authentication modules.

Note:

This section provides the following topics:
■

Comparing Simple Form and Multi-Factor (Multi-Step) Authentication

■

About Plug-ins for Multi-Step Authentication Modules

Managing Authentication and Shared Policy Components

22-29

Orchestrating Multi-Step Authentication with Plug-in Based Modules

■
■

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
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management if you want to create custom authentication
plug-ins.

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.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management for details about customizing login pages and forms

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.
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.

Note:

Table 22–10 provides more information about these two forms of authentication.

22-30 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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

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.
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.

Note:

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.

Managing Authentication and Shared Policy Components

22-31

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.

22-32 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.
When multi-factor authentication is used, the
UserIdentificationPlugin should be invoked in the last pass during the
authentication process.

Note:

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.
Table 22–11

General tab

Element

Description

Name

A unique name up to 60 characters.

Description

Optional; up to 250 characters.

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.

Managing Authentication and Shared Policy Components

22-33

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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–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.

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.

22-34 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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:

CredentialCollectorPlugIn

CredentialCollectorPlugIn

■

UserIdentificationPlugIn

■

UserAuthenticationPlugIn

■

UserPasswordPolicyPlugin

■

TAPUserAuthenticationPlugin

■

TenantDisambiguationPlugin

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.

Managing Authentication and Shared Policy Components

22-35

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Table 22–13 (Cont.) Parameter Details for Various Plug-ins
Plug-in Parameter

Display Name

Description

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:
■

■

■

POLICY_SCHEMA

Policy Schema To Use

NEW_USERPSWD_BEHAVIOR

Force Password Change on First
Login

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

Specifies the schema for the password service (used
with UserPasswordPolicyPlugin). Only OAM10G is
supported.
Default: OAM10G
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

22-36 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Table 22–13

(Cont.) Parameter Details for Various Plug-ins

Plug-in Parameter

Display Name

Description

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.

Username Mapping Attribute

Name of the attribute used for account linking by
TAPIdentifyPlugIn.

Orchestration Strategy

Name of the plugin orchestration strategy required by
SequentialPlugInExecutionStrategy.

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.

FedUserProvisioningPlugin

TAPIdentifyPlugIn
KEY_TAP_RETURN_ATTRIBUTE
SequentialPlugInExecutionStrate
gy
StrategyName
KerberosTokenAuthenticator

X509CredentialExtractor
KEY_CERTIFICATE_ATTRIBUTE_ User Mapping Attribute
TO_EXTRACT

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.

TAPS2PVersion

Integration Protocol Version

Token version for Integration.

TAPPartnerId

Integration PartnerId

Integration Partner Identifier.

TAPChallengeURL

Partner Integration Endpoint
URL

Remote Partner End Point URL.

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.

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.

Username Parameter

Name of the username plugin parameter required by
RSA SecurID Plugin.

TAPRequestPlugin

TAPUserAuthenticationPlugin

TenantDisambiguationPlugin
KEY_FEDERATED_TENANTS

RSA SecurID Plugin
username

Managing Authentication and Shared Policy Components

22-37

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Table 22–13 (Cont.) Parameter Details for Various Plug-ins
Plug-in Parameter

Display Name

Description

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.

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."

HTTPTokenExtractor

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).

22-38 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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)

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:

OnFailure

OnError

■

Success

■

Failure

■

StepName (activates the next step)

The action selected for failure of this step. A list provides actions you
can choose:
■

Success

■

Failure

■

StepName (activates the next step)

The action selected for an error when executing this step. A list
provides actions you can choose:
■

Success

■

Failure

■

StepName (activates the next step)

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:
Managing Authentication and Shared Policy Components

22-39

Orchestrating Multi-Step Authentication with Plug-in Based Modules

■

KerberosPlugin

■

LDAPPlugin

■

X509Plugin

■

Password Policy Validation Module and Plug-ins
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

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.

22-40 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.

Managing Authentication and Shared Policy Components

22-41

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Figure 22–16

LDAPPlugin

Figure 22–17

Default LDAPPlugin Steps and Details

22-42 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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

Managing Authentication and Shared Policy Components

22-43

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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
issuer.D
subject.

X509 Step Details (KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT)
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

22-44 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Figure 22–21

Default Orchestration for X509Plugin Steps

See Also: "Example: Leveraging SubjectAltName Extension Data
and Integrating with Multiple OCSP Endpoints"

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.

Managing Authentication and Shared Policy Components

22-45

Orchestrating Multi-Step Authentication with Plug-in Based Modules

See Also:
■

Table 22–13, " Parameter Details for Various Plug-ins"

■

Configuring Password Policy

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:
See Also: "Creating and Orchestrating Plug-in Based Multi-Step
Authentication Modules" on page 22-48

General Tab:
a.

Name: CustomX509Plugin.

b.

Description: Custom Plug-in for X509.

Steps Tab:

22-46 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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}
))

5.

6.

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).

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.

Set up the Certificate Validation Module for Certificate Validation and Revocation
using OCSP.
See Also:

"Managing Certificate Validation and Revocation" on

page 3-7
a.

In the Oracle Access Management Console, click Configuration at the top of
the window.
Managing Authentication and Shared Policy Components

22-47

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.
Initially the keystore is empty; its password is set the first time
the Java keytool application is used.

Note:

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).
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

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.

22-48 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

f.
5.

Repeat b through e to add other steps until you have listed all required
plug-ins for your module.

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

6.

7.

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.

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.

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.

Managing Authentication and Shared Policy Components

22-49

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.

22-50 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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:

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.

■

ON SUCCESS, go to SensitiveLevelCheck-6

■

ON FAILURE, go to CollectUserNamePassword

■

ON ERROR, Failure

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:

3

UserIdentificationProcess

UserIdentificationPlugIn

■

ON SUCCESS, go to UserIdentificationProcess

■

ON FAILURE, Failure

■

ON ERROR, Failure

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

Managing Authentication and Shared Policy Components

22-51

Orchestrating Multi-Step Authentication with Plug-in Based Modules

Table 22–16 (Cont.) Steps and Plug-ins in a Customized Step-up Authentication Module
Step
#

Step Name

Plug-in Name

Description

4

UserAuthenticationStep

UserAuthenticationPlugin

Out of the box plug-in that authenticates the supplied
username and password credentials against an LDAP
directory.

5

6

SensitiveLevelCheck-6

UserAuthnLevelCheckPlu
gin

CollectSensitiveLevelCreds CredentialCollectorPlugin

■

ON SUCCESS, go to SensitiveLevelCheck-6

■

ON FAILURE go to CollectSensitiveLevelCreds

■

ON ERROR, Failure

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

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

■

7

ValidateSensitiveLevelCred SubjectSetPlugin
s

CRED_PARAM_1: {ID=securitycode},{DISPLAY_
NAME=form_securecode},{TYPE=text}

This custom developed plug-in validates the security code
against the server.
■

ON SUCCESS, Success

■

ON FAILURE, Failure

■

ON ERROR, Failure

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.
See Also: "Creating and Orchestrating Plug-in Based Multi-Step
Authentication Modules"

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.

22-52 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

3.

Orchestrate your Steps and Plug-ins as shown here and described in Table 22–16.

Managing Authentication and Shared Policy Components

22-53

Orchestrating Multi-Step Authentication with Plug-in Based Modules

4.

Sensitive Scheme: Create or edit an Authentication Scheme for sensitive
applications that uses your customized step-up authentication module. For
example:
See Also:

5.

"Managing Authentication Schemes" on page 22-64

Lower-Level Scheme: Create or edit an Authentication Scheme for the lowest level
applications using your customized step-up authentication module F.or example:

22-54 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

6.

Sensitive Policy: Create or edit an Authentication Policy for sensitive-level
resources using your customized step-up Authentication Scheme. For example:
See Also: Chapter 25, "Managing Policies to Protect Resources and
Enable SSO"

7.

Lower-Level Policy: Create or edit an Authentication Policy for the lowest level
resources using your customized step-up Authentication Scheme. For example:

Managing Authentication and Shared Policy Components

22-55

Orchestrating Multi-Step Authentication with Plug-in Based Modules

8.

Verify: 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})
Note:

The user should be present in the data store which is being

used.

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.

22-56 Administrator's Guide for Oracle Access Management

Orchestrating Multi-Step Authentication with Plug-in Based Modules

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.

Managing Authentication and Shared Policy Components

22-57

Deploying and Managing Individual Plug-ins for Authentication

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:
22-58 Administrator's Guide for Oracle Access Management

Deploying and Managing Individual Plug-ins for Authentication

■

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.

Managing Authentication and Shared Policy Components

22-59

Deploying and Managing Individual Plug-ins for Authentication

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"

22-60 Administrator's Guide for Oracle Access Management

Deploying and Managing Individual Plug-ins for Authentication

Table 22–17

(Cont.) Managing Custom Plug-ins Actions

Action Button
Activate Selected

Description
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 describes elements in the Plugins status table.
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.

Managing Authentication and Shared Policy Components

22-61

Deploying and Managing Individual Plug-ins for Authentication

Table 22–18

(Cont.) Plugins Status Table

Element

Description

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.

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.
Table 22–19

Example of Plugin Details Extracted from XML Metadata File

Configuration
Element

Description

DataSource

- 
- 
DataSource
true
false
true
jdbc/CISCO



Kerberos Details

Defines the following Kerberos details:

User Identification
Details

Defines the User Identity Store and LDAP filter parameters. for this plug-in to use:

User Authentication
Details

Defines the User Identity Store for this plug-in to use:

X.509 Details

Defines the X.509 certificate details for this plug-in to use:

KEY_KEYTAB_FILE, KEY_PRINCIPAL, KEY_KRB_CONFIG_FILE

KEY_IDENTITY_STORE_REF, KEY_LDAP_FILTER

KEY_IDENTITY_STORE_REF

KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT, KEY_IS_CERT_VALIDATION_ENABLED

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

22-62 Administrator's Guide for Oracle Access Management

Deploying and Managing Individual Plug-ins for Authentication

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:

4.

5.

a.

In the Plug-ins table, select the target plug-in.

b.

Click Distribute Selected, then check the plug-in’s Activation Status tab.

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.

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 and Shared Policy Components

22-63

Managing Authentication Schemes

■

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.

4.

5.

a.

In the Plug-ins table, select the target plug-in.

b.

Click Deactivate Selected, then check the plug-in’s Activation Status.

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.

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
22-64 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

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 and Shared Policy Components

22-65

Managing Authentication Schemes

Table 22–20

(Cont.) Authentication Scheme Definition

Element

Description

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:///
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.

22-66 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

Table 22–20

(Cont.) Authentication Scheme Definition

Element

Description

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.

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:

Managing Authentication and Shared Policy Components

22-67

Managing Authentication Schemes

■

■

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");


–

Submit back to the OAM Server the end point, "/oam/server/auth_cred_
submit". For example: 
 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
See Also: Oracle Fusion Middleware Developer's Guide for Oracle
Access Management for details about customizing login pages and
messages.

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.
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

For Fusion Applications

Only for Oracle 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

BasicSessionlessScheme

Authentication Level: 1
Challenge Method: Basic
Authentication Module: LDAP

Protects Access Manager-related resources (URLs) for
most directory types.

Authentication Level: 1
Challenge Method: Basic
Authentication Module: LDAP

Primarily used for clients that don't support URL
redirect or cookies.

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.

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.

22-68 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

Table 22–21

(Cont.) Pre-configured Authentication Schemes

Scheme Name

Specifications

Purpose

FAAuthScheme

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:

Only for Oracle Fusion
Applications

http://www.oracle.com/technetwork
FederationMTScheme
Only for Oracle Fusion
Applications

FederationScheme
Only for Identity
Federation 11.1.2.

KerberosScheme

For specific information about this authentication
Authentication Level: 2
Challenge Method: FORM
scheme, refer to the Oracle Fusion Applications
Authentication Module: FederationMTPlugin Technology Library located on the Oracle Technology
Network (OTN) web site:
Context Type: customWar
Context Value: /fusion_apps
http://www.oracle.com/technetwork
Challenge Parameters: initial_
See Also: "About Challenge Parameters for
command=NONE
Authentication Schemes" on page 22-75.
is_rsa=true
Authentication Level: 2
Challenge Method: FORM
Authentication Module: FederationPlugin

See Also: Part IX, "Managing Oracle Access
Management Identity Federation".

Context Type: customWar
Context Value: /oam
Challenge Parameters: initial_
command=NONE
is_rsa=true

Note: With Oracle Identity Federation 11.1.1, use
OIFScheme as described in the Oracle Fusion
Middleware Integration Guide for Oracle Access
Manager.

Authentication Level: 2
Challenge Method: WNA
Authentication Module: Kerberos

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.

Context Type: customWar
Context Value: /fusion_apps
LDAPNoPasswordValid Authentication Level: 2
Challenge Method: FORM
ationScheme
Authentication Module:
LDAPNoPasswordAuthModule
Context Type: default
Context Value: /oam

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.

Note: LDAPNoPasswordAuthModule is
similar to the DAP (asserter) mechanism.
See Also OAM10gScheme, later in this table.
LDAPScheme

Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP

Protects Access Manager-related resources (URLs) for
most directory types based on a form challenge
method.

Context Type: customWar
Context Value: /fusion_apps
OAAMAdvanced

Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: external

OAAMBasic

Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP
Context Type: default
Context Value: /oam

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.
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.

Challenge Parameters
oaamPostAuth=true
oaamPreAuth=true

Managing Authentication and Shared Policy Components

22-69

Managing Authentication Schemes

Table 22–21 (Cont.) Pre-configured Authentication Schemes
Scheme Name

Specifications

Purpose

OAM10gScheme

Authentication Level: 2
Challenge Method: OAM10G
Authentication Module:
LDAPNoPasswordAuthModule

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.

See Also
LDAPNoPasswordValidationScheme, earlier
in this table.

This scheme requires challenge mechanism OAM10G,
specifically for OAM10g coexistence with OSSO as
described in "OAM10G" on page 22-74.

enableCoexistMode and disableCoexistMode
in the Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
OAMAdminConsoleSch
eme

Authentication Level: 2
Challenge Method: FORM
Authentication Module: LDAP

Authentication scheme for Oracle Access Management
Console.

Context Type: default
Context Value: /oam
OICScheme

Authentication Level: 2
Challenge Method: DAP
Authentication Module: TAPModule
Context Type: External
Challenge Parameters:
TAPPartnerId=RPPartner
MatchLDAPAttribute=mail

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

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"

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.

22-70 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

Table 22–21

(Cont.) Pre-configured Authentication Schemes

Scheme Name

Specifications

Purpose

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

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.

Context Type: External

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.

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.

Managing Authentication and Shared Policy Components

22-71

Managing Authentication Schemes

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.
This challenge method relies on an LDAP Authentication
Module and the user identity store associated with that module.

Note:

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.
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  tag in the config.xml file.

Note:

false


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.
Note: X509 is the challenge method for the X509Scheme. The user's
organization can determine how to obtain a certificate.

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.

22-72 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

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.
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 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.
The KerbScheme relies on the WNA challenge method and
Kerberos Authentication Module.

Note:

See Also: Chapter 57 for details about integration with Windows
Native Authentication

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

Managing Authentication and Shared Policy Components

22-73

Managing Authentication Schemes

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.

22-74 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

See Also:
■
■

OAM10gScheme in Table 22–21
enableCoexistMode and disableCoexistMode in the Oracle Fusion
Middleware WebLogic Scripting Tool Command Reference

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:
=

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.
Table 22–22

Challenge Parameters in Pre-configured Schemes

Pre-configured Schemes
BasicSessionlessScheme

Challenge Parameter
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

Primarily used for clients that do not support URL redirect or cookies.

For Identity Federation 11.1.2.only.
Use OIFScheme for Oracle Identify
Federation 11.1.1.

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

TAPPartnerId=OIFDAPPartner

For Oracle Identify Federation 11.1.1 This scheme delegates authentication to Oracle Identity Federation 11.1.1, after which,
only. Use FederationScheme for
Federation sends back a token that is asserted by the OAM Server.
Identity Federation 11.1.2.
TapScheme

TAPPartnerId=TAPPartnerName

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.

Managing Authentication and Shared Policy Components

22-75

Managing Authentication Schemes

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=

Supported by the detached credential collector (DCC) only.

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}:]
. However, the value any is used by extracreds only. For example:
extracreds=[{any | cookie | header | server | query | post}:] 
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"

22-76 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

Table 22–23

(Cont.) User-Defined Challenge Parameters for Authentication Schemes

Challenge Parameter

Definition

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"

Managing Authentication and Shared Policy Components

22-77

Managing Authentication Schemes

Table 22–23 (Cont.) User-Defined Challenge Parameters for Authentication Schemes
Challenge Parameter

Definition

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=

Defines the maximum length of the DCC cookie.

DCC Only

Default: 4096
See Also: TempStateMode in this table for more information.

22-78 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

Table 22–23

(Cont.) User-Defined Challenge Parameters for Authentication Schemes

Challenge Parameter

Definition

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:

allowedAccessGateList=

■

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"

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

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

Managing Authentication and Shared Policy Components

22-79

Managing Authentication Schemes

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
Note: Multi-level authentication does not affect, negate, or alter
X.509 certificate authentication.

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".
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:

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: 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.

22-80 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

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.

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.
See Also: "Understanding Authentication Methods and Credential
Collectors" on page 22-18

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.
11g OAM Agents are associated with individual per-agent
OAMAuthnCookies.

Note:

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.

Managing Authentication and Shared Policy Components

22-81

Managing Authentication Schemes

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.
See Also:
■
■

"About Authentication Schemes and Pages" on page 22-65
Configuring 11g WebGates and Authentication Policy for DCC if
needed

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.

22-82 Administrator's Guide for Oracle Access Management

Managing Authentication Schemes

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.
See Also:

"Conducting A Search"

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.
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.

Note:

See Also:
■

"About Authentication Schemes and Pages"

■

"Configuring the PasswordPolicyValidationScheme"

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).

Managing Authentication and Shared Policy Components

22-83

Extending Authentication Schemes with Advanced Rules

In an upgraded deployment with OSSO Agents, change the
Authentication Scheme and any Protected Resource Policies to use
SSOCoExistMigrateScheme.

Note:

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 are part of the Adaptive Authentication
Service for which a license is required. See Section 35.1, "Using the
Adaptive Authentication Service."

Note:

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.
Table 22–24

Advanced Rules Attributes

Name

Description

Name

AuthnRule name. Name has to be unique within the checkpoint

Description

Description of the rule

22-84 Administrator's Guide for Oracle Access Management

Extending Authentication Schemes with Advanced Rules

Table 22–24

(Cont.) Advanced Rules Attributes

Name

Description

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.

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.
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
This rule can be used in
location.clientIP.startswith('172.16') or Pre and Post
location.clientIP.startswith('192.168')
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

Managing Authentication and Shared Policy Components

22-85

Extending Authentication Schemes with Advanced Rules

Table 22–25

(Cont.) Sample Advanced Rules
Sample Jython Script-based
Condition

Sample Rule

Notes

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 This rule can be used
th('basic')
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

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"

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

22-86 Administrator's Guide for Oracle Access Management

Extending Authentication Schemes with Advanced Rules

Table 22–26

(Cont.) Request Context Data

Attribute Name

Description

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

Table 22–28

Returns Proxy IP address

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'

Managing Authentication and Shared Policy Components

22-87

Configuring Challenge Parameters for Encrypted Cookies

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__
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.
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 (=):

Note:

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 describes specific challenge parameters that control how Webgates set
encrypted cookie flags for single sign-on.
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.

22-88 Administrator's Guide for Oracle Access Management

Configuring Challenge Parameters for Encrypted Cookies

Table 22–30

(Cont.) Challenge Parameters for 10g/11g Encrypted Cookies

11g /10g Webgate Challenge
Parameter Syntax for Encrypted
Cookies

Description
Parameter that controls flags for all other Access Manager encrypted
cookies.

miscCookies=

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.

Secure

ssoCookie=Secure
miscCookies=Secure
Explicitly disables Secure cookies.

disableSecure

ssoCookie=disableSecure
miscCookies=disableSecure
Enabled by default with 11g Webgate SSO OAMAuthnCookie and
miscellaneous cookies.

httponly

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 Creates a persistent cookie in browsers, rather than one that lasts for
a single session, and specifies the time interval in-seconds when the
ds
cookie expires.
For example, to set the cookie to expire in 30 days (2592000 seconds):
max-age=2592000

22.11.2 Configuring Challenge Parameters for Security of Encrypted Cookies
The challenge parameter is not case sensitive.
See Also:

"Creating an Authentication Scheme" on page 22-82

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.
See Also:

"Creating an Authentication Scheme" on page 22-82

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

Managing Authentication and Shared Policy Components

22-89

Configuring Authentication POST Data Handling

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.
Authentication POST data preservation and restoration is not
supported when Access Manager performs authentication through
custom agents.

Note:

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.

22-90 Administrator's Guide for Oracle Access Management

Configuring Authentication POST Data Handling

Table 22–31

(Cont.) Resource Webgate Support of POST Data Preservation and

Resource Webgate

Description

Ignores Preservation if ...

Post data is larger than the configured or hard-coded limit, preservation
is ignored.

Logs a Message when ...
Performs Standard
Authentication if ...
Shows an Error when ...

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 describes credential collector feature support for POST data handling.
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.

22.12.2 About Configuring Authentication POST Data Handling
Table 22–33 summarizes the authentication schemes that support authentication POST
data handling.

Managing Authentication and Shared Policy Components

22-91

Configuring Authentication POST Data Handling

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 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–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"

22-92 Administrator's Guide for Oracle Access Management

Configuring Authentication POST Data Handling

Table 22–34

(Cont.) Parameters Required for Authentication POST Data Handling

Parameter

Description

ChallengeRedirectMaxMessageBy Configure this user-defined Webgate parameter to limit the size of the
tes
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

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.
Managing Authentication and Shared Policy Components

22-93

Configuring Authentication POST Data Handling

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

Authentication Scheme Challenge
Parameters for Post Data with ECC

Authentication Scheme Challenge
Parameters for Post Data with DCC

MaxPreservedPostDataBytes=9000

MaxPreservedPostDataBytes=9000
TempStateMode=form

c.
2.

3.

Click Apply to submit the changes.

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.

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
User-Defined Webgate

User-Defined Webgate

Post Data Parameters with ECC

Post Data Parameters with DCC

PostDataRestoration=true

PostDataRestoration=true

22-94 Administrator's Guide for Oracle Access Management

Long URL Handling During Authentication

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.

Managing Authentication and Shared Policy Components

22-95

Long URL Handling During Authentication

Table 22–35 identifies Long URL handling functionality with both the ECC and DCC.
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.

22.13.2 About Configuring Long URL Handling
Table 22–36 summarizes the authentication schemes that support authentication Long
URL handling.
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 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–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"

22-96 Administrator's Guide for Oracle Access Management

Using Application Initiated Authentication

Table 22–37

(Cont.) Parameters Required for Long URL Handling

Parameter

Description

ChallengeRedirectMaxMessageBy Configure this user-defined Webgate parameter to limit the size of the
tes
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

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://:/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://:/oamreauthenticate?
redirect_url=http://:/

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.
Managing Authentication and Shared Policy Components

22-97

Using Application Initiated Authentication

1.

Create an http://:/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.

22-98 Administrator's Guide for Oracle Access Management

23
Understanding Credential Collection and Login
23

[20This
]
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
Unless explicitly stated, information in this chapter is the same
for all agent types and Access Manager credential collectors.

Note:

For details about single log-out, see Chapter 27, "Configuring
Centralized Logout for Sessions Involving 11g WebGates".

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.

Understanding Credential Collection and Login

23-1

Logging In with Access Manager Credential Collection

For a detailed comparison of the two mechanisms for credential collection, see
Section 22.5, "Understanding Authentication Methods and Credential Collectors."
Although the DCC is the recommended approach for
credential collection, instructions in this book presume you are using
the ECC unless explicitly stated.

Note:

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.
Note: Success and failure results are the same as described in "Login
Processing with Access Manager-Protected Resources".

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.

23-2 Administrator's Guide for Oracle Access Management

Processing SSO Login with OAM Agents and ECC

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.
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:
■

■
■

Login and Auto Login for
Applications Using Oracle ADF
Security

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"

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".

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

Understanding Credential Collection and Login

23-3

Processing SSO Login with OAM Agents and ECC

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

23-4 Administrator's Guide for Oracle Access Management

Processing SSO Login with OAM Agents and DCC

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.

■

9.

One for OAM Server: OAM_ID

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.

Understanding Credential Collection and Login

23-5

Processing SSO Login with OAM Agents and DCC

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

Separate DCC and Resource Webgates: A sample deployment with segregated DCC
is shown in Figure 23–2.

23-6 Administrator's Guide for Oracle Access Management

Processing SSO Login with OAM Agents and DCC

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.

Understanding Credential Collection and Login

23-7

Processing SSO Login with OAM Agents and DCC

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.

Note:

Figure 23–3 Combined DCC and WebGate Configuration

OHS

1 3 4

3
2

9

DCC
WebGate

Login App with pages:
Login / CredCollection
Logout
Error

5
Browser
User Agent

8
OAM Server
Instance
6
OAM
7
Proxy
AUTHN
Plugin

Legend
Front channel: HTTPS
User-Agent channel: HTTPS
Other: SSL

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.

See Also: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate" on page 27-6

23-8 Administrator's Guide for Oracle Access Management

Processing SSO Login with OSSO Agents (mod_osso) and ECC

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.
mod_osso does not support authorization either on its own or
using Access Manager 11g policies.

Note:

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:

4.

■

Checks for the existence of an SSO cookie.

■

Checks policies to determine if the resource protected and if so, how?

OAM Server logs and returns decisions.

Understanding Credential Collection and Login

23-9

Configuring 11g WebGates and Authentication Policy for DCC

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

■

9.

Global Inactivity Out: A domain-level cookie GITO, described in mod_osso
Cookies.

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.

23-10 Administrator's Guide for Oracle Access Management

Configuring 11g WebGates and Authentication Policy for DCC

If your environment uses the ECC, go to "Completing
Password Policy Configuration".

Note:

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.
Note:

If the DCC is combined with a Resource WebGate, skip Step 3.

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:
Agent & Artifacts

Artifacts

11g WebGate/Access Client

From the AdminServer (Console) host:

ObAccessClient.xml and
cwallet.sso
Simple or Cert Mode

$DOMAIN_HOME/output/$Agent_Name/
To the Agent host: $11gWG_install_dir/webgate/config
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"

5.

Restart the OHS Web server.

Understanding Credential Collection and Login

23-11

Configuring 11g WebGates and Authentication Policy for DCC

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.
See Also: Oracle Fusion Middleware Developer's Guide for Oracle Access
Management

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).
This example refers to the PasswordPolicyValidationScheme
set for the DCC in Section 24.7, "Configuring Password Policy
Authentication."

Note:

23-12 Administrator's Guide for Oracle Access Management

Configuring 11g WebGates and Authentication Policy for DCC

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.
2.

Perform Step 2 if you have the Chrome Browser. Otherwise, go to Step 4.

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

3.

d.

In the Protection section, Protection Level list, select Excluded, then click
Apply.

e.

Proceed to Step 4.

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.
4.

Perform Step 2 if you have the Chrome Browser. Otherwise, go to Step 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

Understanding Credential Collection and Login

23-13

Tunneling from DCC to Access Manager Over Oracle Access Protocol

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.
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.

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.
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.

Note:

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
23-14 Administrator's Guide for Oracle Access Management

Tunneling from DCC to Access Manager Over Oracle Access Protocol

credential collection during Access Manager authentication. The following sections
contain more details.
■

How DCC Tunneling with OAP Works

■

Configuring OAP Tunneling
For details on the DCC, see Section 22.5.2, "Comparing
Embedded Credential Collector with Detached Credential Collector."

Note:

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=,. For example:
TunneledUrls=/oam,/sampleapp

Understanding Credential Collection and Login

23-15

Configuring a DCC WebGate for X509 Authentication

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.

23-16 Administrator's Guide for Oracle Access Management

Configuring a DCC WebGate for X509 Authentication

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."

Understanding Credential Collection and Login

23-17

Configuring a DCC WebGate for X509 Authentication

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.

23-18 Administrator's Guide for Oracle Access Management

Configuring a DCC WebGate for X509 Authentication

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.

2.

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.

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://:7778/index.html.

Understanding Credential Collection and Login

23-19

Configuring a DCC WebGate for X509 Authentication

2.

Configure an 11g WebGate profile named, for example, XYZ_WG1_DCC on
http://: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.

5.

a.

Name as LDAPScheme_DCC

b.

Challenge redirect URL is http://:/ (http://:7779/)

c.

Challenge URL : /oamsso-bin/login.pl

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://: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.
$ /bin/owm

2.

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.

Create and export the server request file as server.csr using OWM.
a.

Select Operations > Export Certificate Request.

23-20 Administrator's Guide for Oracle Access Management

Configuring a DCC WebGate for X509 Authentication

b.
3.

Save as server.csr

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 /
/ca.pem -CAkey //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.

5.

6.

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.

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.

Edit the Oracle HTTP Server (OHS) ssl.conf file to point to this wallet as follows.
#Path to the wallet
SSLWallet "//wallet"
SSLVerifyClient require

ssl.conf is located at //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.

Understanding Credential Collection and Login

23-21

Configuring a DCC WebGate for X509 Authentication

Figure 23–10

New X509 Scheme

3.

Import .p12 into your browser.

4.

Access the protected resource via its SSL port. For example:
https://:/index.html

A popup is displayed asking which certificate to use. Select the appropriate
certificate and the requested resource is accessed.

23-22 Administrator's Guide for Oracle Access Management

24
Using Password Policy
24

[21Access
]
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.

Using Password Policy 24-1

Enabling Password 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.

24-2 Administrator's Guide for Oracle Access Management

Configuring Password Policy

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.

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.

Using Password Policy 24-3

Configuring Password Policy

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.

24-4 Administrator's Guide for Oracle Access Management

Specifying Credential Collector URLs with Password Policy

Table 24–2 (Cont.) Password Policy Elements
Element

Description

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.

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.

Using Password Policy 24-5

Specifying Credential Collector URLs with Password Policy

Table 24–3

Specifying Credential Collectors and Related Forms for Authentication

In the . . .

For the ECC . . .

For the DCC . . .

OAM Agent Registration

N/A.

Check the box beside Allow Management
Operations in the OAM Agent registration page.

DCC Only

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

■

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_
Multi-step authentication: /pages/mfa_ HOME/webgate/ohs/oamsso-bin/*pl, and
$WEBGATE_
login.jsp
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

User Identity Store

Password Policy Validation
Authentication Module

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.
Enter the Default Store as the KEY_
IDSTORE_REF for each of the three plug-ins
/ steps (with an Error redirect on Failure):

Enter the DCC password page:
Password Service URL for DCC:
/oamsso-bin/login.pl
See Also: "Locating and Updating DCC Forms for
Password Policy"
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"

Same for both DCC and ECC:

See Also:
■

■

Authentication Scheme,
Challenge Redirect URL

Table 22–13, " Parameter Details for
Various Plug-ins"
"Configuring the Password Policy
Validation Authentication Module"

Enter the Credential Collector host:
■

For ECC, relative URI format:
/oam/server (server prepends the
host:port)

See Also: "Configuring the
PasswordPolicyValidationScheme"

24-6 Administrator's Guide for Oracle Access Management

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

Table 24–3 (Cont.) Specifying Credential Collectors and Related Forms for Authentication
In the . . .

For the ECC . . .

For the DCC . . .

Authentication Scheme,
Challenge URL

Enter the Credential Collector login form
relative URI:

Enter the Credential Collector login form relative
URI:

■

For ECC: /pages/login.jsp

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"

■

For DCC: /oamsso-bin/login.pl

See Also: "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"

Using Password Policy 24-7

Using the Oracle-Provided Password Forms

Table 24–3 (Cont.) Specifying Credential Collectors and Related Forms for Authentication
In the . . .
Server Error Mode

Authentication Policy

For the ECC . . .

For the DCC . . .

Same for both DCC and ECC.

Same for both DCC and ECC.

See: "Setting the Error Message Mode for
Password Policy Messages" on page 24-21

See: "Setting the Error Message Mode for Password
Policy Messages" on page 24-21

Credential collectors in authentication
policies:

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"

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"

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
See "Configuring Centralized Logout for 11g
WebGates" on page 27-4

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

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.

24-8 Administrator's Guide for Oracle Access Management

Using the Oracle-Provided Password Forms

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.

DCC pages

■

Login page: /pages/login.jsp

■

Logout page: /pages/logout.jsp

■

Error page: /pages/servererror.jsp

■

Multi-step authentication page: /pages/mfa.jsp

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 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–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.

Using Password Policy 24-9

Managing Global Password Policy

Table 24–5 (Cont.) Password Management Forms and Functions
Form

Function

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.

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.

24-10 Administrator's Guide for Oracle Access Management

Managing Global Password Policy

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:

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 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.
Note:

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.

ECC Password Service URL

DCC Password Service URL

/pages/login.jsp

/oamsso-bin/login.pl

On the Password Policy page, enter values (Table 24–2) based on requirements for
your enterprise. For example:
Using Password Policy 24-11

Managing Global Password Policy

■

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.
See Also:

"Using the System Store for User Identities"

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.

4.

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".

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

24-12 Administrator's Guide for Oracle Access Management

Managing Global Password Policy

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.
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

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.
Using Password Policy 24-13

Managing Global Password Policy

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

obuseraccountcontrol

Boolean string value.

Used during forced password
change for first time user login (or
forced password change initiated by
the Administrator.

true | false

Used to represent a disabled user.

Non-encrypted string value.

Empty string represents false.

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.

obLoginTrvCount

The number of consecutive login
failures by the user. This counter is
reset on the first correct password
entry.

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

Seconds (since 01 January, 1970)
Non-encrypted integer value.

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  –h  -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".

24-14 Administrator's Guide for Oracle Access Management

Configuring Password Policy Authentication

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.
See Also:

"Understanding Administrator Roles" on page 5-26

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:

4.

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.

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.
There are no credential collector dependencies when defining
the Password Policy Validation Module for authentication.

Note:

A sample module is shown in Figure 24–2. The User Password Status Step is the
unique step that relies on the UserPasswordPolicyPlugin.
UserPasswordPolicyPlugin is supported only when using
LDAP based authentication modules. It does not work with non
LDAP authentication modules.

Note:

Using Password Policy 24-15

Configuring Password Policy Authentication

Figure 24–2 Password Policy Validation Authentication Module with Orchestrated
Plug-ins

Each step identifies the action provided by a specific named plug-in.
See Also: "Orchestrating Multi-Step Authentication with Plug-in
Based Modules".

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.

24-16 Administrator's Guide for Oracle Access Management

Configuring Password Policy Authentication

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.

User Password Status Step

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.

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.

NEW_USERPSWD_BEHAVIOR

Configures retroactive behavior of the new-user
password-policy. Values are either:

Default: The registered Default Store.

■

■

FORCEPASSWORDCHANGE: Forces a password
change.
NOFORCEPASSWORDCHANGE: The password
policy change does not affect user passwords that
are already set.

Default: NOFORCEPASSWORDCHANGE

Using Password Policy 24-17

Configuring Password Policy Authentication

Table 24–8 (Cont.) User Password Step Details
Step Name

Step Details

Description

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

Prerequisites
Defining Your Global Password Policy
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).

Note:

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".

24-18 Administrator's Guide for Oracle Access Management

Configuring Password Policy Authentication

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.
Differences between values for the ECC versus the DCC
include (Table 24–3):

Note:
■

Challenge Redirect URL: Credential Collector host and port

■

Challenge URL: Credential Collector Pages

■

Challenge Parameters: Table 22–22

Prerequisites
Configuring the Password Policy Validation Authentication Module
See Also:

"Managing Authentication Schemes"

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:
ECC Challenge Parameters

DCC Challenge Parameters

OverrideRetryLimit=0
initial_command=NONE

OverrideRetryLimit=0
creds=userid password

Using Password Policy 24-19

Configuring Password Policy Authentication

ECC Challenge Parameters

DCC Challenge Parameters
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

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).
See Also: "Adding Your PasswordPolicyValidationScheme to ECC
Authentication Policy"
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).

24-20 Administrator's Guide for Oracle Access Management

Completing Password Policy Configuration

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
In the Oracle Access Management Console, click Configuration at the top of the
window.

1.
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:

Using Password Policy 24-21

Completing Password Policy Configuration

dn: cn=default,cn=pwdPolicies,cn=Common,cn=Products,cn=OracleContext,

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.
You can disable the Oracle Internet Directory password policy by setting the
orclpwdpolicyenable parameter to zero (0).
See Also: The various attributes described in Oracle Fusion
Middleware Administrator's Guide for Oracle Internet Directory

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.

24-22 Administrator's Guide for Oracle Access Management

Completing Password Policy Configuration

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.

Note:

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:

... ...

false


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):

11.1.1.3
2


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.
See Also: Chapter 27, "Configuring Centralized Logout for Sessions
Involving 11g WebGates"

To confirm your multi-step authentication
1. Confirm access after login:

2.

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.

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.
Using Password Policy 24-23

Configuring the IPFUserPasswordPolicyPlugin

3.

4.

5.

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.

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.

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:
3

This procedure assumes:

24-24 Administrator's Guide for Oracle Access Management

Configuring the IPFUserPasswordPolicyPlugin

■

■

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 /config/fmwconfig/ and
make a backup of it before editing.

3.

Modify the file so it contains the following snippet.

3
/oam/pages/pswd.jsp


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 /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

Using Password Policy 24-25

Configuring the IPFUserPasswordPolicyPlugin

Table 24–9 (Cont.) Included LDIF Schema Files
LDAP Directory

LDIF Schema File

OVD

OVD_OblixSchema.ldif, OVD_OracleSchema.ldif

Tivoli

TIVOLI_OblixSchema.ldif, TIVOLI_OracleSchema.ldif

EDIR

EDIR_OblixSchema.ldif, EDIR_OracleSchema.ldif

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."

24-26 Administrator's Guide for Oracle Access Management

25
Managing Policies to Protect Resources and
Enable SSO
25

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"

Managing Policies to Protect Resources and Enable SSO 25-1

Introduction to Application Domain and Policy Creation

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.
To enhance security, Access Manager, by default, will deny
access when a resource is not protected by a policy that explicitly
allows access.

Note:

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.
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.

Note:

■

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

25-2 Administrator's Guide for Oracle Access Management

Introduction to Application Domain and Policy Creation

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.
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.

Note:

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:
Managing Policies to Protect Resources and Enable SSO 25-3

Understanding Application Domain and Policy Management

2.

■

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

Perform all prerequisite tasks for this chapter, as described in:
■

3.

4.

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

Add resource definitions to your Application Domain as described in:
■

5.

6.

7.

8.

9.

Prerequisites

Adding and Managing Policy Resource Definitions

Define your Authentication Policy, as described in:
■

Creating an Authentication Policy for Specific Resources

■

Adding and Managing Policy Responses for SSO

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

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

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

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

25-4 Administrator's Guide for Oracle Access Management

Understanding Application Domain and Policy Management

■

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.

Managing Policies to Protect Resources and Enable SSO 25-5

Understanding Application Domain and Policy 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.

25-6 Administrator's Guide for Oracle Access Management

Understanding Application Domain and Policy Management

See Also:
■

■

"Adding and Managing Policy Resource Definitions" on
page 25-13
Appendix D, "Reviewing Bundled, Generated, and Migrated
Artifacts"

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.

Managing Policies to Protect Resources and Enable SSO 25-7

Understanding Application Domain and Policy Management

Figure 25–5 Authentication Policy Page: Resources and Responses

Initially, all resources are protected. Success and Failure URLs
and Responses must be added manually; no default values are
supplied.

Note:

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/**.
Note: Administrators can change the authentication scheme, specify
Success and Failure URLs, add other resources, and define SSO
Responses.

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.

See Also:

"Introduction to Policy Responses for SSO" on page 25-68

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

25-8 Administrator's Guide for Oracle Access Management

Understanding Application Domain and Policy Management

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 Policies to Protect Resources and Enable SSO 25-9

Managing Application Domains Using the Console

Figure 25–8 Individual Authorization Policy Resources tab

Administrators can also define Conditions, Rules, and Responses for this policy. None
are generated automatically.
See Also:
■
■

"Introduction to Policy Responses for SSO" on page 25-68
"Introduction to Authorization Policy Rules and Conditions" on
page 25-40

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.
25-10 Administrator's Guide for Oracle Access Management

Managing Application Domains Using the Console

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.
Note:

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.

Managing Policies to Protect Resources and Enable SSO 25-11

Managing Application Domains Using the Console

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.
Note:

This Search operation is case sensitive.

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.
See Also:

"Managing Policies and Application Domains Remotely"

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.

25-12 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

■

■

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.
During a Delete operation, if the Application Domain contains
any policy elements, you are alerted.

Note:

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:
Managing Policies to Protect Resources and Enable SSO 25-13

Adding and Managing Policy Resource Definitions

■

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.
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.

Note:

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.

25-14 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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.

Managing Policies to Protect Resources and Enable SSO 25-15

Adding and Managing Policy Resource Definitions

Table 25–1 (Cont.) Resource Definition Elements
Elements

Description

Query

For HTTP resource types only. You can provide a list of Name and Value pairs for use in access
policies.

Name-Value list

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.

25-16 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

Table 25–1 (Cont.) Resource Definition Elements
Elements

Description

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.

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.
See Also:

"About Resource Types and Their Use" on page 22-2

Managing Policies to Protect Resources and Enable SSO 25-17

Adding and Managing Policy Resource Definitions

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.
Table 25–2

HTTP Resources Sample URL Values

Resource

Sample URL Values

Directories

■

/mydirectory

■

/mydirectory/**

■

/mydirectory/projects/index.html

■

/mydirectory/projects/*.html

■

/mydirectory/.../*.html

■

/mydirectory/projects/example.exe

■

/mydirectory/projects/*.exe

■

/mydirectory/**

Pages

Web applications

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.
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:

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.
Note:

No host identifier is associated with a non-HTTP resource

type.
Administrations identify individual resources in the Application Domain using a
specific resource URL. Individual resource URLs need not be unique across domains.

25-18 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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/.../*.
Note: The Access Manager policy model does not support a resource
prefix. In other words, there is no policy inheritance.

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.

Table 25–3

■

Supported wildcard matching is provided for the patterns in Table 25–3

■

Sample Resource URLs and their correctness are shown in Table 25–4

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.

Matches
/foo/bar
/foo/

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.
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.

Managing Policies to Protect Resources and Enable SSO 25-19

Adding and Managing Policy Resource Definitions

Table 25–3 (Cont.) Supported Wildcards in Resource URL Patterns (Precedence Order)
Pattern

Description

Example

[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.

The following URL pattern:

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.

/.../update.html
Matches:
/humanresources/benefits/update.html
/corporate/news/update.html
update.html
See Also: Table 25–4

Does not match /.

/.../ Hierarchy Matches any sequence of one or more characters that starts
and ends with the forward slash character (/).

■

/index.html

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.

/oracle/index.html
/oracle/sales/index.html
index.html
It does not match xyzindex.html or
xyz/index.html.

Host wide; the entirety of the pattern.
/.../* Host
wide

The pattern /.../index.html matches:

■

/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

■

abc\*d only matches abc*d

■

abc\\d only matches abc\d

Escaped special characters are matched literally to the
special characters, if any, within the incoming URL

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.

25-20 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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

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)

Managing Policies to Protect Resources and Enable SSO 25-21

Adding and Managing Policy Resource Definitions

■

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.
Note:

All matching in 11g has been, and remains, case insensitive.

Table 25–5 illustrates the matching pattern for each of several requested URLs.
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

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*
25-22 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

/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.
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*

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
a
a

VALUE
ab
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
area
dept

VALUE
emea
engg

Managing Policies to Protect Resources and Enable SSO 25-23

Adding and Managing Policy Resource Definitions

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
area
dept

VALUE
emea
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
area
dept

VALUE
e*
e*

area
dept

em*
en*

and

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).

25-24 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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:

Managing Policies to Protect Resources and Enable SSO 25-25

Adding and Managing Policy Resource Definitions

■

■

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.
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

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.
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.

25-26 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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).
An error can occur if you specify a host identifier value that is
invalid: The challenge URL is invalid.

Note:

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.
See Also: "Defining Resources in an Application Domain" on
page 25-14

To add resource definitions to an Application Domain
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.

1.

Managing Policies to Protect Resources and Enable SSO 25-27

Adding and Managing Policy Resource Definitions

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)

4.

b.

Click Apply to add this resource to the Application Domain.

c.

Repeat this procedure to add other resources to this Application Domain.

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.

25-28 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Resource Definitions

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.
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

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.

Managing Policies to Protect Resources and Enable SSO 25-29

Adding and Managing Policy Resource Definitions

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.
During a Delete, you are alerted if the resource is associated
with a policy. Without a policy association, the resource is deleted.

Note:

Prerequisites
You must have the desired resource type defined as a shared component. For details,
see "Managing Resource Types" on page 22-2.
See Also: "Defining Resources in an Application Domain" on
page 25-14

To view, modify, or delete resource definitions
Find the Resource, as described in "Searching for a Resource Definition".

1.

■
■

■

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.

25-30 Administrator's Guide for Oracle Access Management

Defining Authentication Policies for Specific Resources

–

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
See Also: "Understanding Application Domain and Policy
Management" on page 25-4

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.

Managing Policies to Protect Resources and Enable SSO 25-31

Defining Authentication Policies for Specific Resources

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.

25-32 Administrator's Guide for Oracle Access Management

Defining Authentication Policies for Specific Resources

Table 25–9 (Cont.) Authentication Policy Elements and Descriptions
Element

Description

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.

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.
See Also:
■

"About the Authentication Policy Page" on page 25-31

■

"Managing Authentication Schemes" on page 22-64

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.

4.

■

Name

■

Authentication Scheme

Optional Elements (Table 25–9): Add as needed for your policy.
■

Description (optional)

■

Success URL

■

Failure URL

Managing Policies to Protect Resources and Enable SSO 25-33

Defining Authentication Policies for Specific Resources

Tip: See Configuring Success and Failure URLs for Authorization
Policies.
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.
See Also:

"About the Authentication Policy Page" on page 25-31

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.

25-34 Administrator's Guide for Oracle Access Management

Defining Authorization Policies for Specific Resources

■

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.
During a Delete operation, you are alerted to confirm removal
of the policy. Confirmation is required to complete the operation.

Note:

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".
See Also:

"About the Authentication Policy Page" on page 25-31

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
See Also: "Understanding Application Domain and Policy
Management" on page 25-4

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:
Managing Policies to Protect Resources and Enable SSO 25-35

Defining Authorization Policies for Specific Resources

■

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.

25-36 Administrator's Guide for Oracle Access Management

Defining Authorization Policies for Specific Resources

Table 25–10

(Cont.) Authorization Policy Elements and Descriptions

Element

Description

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.

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.
See Also: "About Authorization Policies for Specific Resources" on
page 25-36

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.

Managing Policies to Protect Resources and Enable SSO 25-37

Defining Authorization Policies for Specific Resources

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.
See Also: "About Authorization Policies for Specific Resources" on
page 25-36

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.
During a Delete operation, you are alerted to confirm removal
of the policy. Confirmation is required to complete the operation.

Note:

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.

25-38 Administrator's Guide for Oracle Access Management

Configuring Success and Failure URLs for Authorization Policies

To simply alter an element in the policy see "Viewing or Editing an Authentication
Policy".
See Also: "About Authorization Policies for Specific Resources" on
page 25-36

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

Managing Policies to Protect Resources and Enable SSO 25-39

Introduction to Authorization Policy Rules and Conditions

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.

1E8461DFA32AD746AF28BAAAA9F327327941C14CAC216DCFA9AC17985E09
7A0DD603EC1DF5C6D9F5C904ED44952A5D5F
true


Note: The Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference for Identity and Access Management provides details on the
displayAuthZCallBackKey() WLST command.

■

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:

25-40 Administrator's Guide for Oracle Access Management

Introduction to Authorization Policy Rules and Conditions

■

■

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.
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.

Note:

■
■

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.

Managing Policies to Protect Resources and Enable SSO 25-41

Introduction to Authorization Policy Rules and Conditions

Figure 25–16

Individual Authorization Policy Conditions Tab

Table 25–11 describes elements and controls on the Conditions tab.
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

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).

25-42 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

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.

Note:

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

Managing Policies to Protect Resources and Enable SSO 25-43

Defining Authorization Policy Conditions

■

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.
Table 25–12

Add Condition Window Elements

Element

Description

Name

A unique name for this condition.

Type

Description

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)

Optional.

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

25-44 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

Figure 25–18

Condition Containers on the Authorization Policy Page

See Also: "Defining Authorization Policy Conditions" for
information and procedures

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.
You can have more than one instance of a given class of
condition in a policy.

Note:

Prerequisites
The Application Domain must exist.
See Also:

"About Choosing a Condition Type" on page 25-44

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):

5.

■

Name: Enter a unique name.

■

Type list, choose the kind of condition (Identity, for example).

■

Click the Add Selected button.

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

Managing Policies to Protect Resources and Enable SSO 25-45

Defining Authorization Policy Conditions

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.

25-46 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

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.

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.

Managing Policies to Protect Resources and Enable SSO 25-47

Defining Authorization Policy Conditions

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:

Add Filter

■

Type: LDAPSearchFilter

■

Identifier: Your LDAP Search Filter

Click to Add the filter to this identity condition.

25-48 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

Table 25–14

(Cont.) Add Search Filter Elements

Element

Description

Cancel

Click to dismiss the Add Search Filter dialog without adding a
filter.

Figure 25–22 shows the Identity Conditions: Details page, displayed after adding an
LDAP Search Filter.
Figure 25–22

Identity Conditions: Details

See Also:
■

"About LDAP Search Filter Syntax" on page 25-49

■

"Defining Identity Conditions" on page 25-45

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.
Table 25–15

LDAP Search Filter Examples for Access Manager

Filter Type and
Operators
Static LDAP Search
Filters

Description

Syntax Example

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.

(attribute=value)

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.

(businessCategory=dealership)

For example:

Static Searches Using
Wild Cards

As an example of a static filter that uses wild cards, suppose (attribute=*value*)
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 For example:
(*) wildcard.
(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$)

Managing Policies to Protect Resources and Enable SSO 25-49

Defining Authorization Policy Conditions

Table 25–15 (Cont.) LDAP Search Filter Examples for Access Manager
Filter Type and
Operators
Substitution syntax

Description

Syntax Example

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).

(attribute=$attribute$)

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.

For example: The following filter finds
all those in the same organizational
unit as the person logged in to the
application:
(ou=$ou$)

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.
Dynamic Searches Using
Wild Cards

Searches Using the Not
Operator: (!)

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.
The Not operator is supported when constructing a filter.
The optimized algorithm causes the filter (!(sn=white)) to
not give the expected result.

See Also:

(attribute=*$attribute$)
For example:
(postalAddress=*$zipCode$)

((!(sn=white))(objectclass=personO
C))

"Specifying Identity Type Conditions" on page 25-50

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.
See Also: Oracle Fusion Middleware Upgrade Guide for Oracle
Identity Management

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.
You must save each condition definition individually, before
adding or selecting another condition.

Note:

25-50 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

Prerequisites
The Application Domain must exist.
See Also:
■
■

"About Identity Conditions" on page 25-46
"About LDAP Search Filter Support in Identity Conditions" on
page 25-47

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.

■

5.

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.

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

Managing Policies to Protect Resources and Enable SSO 25-51

Defining Authorization Policy Conditions

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.
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.

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.
If the From IP address is greater than the To address, the
condition cannot match any client IP address.

Note:

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.

25-52 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

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.
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.

Note:

Prerequisites
The Application Domain must exist.
See Also:

"About IP4 Range Condition Types" on page 25-52

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.

Managing Policies to Protect Resources and Enable SSO 25-53

Defining Authorization Policy Conditions

■

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.

25-54 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

Table 25–16

Temporal Condition Details

Elements

Description

Start Time

Specifies the hour, minute, and second that this condition begins.

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.

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).

Save the details before closing this page.
See Also:

"Defining Temporal Conditions"

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.
You must save each condition definition individually, before
adding or selecting another condition.

Note:

Prerequisites
The Application Domain must exist.
See Also:

"About Temporal Conditions" on page 25-54

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 Temporal 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
Managing Policies to Protect Resources and Enable SSO 25-55

Defining Authorization Policy Conditions

■

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.
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.

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.

25-56 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

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.
See Also:

"Defining Attribute Conditions"

Figure 25–26

Add Attribute Condition Dialog

Table 25–18

Attribute Condition Elements

Condition

Description

Namespace

Supported namespaces:
■

Request Built-ins

■

Session Built-ins

■

Session (User Session)

■

User (User Attributes)

Managing Policies to Protect Resources and Enable SSO 25-57

Defining Authorization Policy Conditions

Table 25–18

(Cont.) Attribute Condition Elements

Condition

Description

Name

Attribute name, which can be added as follows, depending on the:
■

■

Operator

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

Allowed operators:

Value

■

STARTS WITH

■

EQUALS

■

CONTAINS

■

ENDS WITH

Literal value with no special wildcard characters.

Request Built-ins
Table 25–19 identifies the list of built-in attribute names for Request Built-ins:
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.

Session Built-ins
Table 25–20 identifies the list of attribute names for Session-based attribute-type
conditions.
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.

Example: Attribute Condition Data (Aggregation of Conditions)
Table 25–21 illustrates sample condition data for each allowable namespace.

25-58 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Conditions

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

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.
You must save each condition definition individually, before
adding or selecting another condition.

Note:

Prerequisites
The Application Domain must exist.
See Also:

"About Attribute Conditions" on page 25-54

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.

Managing Policies to Protect Resources and Enable SSO 25-59

Defining Authorization Policy Rules

See Also: "Introduction to Authorization Policy Rules and
Conditions" on page 25-40

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:

25-60 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Rules

■

■

■

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.

Managing Policies to Protect Resources and Enable SSO 25-61

Defining Authorization Policy Rules

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

■

Allow Rule

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.

The rule that allows access based on evaluation of your rules
and the Selected Conditions list.

25-62 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Rules

Table 25–22

(Cont.) Authorization Policy Rules Elements

Element

Description

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).

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.

Managing Policies to Protect Resources and Enable SSO 25-63

Defining Authorization Policy Rules

Figure 25–28

Rules Tab: Expression Rule Mode

Table 25–23 describes the elements on the Rule tab in Expression mode.
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 identifies the operators you can use when building an authorization
expression.
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.

25-64 Administrator's Guide for Oracle Access Management

Defining Authorization Policy Rules

Table 25–24

(Cont.) Operators for Expressions in Authorization Rules

Operator

Description

&

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.

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

Managing Policies to Protect Resources and Enable SSO 25-65

Defining Authorization Policy Rules

■

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.
See Also:

"About Defining Rules in an Authorization Policy"

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:

4.

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.

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.

25-66 Administrator's Guide for Oracle Access Management

Configuring Policy Ordering

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".)
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.

Note:

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.

Managing Policies to Protect Resources and Enable SSO 25-67

Introduction to Policy Responses for SSO

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.
Note:

There are no responses in Token Issuance Policies.

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.
Oracle Access Manager 10g provided data passage to (and
between) applications only by redirecting to URLs in a specific
sequence.

Note:

There are no default response provided. Figure 25–30 illustrates an Authorization
Policy Response defined by an Administrator in the Oracle Access Management

25-68 Administrator's Guide for Oracle Access Management

Introduction to Policy Responses for SSO

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
Cookie, Header, and Session responses are supported.

1.
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).

Managing Policies to Protect Resources and Enable SSO 25-69

Introduction to Policy Responses for SSO

Table 25–25

(Cont.) Response Elements

Element

Description

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.

■

Value

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.

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"

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
Note:

Certain variables include an attribute: $ns.name.attribute

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:

25-70 Administrator's Guide for Oracle Access Management

Introduction to Policy Responses for SSO

■

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.

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.

Managing Policies to Protect Resources and Enable SSO 25-71

Introduction to Policy Responses for SSO

Table 25–28

(Cont.) Namespace User Variables

Namespace

Description

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

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
See Also: Guidelines for Authorization Responses Based on
Conditions

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.
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

25-72 Administrator's Guide for Oracle Access Management

Introduction to Policy Responses for SSO

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.
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 client: Agent ID: ${request.agent_id}, Browser IP:
$request.client_ip

HTTP_OAM_CLIENTINFO

${user.userid}'s groups: ${user.groups}, description:
${user.attr.description}

HTTP_OAM_USERINFO

Session creation/expiration/count:
${session.creation}/${session.expiration}/${session.count}

HTTP_OAM_SESSIONINFO

$user.userid

HTTP_OAM_USERID name

oam_clientinfo

oam_userinfo

oam_sessioninfo

oam_app_user

Runtime resource:
myhost.domain.com:1234/cgi-bin/myres3

Runtime client: Agent ID: RREG_OAM, Browser
IP: 123.45.67.891

WebLogic's groups: Administrators, description: This
user is the default Administrator

Session creation/expiration/count: Tue Oct 23
17:47:42 PST 2011/Wed Oct 24 01:47:42 PST 2011/7

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"

Managing Policies to Protect Resources and Enable SSO 25-73

Introduction to Policy Responses for SSO

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.
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:

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
Note:

Verify the Responses.

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.

25-74 Administrator's Guide for Oracle Access Management

Adding and Managing Policy Responses for SSO

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.
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).

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.
See Also:

"Introduction to Policy Responses for SSO" on page 25-68

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 Value field, enter a value for this response. For example:
$namespace1.var1

Managing Policies to Protect Resources and Enable SSO 25-75

Validating Authentication and Authorization in an Application Domain

See Also: "About the Namespace and Variable Names for Policy
Responses" on page 25-70
■

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.
See Also:

"Introduction to Policy Responses for SSO" on page 25-68

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.

25-76 Administrator's Guide for Oracle Access Management

Understanding Remote Policy and Application Domain Management

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.

See Also: Chapter 26, "Validating Connectivity and Policies Using
the Access Tester"

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

Managing Policies to Protect Resources and Enable SSO 25-77

Understanding Remote Policy and Application Domain 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.
Application Domain removal is a manual task that must be
performed using the Oracle Access Management Console.

Note:

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   [prompt_flag] [component.oam.config_file] 
value
Table 25–32

Remote Policy Management Modes, Templates, and Flags

Mode and Template

Description

policyCreate

Allows Administrators to create Host Identifiers and an Application
Domain without registering an Agent.

$OAM_REG_HOME/input/
CreatePolicyRequest.xml

./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

25-78 Administrator's Guide for Oracle Access Management

Understanding Remote Policy and Application Domain Management

Table 25–32

(Cont.) Remote Policy Management Modes, Templates, and Flags

Mode and Template

Description

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):
 'tab' 
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

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  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:

Managing Policies to Protect Resources and Enable SSO 25-79

Understanding Remote Policy and Application Domain Management

■

■

Elements for Authentication and Authorization Policies and resources are
provided
No  element or related elements are provided
See Also: "About Remote Policy Management and Templates" on
page 25-80

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 
element.
See Also: "About Remote Policy Management and Templates" on
page 25-80

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.
Table 15–8, " Common Elements in Remote Registration
Requests" for a description of elements common to remote registration
and remote management.

See Also:

25-80 Administrator's Guide for Oracle Access Management

Understanding Remote Policy and Application Domain Management

Table 25–33

Remote Management Template Elements

Element

Description




Specifies the name and description for
the Authentication Policy (to use when
creating a new policy or updating an
existing policy).



AuthenticationPolicy1
Authentication policy
created using policyUpdate mode of
rreg tool
.
.





Specifies the Authentication Scheme to
use in the Authentication Policy.


.
.
authnSchemeName>LDAPScheme

.
.





Identifies a resource that requires
authentication using the policy.


.
.

- 
/res1



.
.



Specifies the name and description for
the Authorization Policy (to use when
creating it anew or updating an existing
policy).



AuthorizationPolicy1
Authorization policy
created using policyUpdate mode of
rreg tool
.
.



Identifies a resource that requires
Authorization using the Authorization
Policy.


.
.

- 
/res1



.
.








Example

Managing Policies to Protect Resources and Enable SSO 25-81

Managing Policies and Application Domains Remotely

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.

3.

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

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.
25-82 Administrator's Guide for Oracle Access Management

Defining an Application

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.

Note:

Managing Policies to Protect Resources and Enable SSO 25-83

Defining an Application

25-84 Administrator's Guide for Oracle Access Management

26
Validating Connectivity and Policies Using the
Access Tester
62

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.

Validating Connectivity and Policies Using the Access Tester 26-1

Introduction to the Access Tester for Access Manager 11g

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.

26-2 Administrator's Guide for Oracle Access Management

Introduction to the Access Tester for Access Manager 11g

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.

Validating Connectivity and Policies Using the Access Tester 26-3

Introduction to the Access Tester for Access Manager 11g

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.

26-4 Administrator's Guide for Oracle Access Management

Introduction to the Access Tester for Access Manager 11g

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.
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

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
Validating Connectivity and Policies Using the Access Tester 26-5

Introduction to the Access Tester for Access Manager 11g

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.

26-6 Administrator's Guide for Oracle Access Management

Introduction to the Access Tester for Access Manager 11g

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.

Note:

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.
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.

Validating Connectivity and Policies Using the Access Tester 26-7

Installing and Starting the Access Tester

Table 26–1 (Cont.) User Interactions: Tester Console Mode versus Command Line Mode Operations
Tester Console mode

Command Line Mode

When the test completes, the Access Tester generates:

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

■

■

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.

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"

26-8 Administrator's Guide for Oracle Access Management

Installing and Starting the Access Tester

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
log.traceconnfile

display.fontname

Access Tester
Mode

Description and Command Syntax

Tester Console and
Command Line
modes

Logs connection details to the specified file
name.

Tester Console
mode

Starts the Access Tester with the specified font.
This could be useful in compensating for
differences in display resolution.

-Dlog.traceconnfile=""

- Ddisplay.fontname =""
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 =""

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  in command line
mode.
-Dscript.scriptfile=""

Validating Connectivity and Policies Using the Access Tester 26-9

Installing and Starting the Access Tester

Table 26–2 (Cont.) Access Tester Supported System Properties
Property
control.configfile

Access Tester
Mode
Command Line
mode

Description and Command Syntax
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=""

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 _
.
-Dcontrol.testname=""

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 _
.
-Dcontrol.testnumber="".
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 Command Line
stats
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"

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.

26-10 Administrator's Guide for Oracle Access Management

Installing and Starting the Access Tester

See Also:
■
■

"About Access Tester Supported System Properties"
"Starting the Access Tester with System Properties For Use in
Command Line Mode"

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.
See Also: "About Access Tester Supported System Properties" on
page 26-9

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.
Validating Connectivity and Policies Using the Access Tester

26-11

Introduction to the Access Tester Console and Navigation

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.
See Also: "About Access Tester Supported System Properties" on
page 26-9

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.

26-12 Administrator's Guide for Oracle Access Management

Introduction to the Access Tester Console and Navigation

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.

Validating Connectivity and Policies Using the Access Tester

26-13

Introduction to the Access Tester Console and Navigation

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.
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"

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–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

26-14 Administrator's Guide for Oracle Access Management

Testing Connectivity and Policies from the Access Tester Console

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- combination defined for each menu command.
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:

Test

■

Cut

■

Copy

■

Paste

■

Clear all fields

■

Import URI fields from a saved URL

■

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.

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.
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.

Note:

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.

Validating Connectivity and Policies Using the Access Tester

26-15

Testing Connectivity and Policies from the Access Tester Console

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.
Caution: Once the connection is established, it cannot be changed
until you restart the Access Tester Console.

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.

26-16 Administrator's Guide for Oracle Access Management

Testing Connectivity and Policies from the Access Tester Console

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.

After entering information and establishing a connection, you can save details to a
configuration file that can be re-used later.
See Also: "Establishing a Connection Between the Access Tester and
the OAM Server"

Validating Connectivity and Policies Using the Access Tester

26-17

Testing Connectivity and Policies from the Access Tester Console

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.
Cert mode requires the presence of keystores generated as
described in Appendix C, "Securing Communication"

Note:

Prerequisites
Installing and Starting the Access Tester
See Also:

"About the Connection Panel"

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.

26-18 Administrator's Guide for Oracle Access Management

Testing Connectivity and Policies from the Access Tester Console

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  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  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.

Validating Connectivity and Policies Using the Access Tester

26-19

Testing Connectivity and Policies from the Access Tester Console

Table 26–8 (Cont.) Protected Resource URI Panel Fields and Controls
Field or Control

Description

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.

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.
See Also:
■

"Validating Resource Protection from the Access Tester Console"

■

"Creating and Managing Test Cases and Scripts" on page 26-24

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
See Also:

"About the Protected Resource URI Panel"

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

26-20 Administrator's Guide for Oracle Access Management

Testing Connectivity and Policies from the Access Tester Console

■

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.

Validating Connectivity and Policies Using the Access Tester

26-21

Testing Connectivity and Policies from the Access Tester Console

Table 26–9 (Cont.) Access Tester User Identity Panel Fields and Controls
Field or Control

Description

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.

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.
See Also:
■

"Testing User Authentication from the Access Tester Console"

■

"Creating and Managing Test Cases and Scripts" on page 26-24

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.
See Also:

"About the User Identity Panel"

To test user credential authentication
In the Access Tester User Identity panel, enter information for the user to be
authenticated (Table 26–9).

1.
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.

26-22 Administrator's Guide for Oracle Access Management

Testing Connectivity and Policies from the Access Tester Console

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.
See Also:

"About the User Identity Panel"

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.

Note:

To test user authorization
In the Access Tester User Identity panel, confirm the user is authenticated
(Table 26–9).

1.
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

Validating Connectivity and Policies Using the Access Tester

26-23

Creating and Managing Test Cases and Scripts

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
[2/3/12
[2/3/12
[2/3/12
187ms
[2/3/12
...

5.

11:03
11:03
11:03
11:03

PM][info]
PM][info]
PM][info]
PM][info]

Summary statistics
Matched 4 of 4, avg latency 232ms vs 238ms
Validate: matched 2 of 2, avg latency 570ms vs 578ms
Authenticate: matched 1 of 1, avg latency 187ms vs

11:03 PM][info] Authorize: matched 1 of 1, avg latency 172ms vs 188ms

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

26-24 Administrator's Guide for Oracle Access Management

Creating and Managing Test Cases and Scripts

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

Validating Connectivity and Policies Using the Access Tester

26-25

Creating and Managing Test Cases and Scripts

■

An authorization request and response

Table 26–10 describes the location of the capture options.
Table 26–10

Access Tester Capture Request Options

Location

Description

Test menu

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).

Capture last "..." request
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).

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
Initiate a request from the Access Tester Console, as described in "Testing
Connectivity and Policies from the Access Tester Console" on page 26-15.

1.
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.
Do not clear the capture queue until you have captured all the
test cases you want to include in the script.

Note:

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

26-26 Administrator's Guide for Oracle Access Management

Creating and Managing Test Cases and Scripts

■

Allows comparison of test execution results against "Known Good" results

Following are the locations of the Generate Script command.
Table 26–11

Generate Script Command

Location of the Command

Description

Test menu

Select Generate Script from the Test menu to initiate creation of the
script containing your captured test cases.

Generate Script
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.

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.

Validating Connectivity and Policies Using the Access Tester

26-27

Creating and Managing Test Cases and Scripts

Table 26–12

Test Script Control Parameters

Control Parameter

Description

ignorecontent=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

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

26-28 Administrator's Guide for Oracle Access Management

Creating and Managing Test Cases and Scripts

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.
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.

Note:

Table 26–13 describes the commands to execute a test script.
Table 26–13

Run Test Script Commands

Location

Description

Test menu

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.

Run Script
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.

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.
Validating Connectivity and Policies Using the Access Tester

26-29

Creating and Managing Test Cases and Scripts

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".

5.

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).

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 _
.
Note: Shell scripts can automate generating the bundle by providing
testname and testnumber command line parameters.

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 _
:
The target XML script contains the new test cases: __
_












http
oam_server1
7777
/index.html
Get


admin1
00030d05101b050c42

111.222.3.4



26-32 Administrator's Guide for Oracle Access Management

Evaluating Scripts, Log File, and Statistics

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









http
oam_server1
7777
/index.html
Get




Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)

LDAPScheme
2
2
http://emerald.uk.example.com:14100/oam/server/






http
oam_server1
7777
/index.html
Get


weblogic
00030d05101b050c42

192.168.1.8




Major code: 10(CredentialsAccepted) Minor code:

Validating Connectivity and Policies Using the Access Tester

26-33

Evaluating Scripts, Log File, and Statistics

2(NoCode)

cn=weblogic,dc=uk,dc=example,dc=com






http
oam_server1
7777
/index.html
Get


weblogic
00030d05101b050c42

192.168.1.8




Major code: 8(Allow) Minor code: 2(NoCode)






http
oam_server1
7777
/index.html
Get




Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)






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.

26-34 Administrator's Guide for Oracle Access Management

Evaluating Scripts, Log File, and Statistics

Example 26–3

Output File Generated During a Test Run









http
oam_server1
7777
/index.html
Get




Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)

LDAPScheme
2
2
http://emerald.uk.example.com:14100/oam/server/







http
oam_server1
7777
/index.html
Get


weblogic
00030d05101b050c42

111.222.3.4




Major code: 10(CredentialsAccepted) Minor code:
2(NoCode)

cn=weblogic,dc=us,dc=oracle,dc=com






Validating Connectivity and Policies Using the Access Tester

26-35

Evaluating Scripts, Log File, and Statistics


http
oam_server1
7777
/index.html
Get


weblogic
00030d05101b050c42

111.222.3.4




Major code: 8(Allow) Minor code: 2(NoCode)






http
oam_server1
7777
/index.html
Get




Major code: 4(ResrcOpProtected) Minor code:
2(NoCode)






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,




26-36 Administrator's Guide for Oracle Access Management

Evaluating Scripts, Log File, and Statistics


4
4
238232


2
2
578
570


1
1
187
187


1
1
188
172





2
0
0
0
1156


1
0
0
0
187


1
0
0
0
188




2
0
0
0
1140


1
0

Validating Connectivity and Policies Using the Access Tester

26-37

Evaluating Scripts, Log File, and Statistics

0
0
187


1
0
0
0
172






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

26-38 Administrator's Guide for Oracle Access Management

Evaluating Scripts, Log File, and Statistics

[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'

Validating Connectivity and Policies Using the Access Tester

26-39

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

[2This
]
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
See Also: Different agents require different logout implementation
steps described as follows:
■

10g Webgate logout Chapter 30

■

OSSO Agent (mod_osso) logout Chapter 29

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
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-1

Introduction to Centralized Logout for Access Manager 11g

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.
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.

Note:

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.
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.

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

27-2 Administrator's Guide for Oracle Access Management

Introduction to Centralized Logout for Access Manager 11g

loggedout to empty and expires OAMAuthnCookie__ 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

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.

10g and 11g WebGates

■
■

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 Sessions Involving 11g WebGates 27-3

Configuring Centralized Logout for 11g WebGates

Table 27–2 (Cont.) Logout Details After Registration (ObAccessClient.xml)
Element

Description

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__
 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.

■

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
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

27-4 Administrator's Guide for Oracle Access Management

Configuring Centralized Logout for 11g WebGates

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.
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.
Note:

See Also: "Configuring Logout When Using Detached Credential
Collector-Enabled WebGate" on page 27-6

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.
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.
Note:

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.

Configuring Centralized Logout for Sessions Involving 11g WebGates 27-5

Validating Global Sign-On and Centralized Logout

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 URLsGets 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
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"
Note:

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

27-6 Administrator's Guide for Oracle Access Management

Validating Global Sign-On and Centralized Logout

■

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:

2.

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.

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.
Configuring Centralized Logout for Sessions Involving 11g WebGates 27-7

Validating Global Sign-On and Centralized Logout

5.

c.

Confirm that the protected resource is served.

d.

Remain in the same browser session and proceed to Step 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:

2.

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.

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.

27-8 Administrator's Guide for Oracle Access Management

Part VII
Part 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

[23If
]
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.
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.

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.

Registering and Managing Legacy OpenSSO Agents 28-1

Introduction to OpenSSO, Agents, Migration and Co-existence

OpenSSO Agents must be registered with Access Manager to
use OAM Server instead of the OpenSSO Server.

Note:

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).
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

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

28-2 Administrator's Guide for Oracle Access Management

Introduction to OpenSSO, Agents, Migration and Co-existence

See Also: Oracle Fusion Middleware Upgrade Guide for Oracle Identity
and Access Management

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.
See Also:
Table 28–2

"Migrated Artifacts: OpenSSO" on page D-13

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

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.
Note:

An OpenSSO policy referral policy is not migrated.

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.
An OpenSSO policy containing artifacts with no rules is not a
valid policy.

Note:

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.

Registering and Managing Legacy OpenSSO Agents 28-3

Introduction to OpenSSO, Agents, Migration and Co-existence

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.

28-4 Administrator's Guide for Oracle Access Management

Introduction to OpenSSO, Agents, Migration and Co-existence

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.

■

■
■

■

SSO Controller
SSO Engine

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

Fulfills protocol requests by invoking functional components (SSO Engine, Authentication Engine,
and so on):
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.

Registering and Managing Legacy OpenSSO Agents 28-5

Runtime Processing Between OpenSSO Agents and Access Manager

Table 28–3 (Cont.) OpenSSO Reliance on Access Manager
Component

Description

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

Oracle Access
Management Console

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.
Administrators use the console to:
■
■

Remote registration
utility

Provision/register OpenSSO Agents
Manage an Application Domain and authentication and authorization policies for protected
resources.

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.

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.

28-6 Administrator's Guide for Oracle Access Management

Runtime Processing Between OpenSSO Agents and Access Manager

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.

Registering and Managing Legacy OpenSSO Agents 28-7

Runtime Processing Between OpenSSO Agents and Access Manager

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.

28-8 Administrator's Guide for Oracle Access Management

Runtime Processing Between OpenSSO Agents and Access Manager

Table 28–4 (Cont.) Access Manager Processing with OpenSSO
Functionality
End User Session Validation

Description
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
OpenSSO agents can request user profile attributes once the user is successfully logged in and a
retrieval for Web Agent types 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
OpenSSO J2EE agents use jax-rpc calls to retrieve user profile attributes. The flow is similar as
retrieval for J2EE Agent types 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.

Registering and Managing Legacy OpenSSO Agents 28-9

Understanding OpenSSO Agent Registration Parameters

Table 28–4 (Cont.) Access Manager Processing with OpenSSO
Functionality

Description

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 Generation 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

■

Auditing

Log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE),
each of which indicates severity in descending order.

Using the OAM Server audit component to:

Polling

■

Audit Login events

■

Audit Logout success events

Polling is not Supported. Only Session Destroy notifications are supported by the OpenSSO
Proxy.

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.

28-10 Administrator's Guide for Oracle Access Management

Understanding OpenSSO Agent Registration Parameters

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
Agent Type

Description
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

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.

Re-enter Password

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.

Registering and Managing Legacy OpenSSO Agents

28-11

Understanding OpenSSO Agent Registration Parameters

Table 28–5 (Cont.) Elements on the New OpenSSO Agent Page
Element

Description

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.

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.
Table 28–6

Relocating OpenSSO Artifacts

From AdminServer . . .

To OpenSSO Agent /config Directory

$/Oracle_
IDM1/oam/server/rreg/client/rreg/output

$Policy-Agent-base/AgentInstance-Dir/config/

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.

28-12 Administrator's Guide for Oracle Access Management

Understanding OpenSSO Agent Registration Parameters

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.

Registering and Managing Legacy OpenSSO Agents

28-13

Understanding OpenSSO Agent Registration Parameters

Figure 28–4 Expanded OpenSSO J2EE Agent Registration Page

Table 28–7 describes all elements on expanded OpenSSO Agent registration pages.

28-14 Administrator's Guide for Oracle Access Management

Understanding OpenSSO Agent Registration Parameters

Table 28–7

Expanded OpenSSO Agent Registration Elements

Element
Status

Description
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:

Registering and Managing Legacy OpenSSO Agents

28-15

Understanding OpenSSO Agent Registration Parameters

Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element

Description

Enable Cookie
Encoding

Identifies whether cookie encoding is enabled or not.
Default: Enabled

J2EE-type Agent
Only
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
Access Denied URI

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.
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

Defines the filesystem directory path to the local component event logging file.

Web-type Agent
Only

Default:

28-16 Administrator's Guide for Oracle Access Management

Understanding OpenSSO Agent Registration Parameters

Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element
Local Log File

Description
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

Registering and Managing Legacy OpenSSO Agents

28-17

Understanding OpenSSO Agent Registration Parameters

Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element

Description

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  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
Value: 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://:/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

28-18 Administrator's Guide for Oracle Access Management

Registering and Managing OpenSSO Agents Using the Console

Table 28–7 (Cont.) Expanded OpenSSO Agent Registration Elements
Element

Description

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.

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

Registering and Managing Legacy OpenSSO Agents

28-19

Registering and Managing OpenSSO Agents Using the Console

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.
Only centralized configuration mode is supported for new
OpenSSO Agent creation.

Note:

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
See Also:

"Understanding OpenSSO Agent Registration Parameters"

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:
OpenSSO Properties Files From ...

Path ...

From the AdminServer (Console) host

$DOMAIN_HOME/output/$Agent_Name/

28-20 Administrator's Guide for Oracle Access Management

■

OpenSSOAgentBootstrap.properties

■

OpenSSOAgentConfiguration.properties

Registering and Managing OpenSSO Agents Using the Console

9.

OpenSSO Properties Files From ...

Path ...

To the OpenSSO Agent host Web server $OHS_
dir/config.

For example:
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/

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.
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.

Note:

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.
See Also: "About the Expanded OpenSSO Agent Page and
Parameters" on page 28-12

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.

2.

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.

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.
Registering and Managing Legacy OpenSSO Agents

28-21

Performing Remote Registration for OpenSSO Agents

c.
3.

Copy OpenSSO Agent configuration files only if the Agent name, password,
or security mode was changed.

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
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

Create Policies:

$OAM_REG_HOME/input/CreatePolicyRequest.xml

Create New Host Identifiers and
an Application Domain without
Registering an Agent

See Also: "Managing Policies and Application Domains Remotely" on
page 25-82

Update Policies:

$OAM_REG_HOME/input/UpdatePolicyRequest.xml

Existing Host Identifiers and
Application Domain (not
associated with an Agent
Registration)

See Also: "Managing Policies and Application Domains Remotely" on
page 25-82

See Also: "Updating Agents Remotely" on page 15-38

Remote OpenSSO Agent registration automatically:
28-22 Administrator's Guide for Oracle Access Management

Performing Remote Registration for OpenSSO Agents

■

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



Elements common to all remote
registration request templates.

See Table 15–8, " Common
Elements in Remote Registration
Requests"



Choose between J2EE or Web type
OpenSSO agents.

WEB

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.

You are asked to supply a
password during remote
registration. This does not appear
in the template.








Re-enter Password

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.
Extended OpenSSO Template
Only


With  set to true, you can
configure the directory path for logged
agent messages.

/scratch/debug


Default: None
See Also: Chapter 7, "Logging
Component Event Messages"


Defines the directory path for audit
logs from the OAM Server:
■

Audit Login events

■

Audit Logout success events

/scratch/audit


See Also: Chapter 8, "Auditing
Administrative and Run-time Events"


Defines the audit log file name.

audit.log


Registering and Managing Legacy OpenSSO Agents

28-23

Performing Remote Registration for OpenSSO Agents

Table 28–9 (Cont.) OpenSSO Agent Remote Registration Request
Element

Description



When set to true, the OAM Server logs false
messages for:
■

■

■

Example

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"


The name of the cookie, which the
agent finds this cookie after the
OpenSSO Proxy triggers session
validation

iPlanetDirectoryP
ro

The end user has the following valid
cookies:
■

■

OAM_ID cookie (represents the
end user session after agent
authentication)
OpenSSO cookie



If access is denied, the user is
redirected to this URL.





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.

28.5.2 Reviewing OpenSSO Bootstrap Configuration Mappings
This section describes the bootstrap configuration mappings of an OpenSSO Agent.

Table 28–10

■

Table 28–10, " J2EE Request File Mappings to the Properties File"

■

Table 28–11, " Mapping the Web Request File to the Properties File"

J2EE Request File Mappings to the Properties File

Property Name

Default Value

Sample Value

com.iplanet.am.naming.url

from input xml as
/opensso/nami
ngservice

http://example.com:7575/opensso/nami
ngservice

com.sun.identity.agents.app.username

from input xml as 



com.iplanet.am.service.secret

from input xml as




Note: This is not collected as part
of the input XML file but is
prompted for by the remote
registration tool.
com.iplanet.services.debug.directory

from input xml as


28-24 Administrator's Guide for Oracle Access Management

/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/debug

Performing Remote Registration for OpenSSO Agents

Table 28–10

(Cont.) J2EE Request File Mappings to the Properties File

Property Name

Default Value

Sample Value

com.sun.identity.agents.config.local.logfile

from input xml as
/opt/30j2ee/j2ee_agents/tomcat_v6_
/
example_com_7676.log

com.sun.identity.agents.config.organization.name from input xml as 
Note: This is the 
value collected from the input
xml file. By default it is taken as
the  unless
explicitly provided.
com.sun.identity.agents.config.profilename

from input xml as 



N/A

N/A

com.sun.identity.agents.config.service.resolver

N/A

N/A

com.sun.services.debug.mergeall

N/A

com.sun.identity.agents.config.lock.enable

FALSE
N/A

N/A

am.encryption.pwd

N/A

N/A

Not included in the remote registration file ...
com.iplanet.am.naming.url

N/A

Table 28–11 shows the mappings between a Web Agent request file and properties file.
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
//opensso/namingservice

http://example.com:7575/opensso/nami
ngservice

com.sun.identity.agents.config.username

from input xml as 



com.sun.identity.agents.config.password

from input xml as




Note: This is not collected as part
of the input XML file but is
prompted for by the remote
registration tool.
com.iplanet.services.debug.directory

from input xml as


/opt/30j2ee/j2ee_agents/tomcat_v6_
agent/Agent_001/logs/debug

com.sun.identity.agents.config.local.logfile

from input xml as
/opt/30j2ee/j2ee_agents/tomcat_v6_
/
redsky_red_iplanet_com_7676.log

com.sun.identity.agents.config.organization.name from input xml as 
Note: It is the 
value collected from the input
xml. Status: Open Fixed or Closed
com.sun.identity.agents.config.profilename

from input xml as 

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

Registering and Managing Legacy OpenSSO Agents

28-25

Performing Remote Registration for OpenSSO Agents

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

■

2.

Submit the starting request input file to the in-band Administrator using a
method you choose (email or file transfer).

In-band Administrator:

28-26 Administrator's Guide for Oracle Access Management

Updating Registered OpenSSO Agents Remotely

■

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

■

3.

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.

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

yyyy_mm_dd element to track changes

Adds

 element that specifies the agent_base_url_port

Omits



Omits



See Also:
■

Table 28–7, " Expanded OpenSSO Agent Registration Elements"

■

Updating OpenSSO Agents Remotely

Registering and Managing Legacy OpenSSO Agents

28-27

Locating Other OpenSSO Agent Information

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.
3.

Restart the OAM Server that is hosting this agent

Validating Agent:
a.

On the Agent host, run the following command in agentValidate mode. For
example:
./bin/oamreg.sh agentValidate agentname

4.

b.

Provide the registration Administrator user name and password when asked.

c.

Confirm success with on-screen messages.

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.

28-28 Administrator's Guide for Oracle Access Management

Locating Other OpenSSO Agent Information

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

Registering and Managing Legacy OpenSSO Agents

28-29

Locating Other OpenSSO Agent Information

28-30 Administrator's Guide for Oracle Access Management

29
Registering and Managing Legacy OSSO
Agents
92

[24If
] 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)

Registering and Managing Legacy OSSO Agents 29-1

Understanding OSSO Agents with Access Manager

■

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).
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.

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).
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

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.

29-2 Administrator's Guide for Oracle Access Management

Understanding OSSO Agents with Access Manager

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

■

11g OAM Agents

■

10g OAM Agents

■

10g OSSO Agents (mod_osso)

■

OpenSSO Agents

Resides with the relying parties and
delegate authentication and authorization
tasks to OAM Servers.

■

mod_osso (partner)
Note: The mod_osso module is an
Oracle HTTP Server module that
provides authentication to OracleAS
applications.

Note: Nine Administrator languages are
supported.
Servers
Notes: Administrative users access the
console home page by typing the URL:
https://host:port/oamconsole.

■
■

OAM Server

■

Oracle Access Management Console
(installed on the WebLogic
Administration Server)

OracleAS SSO server (OSSO server)

See Also: Oracle Application Server Single
Sign-On Administrator's Guide.

Non-administrative users first gain access See Also:
to the single sign-on server by entering
"Understanding the Oracle Access
the URL of an application, which returns Management Console"
the SSO login page.
"Understanding Credential Collection
and Login"
Proxy

■

Provides support for legacy systems:
■

■

OAM Proxy supports legacy Access
Manager implementations by acting
as a legacy Access Server.

■

OSSO Proxy supports legacy SSO
implementations by acting as the
legacy OSSO 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

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.

N/A

11g Webgate secures information
exchange using the Agent key.
-See Also: Cryptographic keys.
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.

An application that delegates
authentication to mod_osso and the
OracleAS Single Sign-On server.

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.

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.

Registering and Managing Legacy OSSO Agents 29-3

Understanding OSSO Agents with Access Manager

Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description

11g Access Manager

SSO Engine

Manages the session lifecycle, facilitates
global logout across all relying parties in
the valid session, and provides consistent
service across multiple protocols.

OSSO 10g
■

mod_osso delegates authentication
only and communicates exclusively
through the HTTP channel.

Uses Agents registered with Access
Manager 11g:
■

■

Cryptographic keys

■

Authentication (credential
collection) occurs across the HTTP
(HTTPS) channel
Authorization occurs across the
Oracle Access Protocol (OAP)
channel
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

■

■

■

■

■

■
■

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

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.
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

Host-based authentication cookie:

See Also: Table 21–6

■

"About Single Sign-On Cookies During
User Login"

■

■

Policies

■

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

Security Token Service

Cookies
and

■

■

10g Webgate, One ObSSOCookie for
all 10g Webgates.
One for the OAM Server: OAM_ID
(Table 21–6)

Registered agents rely on Access
Manager authentication, authorization,
and token issuance policies to determine
who gets access to protected applications
(defined resources).

29-4 Administrator's Guide for Oracle Access Management

Host-based authentication cookie:
one per partner: OHS-host-port

11g Webgate, One per agent:
OAMAuthnCookie__


one for OSSO server: (not with
Access Manager 11g)
■

Domain-level session cookie for
global inactivity timeout (GITO) if
enabled

mod_osso uses only Access Manager 11g
authentication policies to determine who
gets access to defined resources.
mod_osso provides authentication only.

Understanding OSSO Agents with Access Manager

Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description

11g Access Manager

Client IP

■

OSSO 10g

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.

Cryptography is performed at both mod_
osso and OSSO server:
1.

Webgate encrypts obrareq.cgi using
the agent key.
Note: obrareq.cgi is the
authentication request in the form of 2.
a query string redirected from
Webgate to OAM Server.

site2pstore token (request from
mod_osso to server) is encrypted
using the partner key locally at
mod_osso.
OSSO server decrypts site2pstore
token, authenticates, and generates
its own cookie.

2.

OAM Server decrypts the request,
authenticates, creates the session,
and sets the server cookie.

3.

urlc token (the response from OSSO
server to mod_osso) is encrypted
using the partner key at the server.

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.

4.

mod_osso decrypts the urlc token
locally and re-encrypts using its
own format to set in a host-based
cookie.

Note: obrar.cgi is the authentication
response string redirected from the
OAM Server to Webgate.
4.

Session Management

■

Webgate decrypts obrar.cgi, extracts
the authentication token, and sets a
host-based cookie.
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.

Registering and Managing Legacy OSSO Agents 29-5

Registering OSSO Agents Using Oracle Access Management Console

Table 29–2 (Cont.) 11g Access Manager SSO versus OSSO 10g Component Summary
Component Description

11g Access Manager

Response token replay prevention

■

Multiple network domain support

Include RequestTime (the timestamp
just before redirect) in obrareq.cgi
and copy it to obrar.cgi to prevent
response token replay.

Access Manager 11g supports
cross-network-domain single sign-on out
of the box.

OSSO 10g
■

Include RequestTime (timestamp
just before redirect) in the
site2pstore token and copy it to the
urlc token to prevent token replay.

N/A

Oracle recommends you use Oracle
Federation for this situation.
Centralized log-out

■

■

The logOutUrls (10g Webgate
configuration parameter) is
preserved. 10g logout.html requires
specific details for Access Manager
11g.

There is no change required for Access
Manager 11g with mod_osso (OSSO
Agents).

Logout Redirect URL

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.

Logout Callback URL

See Chapter 27.

11g Webgate parameters are new:

Logout Target URL
See Chapter 27.

See Also:

"Understanding Credential Collection and Login"

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.
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.

Note:

Figure 29–3 shows a Create OSSO Agent page, under the System Configuration tab in
the Oracle Access Management Console.

29-6 Administrator's Guide for Oracle Access Management

Registering OSSO Agents Using Oracle Access Management Console

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.
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:

Base URL
Required for OSSO
agents.

■

1.2

■

1.4

■

3.0

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.

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

Registering and Managing Legacy OSSO Agents 29-7

Registering OSSO Agents Using Oracle Access Management Console

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.
Table 29–4

Relocating OSSO Artifacts

From AdminServer . . .
$DOMAIN_HOME/output/$Agent_Name/

To OHS_dir/osso.conf
$WebTier_MW_HOME/Oracle_
WT1/instances1/config/OHS/ohs1/config/osso

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.
See Also: Understanding the Create OSSO Agent Registration Page
and Parameters

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:
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

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.

29-8 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OSSO Agents Using the Console

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

Registering and Managing Legacy OSSO Agents 29-9

Configuring and Managing Registered OSSO Agents Using the Console

Table 29–5 (Cont.) Expanded OSSO Agent Elements
Element

Description

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.

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:
■
■

■

■
■

6.

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.

Apply any changes (or dismiss the page) when finished.

29-10 Administrator's Guide for Oracle Access Management

Configuring and Managing Registered OSSO Agents Using the Console

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.
See Also:
■

Understanding the Expanded OSSO Agent Page in the Console

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:
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

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.
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.

Note:

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:

Searching for an OSSO Agent (mod_osso) Registration

Registering and Managing Legacy OSSO Agents

29-11

Performing Remote Registration for OSSO Agents

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–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:

$OAM_REG_HOME/input/CreatePolicyRequest.xml

Create New Host Identifiers and
an Application Domain without
Registering an Agent

See Also: "Managing Policies and Application Domains Remotely" on
page 25-82

Update Policies:

$OAM_REG_HOME/input/UpdatePolicyRequest.xml

Existing Host Identifiers and
Application Domain (not
associated with an Agent
Registration)

See Also: "Managing Policies and Application Domains Remotely" on
page 25-82

Table 29–7 describes elements in the OSSO request file: OSSORequest.xml.

29-12 Administrator's Guide for Oracle Access Management

Performing Remote Registration for OSSO Agents

Table 29–7

OSSO-Specific Elements in a Remote Registration Request

Elements

Description

Example



Elements common to all remote registration request
templates.

See Table 15–8, " Common Elements in
Remote Registration Requests"

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.



The absolute file system directory path to the mod_osso
agent.


$ORACLE_HOME




Default: None specified



Optional.





Administrator details for this mod_osso instance. For
example, Application Administrator.
Default: None specified


Optional.



Administrator log in ID for this mod_osso instance. For
example, SiteAdmin.
Default: None specified


Include the Logout URLs for consumption during
remote registration.

logout1.html

Default: None specified


Include the Failure URLs for consumption during remote failure1.html
registration.
Default: None specified

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.

Registering and Managing Legacy OSSO Agents

29-13

Performing Remote Registration for OSSO Agents

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

29-14 Administrator's Guide for Oracle Access Management

Updating Registered OSSO Agents Remotely

■

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

■

2.

Submit the starting request input file to the in-band Administrator using a
method you choose (email or file transfer).

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

■

3.

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.

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

yyyy_mm_dd element to track changes
 element that specifies the agent_base_url_port

Omits



Omits



Registering and Managing Legacy OSSO Agents

29-15

Configuring Logout for OSSO Agents with Access Manager 11.1.2

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.
3.

Restart the OAM Server that is hosting this agent

Validating Agent:
a.

On the Agent host, run the following command in agentValidate mode. For
example:
./bin/oamreg.sh agentValidate agentname

4.

b.

Provide the registration Administrator user name and password when asked.

c.

Confirm success with on-screen messages.

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

29-16 Administrator's Guide for Oracle Access Management

Configuring Logout for OSSO Agents with Access Manager 11.1.2

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.
No change is needed in the logout URL configuration of
existing applications that use the OSSO Agent.

Note:

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=...):

COOKIE_NAME


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.

Registering and Managing Legacy OSSO Agents

29-17

Locating Other OSSO Agent Information

Caution: Work carefully. In general, Oracle recommends that you do
not edit the oam-config.xml file. This, however, is a rare exception.

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:



ORASSO_AUTH_HINT




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:

11.1.1.3
25


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.
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"

29-18 Administrator's Guide for Oracle Access Management

30
Registering and Managing 10g WebGates with
Access Manager 11g
03

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-certification100350.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

Registering and Managing 10g WebGates with Access Manager 11g 30-1

Introduction to 10g OAM Agents for Access Manager 11g

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.
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"

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

30-2 Administrator's Guide for Oracle Access Management

Introduction to 10g OAM Agents for Access Manager 11g

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.
See Also:
■
■

Table 1–2
Appendix A, "Integrating Oracle ADF Applications with Access
Manager SSO"

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.
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.

Note:

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.

Registering and Managing 10g WebGates with Access Manager 11g 30-3

Introduction to 10g OAM Agents for Access Manager 11g

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 1.
media and virtual media that is separate from the core
components.

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.

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.

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.

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.

30-4 Administrator's Guide for Oracle Access Management

Comparing Access Manager 11.1.2 and 10g

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."
See Also: Section 30.4, "Configuring Centralized Logout for
IAMSuiteAgent"

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."

Registering and Managing 10g WebGates with Access Manager 11g 30-5

Comparing Access Manager 11.1.2 and 10g

Table 30–2

Comparison: Access Manager 11g versus 10g
Access Manager 11g

Agents

■

Agents: WebGate, Access Client, OpenSSO,
OSSO (mod_osso), IAMSuiteAgent

Note: Nine Administrator languages are supported.

10g
■

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

Console

Oracle Access Management Console

■

Access Server

■

Policy Manager

■

Identity Server

Access System Console
Identity System Console

Protocols that
secure
information
exchange on the
Internet
Cryptographic
keys

Front channel protocols exchanged between Agent
and Server: HTTP/HTTPS.

10g Agent information exchange is unsecured, in
plain text.

11g WebGate secures information exchange using the
Agent key.
-See Also: Cryptographic keys.
■

■

One per-agent secret key shared between 11g
WebGate and OAM Server

One global shared secret key per Access Manager
deployment which is used by all the 10g WebGates

One OAM Server key, generated during Server
registration

Note: One key is generated and used per registered
mod_osso agent.
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

Cookies

Host-based authentication cookie, described in
Table 1–2, " Features in Access Manager 11.1.2"

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.

Global shared secret stored in the directory server
only (not accessible to WebGate)

WebGate decrypts obrar.cgi, extracts the
authentication token, and sets a host-based
cookie.

30-6 Administrator's Guide for Oracle Access Management

■

■

■

One domain-based ObSSOCookie for all
WebGates (including the AWG), for both
authentication and session management
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

Table 30–2 (Cont.) Comparison: Access Manager 11g versus 10g
Access Manager 11g
Session
Management

Client IP

■

■

10g

Chapter 16, "Maintaining Access Manager
Sessions"

Maintain this Client IP, and include it in the
host- based OAMAuthnCookie.

■

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.

■

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.

Multiple network Cross-network-domain single sign-on out of the box.
domain support Oracle recommends you use Oracle Federation for
multiple network domain support.

N/A

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.

■

Centralized
log-out

■

■

Multi-domain SSO can be supported through
chained customized logout pages.

logout.html requires specific details when using a 10g
The logOutUrls (10g WebGate configuration
WebGate with Access Manager 11g. See Chapter 27,
parameter) is preserved. 10g logout.html
requires specific details for Access Manager 11g. "Configuring Centralized Logout for Sessions
Involving 11g WebGates."
11g WebGate parameters are new:
■

Logout Redirect URL

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.

Logout Callback URL
Logout Target URL
See Chapter 27, "Configuring Centralized Logout for
Sessions Involving 11g WebGates."

Single domain is supported.

■

Multi-domain SSO can be supported through
chained customized logout pages.

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.

Registering and Managing 10g WebGates with Access Manager 11g 30-7

Comparing Access Manager 11.1.2 and 10g

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.
2.

Host identifiers

Authentication
Policies

No URL prefixes. Resource definitions are
treated as complete URLs.

1.

URL prefixes are defined in domains

2.

Pattern matching for:

Pattern matching (with limited features) for:

{ } * …

' * ' and '...' are supported

3.

Resources need not be unique across domains.

3.

Resources need not be unique across domains.

4.

4.

Query-string protection for HTTP URLs.

http resources can be protected based on URL
query string contents and/or HTTP operation.

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).

5.

Non-HTTP resource types and operations can
be defined.

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.

Host Identifiers are defined outside of policies 1.
and are used while defining HTTP resources.

Host Identifiers are defined outside of policies
and are used while defining HTTP resources.

2.

Host Identifiers are mandatory for defining
HTTP resources.

2.

Host Identifiers are not mandatory, for
defining HTTP resources, till there are no Host
Identifiers defined in the system.

1.

Authentication policies include resources,
success responses, and an authentication
scheme.

1.

Authentication policies are simple and contain
only authentication-scheme-based rule.

2.

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.

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.

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.".

30-8 Administrator's Guide for Oracle Access Management

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

Table 30–3 (Cont.) Comparing Access Manager 11g Policy Model versus 10g
Policy Elements

11g Policy Model

10g Policy Model

Authentication
Schemes

Authentication Schemes are defined globally and
can be shared (referenced within authentication
policies).

Authentication Schemes can be defined outside of
policies and can be 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".
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.".

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.

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.

N/A

See Also: Section 25.3.6, "Displaying Token
Issuance Policy Pages.".
Responses

Cookies

Available for all policy types:

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.

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
4.
derive values from request, user, and session
attributes.

Response values can contain literal strings
and list of user attribute values.

See Also: Table 21–6

See Also: Table 21–6

and

and

Section 21.5.1, "About Single Sign-On Cookies
During User Login."

Section 21.5.1, "About Single Sign-On Cookies
During User Login."

Registering and Managing 10g WebGates with Access Manager 11g 30-9

Configuring Centralized Logout for IAMSuiteAgent

Table 30–3 (Cont.) Comparing Access Manager 11g Policy Model versus 10g
Policy Elements

11g Policy Model

10g Policy Model

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.

Rule

Available for only Authorization and Token
Issuance 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.

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.

A policy is defined using authorization rules
(among other policy elements). Authorization
rules:
■

■

See Also: Section 25.9, "Introduction to
Authorization Policy Rules and Conditions.".

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.

N/A

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."

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:

30-10 Administrator's Guide for Oracle Access Management

Registering a 10g WebGate with Access Manager 11g Remotely

■

■

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.
See Also:
■

The following, if needed:

Section 15.7, "Performing Remote Registration for OAM Agents"

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:

http://ruby.uk.example.com:7001
my-10g
my-10g-agent1

/myapp/
/myapp/.../*

Registering and Managing 10g WebGates with Access Manager 11g

30-11

Registering a 10g WebGate with Access Manager 11g Remotely



/public/index.html


/excluded/index.html

true
.uk.example.com

/oamsso/logout.html



See Also: Section 15.7.2, "Creating Your Remote Registration
Request"
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

30-12 Administrator's Guide for Oracle Access Management

Managing 10g OAM Agents Remotely

6.

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).

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.
3.

Restart the server that is hosting this agent.

Validating Agent:
a.

On the Agent host, run the following command in agentValidate mode. For
example:
./bin/oamreg.sh agentValidate agentname

4.

b.

Provide the registration Administrator user name and password when asked.

c.

Confirm success with on-screen messages.

Deleting an Agent:

Registering and Managing 10g WebGates with Access Manager 11g

30-13

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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:
■
■

User Accounts

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

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

30-14 Administrator's Guide for Oracle Access Management

Locating and Installing the Latest 10g WebGate for Access Manager 11g

Table 30–4 (Cont.) Preparing for 10g WebGate Installation with Access Manager 11g
About the ...
Root Level versus
Site Level

Description
■

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.

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:

Apache Web
Servers

See Also Appendix C, "Securing Communication."

■

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)

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 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.
(IHS) v2 Web
Servers:
For details, see Chapter 31, "Configuring Apache, OHS, IHS for 10g WebGates."

Registering and Managing 10g WebGates with Access Manager 11g

30-15

Locating and Installing the Latest 10g WebGate for Access Manager 11g

Table 30–4 (Cont.) Preparing for 10g WebGate Installation with Access Manager 11g
About the ...

Description

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"

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

30-16 Administrator's Guide for Oracle Access Management

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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.
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.

Note:

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.

Registering and Managing 10g WebGates with Access Manager 11g

30-17

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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.
See Also:

Appendix C, "Securing Communication"

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.
See Also:

Appendix C, "Securing Communication"

To request or install certificates for WebGate 10g
Indicate whether you are requesting or installing a certificate, then click Next and
continue. For example:

1.

2.

■

Requesting a certificate, proceed with step 2.

■

Installing a certificate, skip to step 3.

Request a Certificate:
■

■
■

3.

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."

Install a Certificate During Installation: Specify the full paths to the following
files, then click Next:

30-18 Administrator's Guide for Oracle Access Management

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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.
■
■

■

■

■

2.

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.

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."

Registering and Managing 10g WebGates with Access Manager 11g

30-19

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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.
If the manual configuration process was launched during
WebGate installation, you can skip Step 1 in the following procedure.

Note:

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.
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
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.

30-20 Administrator's Guide for Oracle Access Management

Locating and Installing the Latest 10g WebGate for Access Manager 11g

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:

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.
Note: If you are installing a 64-bit IIS WebGate, see Section 33.8,
"Finishing 64-bit Webgate Installation."

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.
■

■

4.

Security-Enhanced Linux: Run the chcon commands for the WebGate you just
installed on this platform.

Proceed with following topics before installing artifacts and certificates:
■

■

■

■
■

5.

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.

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."

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.

Registering and Managing 10g WebGates with Access Manager 11g

30-21

Configuring Centralized Logout for 10g WebGate with 11g OAM Servers

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

2.

■

From: $WLS_DOMAIN_HOME/output/AGENT_NAME

■

To: $WebGate_install_dir/oblix/config

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

30-22 Administrator's Guide for Oracle Access Management

Configuring Centralized Logout for 10g WebGate with 11g OAM Servers

■

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.
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").

Note:

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.

Registering and Managing 10g WebGates with Access Manager 11g

30-23

Configuring Centralized Logout for 10g WebGate with 11g OAM Servers

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.
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."

Note:

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









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.

Registering and Managing 10g WebGates with Access Manager 11g

30-25

Configuring Centralized Logout for 10g WebGate with 11g OAM Servers

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."

Note:

//adfAuthentication?logout=true&end_url=

Table 30–5 illustrates how a logout link in the logout.html file might be specified:
Table 30–5

Sample end_url Parameter Specifications

As a ...

Sample end_url Value

URI

/oamsso/logout.html?end_url=
For example:
/oamsso/logout.html?end_url=/welcome.html

URL

/oamsso/logout.html?end_url=
For example:
/oamsso/logout.html?end_url=http://my.site.com/welcome.html

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.
Optional tasks or those required for only multiple DNS
domain logout are identified and can be skipped unless needed.

Note:

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

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.

Note:

c.
2.

Proceed with following steps, as needed.

Ensure that the logout.html (from Step 1) redirects the user to this central logout
URI, "/oam/server/logout' on the 11g OAM Server.

30-26 Administrator's Guide for Oracle Access Management

Removing a 10g WebGate from the Access Manager 11g Deployment

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:

Satisfy any


■

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.
Deleting an agent registration does not remove the associated
host identifier, Application Domain, resources, or the agent instance.

Note:

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.
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.

Note:

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

Registering and Managing 10g WebGates with Access Manager 11g

30-27

Removing a 10g WebGate from the Access Manager 11g Deployment

\uninstaller.exe
■
■

■
■

4.

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)).

Perform the following steps to remove 10g WebGate configuration data:
■

■

5.

Run the Language Pack Uninstaller program to remove the files.

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.

Locate and run the Uninstaller program for the specific component to remove
Access Manager files. For example:
WebGate_install_dir\access\_uninstWebGate\uninstaller.exe
Note:

6.

On UNIX systems, use uninstaller.bin

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.

30-28 Administrator's Guide for Oracle Access Management

31
Configuring Apache, OHS, IHS for 10g
WebGates
31

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:
Configuring Apache, OHS, IHS for 10g WebGates 31-1

About Access Manager with Apache and IHS v2 Webgates

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.
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

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
31-2 Administrator's Guide for Oracle Access Management

About Access Manager with Apache and IHS v2 Webgates

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

Configuring Apache, OHS, IHS for 10g WebGates 31-3

About Apache v2 Architecture and Access Manager

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.
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:

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.
Unless explicitly stated otherwise, all details in this
discussion apply equally to Apache v2 and IHS v2 Web Servers for
10g Webgates.

Important:

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.
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.

Note:

■

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.

31-4 Administrator's Guide for Oracle Access Management

Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers

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.
Webgates for Apache v2 (and derivatives) can be used in
installations that contain Webgates for other Web servers.

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.

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:



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

Configuring Apache, OHS, IHS for 10g WebGates 31-5

Requirements for Oracle HTTP Server, IHS, Apache v2 Web Servers

■

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.
31-6 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

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.
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.

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.
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.

Note:

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

Configuring Apache, OHS, IHS for 10g WebGates 31-7

Preparing Your Web Server

■

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
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.

Note:

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:

31-8 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

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/

Configuring Apache, OHS, IHS for 10g WebGates 31-9

Preparing Your Web Server

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

31-10 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

■

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

Note: The start and stop instructions for an SSL implementation are
the same as non-SSL-capable implementations.
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.
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.

Note:

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.

Configuring Apache, OHS, IHS for 10g WebGates

31-11

Preparing Your Web Server

With Oracle HTTP Server 11g, there is no need to comment out
any module for Webgates on any platform.

Note:

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.
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.

Note:

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

31-12 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

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

There are no known restrictions with regard to supported
compiler versions for Apache v2 and Access Manager plug-ins. See
the Apache documentation.

Note:

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

Note:
3.

Be sure to download Perl, if needed.

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.

Configuring Apache, OHS, IHS for 10g WebGates

31-13

Preparing Your Web Server

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:

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

To view the complete list of values, use the command:
./configure --help.

Note:

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
31-14 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

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:

Configuring Apache, OHS, IHS for 10g WebGates

31-15

Preparing Your Web Server

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

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

31-16 Administrator's Guide for Oracle Access Management

Preparing Your Web Server

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.
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.

Note:

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

Configuring Apache, OHS, IHS for 10g WebGates

31-17

Preparing Your Web Server

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.
Pressing Control-C may not allow Apache to end any current
operations and clean up gracefully.

Note:

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.

31-18 Administrator's Guide for Oracle Access Management

Activating Reverse Proxy for Apache v2 and IHS v2

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 
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.
Configuring Apache, OHS, IHS for 10g WebGates

31-19

Activating Reverse Proxy for Apache v2 and IHS v2

3.

Use the ProxyPass directive or the [P] flag to the RewriteRule directive to activate
a reverse proxy, as follows:
Reverse Proxy
ProxyRequests Off

Order deny,allow
Allow from all

ProxyPass /foo http://foo.example.com/bar
ProxyPassReverse /foo http://foo.example.com/bar

4.

Control access to your proxy using the  control block as follows:

Order Deny,Allow
Deny from all
Allow from 192.168.0


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
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule
LoadModule

access_module modules/mod_access.so
auth_module modules/mod_auth.so
auth_dbm_module modules/mod_auth_dbm.so
include_module modules/mod_include.so
log_config_module modules/mod_log_config.so
env_module modules/mod_env.so
unique_id_module modules/mod_unique_id.so
setenvif_module modules/mod_setenvif.so
proxy_module modules/mod_proxy.so
proxy_connect_module modules/mod_proxy_connect.so
proxy_ftp_module modules/mod_proxy_ftp.so
proxy_http_module modules/mod_proxy_http.so
mime_module modules/mod_mime.so
dav_module modules/mod_dav.so
autoindex_module modules/mod_autoindex.so
asis_module modules/mod_asis.so
info_module modules/mod_info.so
cgid_module modules/mod_cgid.so
dav_fs_module modules/mod_dav_fs.so
vhost_alias_module modules/mod_vhost_alias.so
dir_module modules/mod_dir.so
imap_module modules/mod_imap.so
actions_module modules/mod_actions.so

31-20 Administrator's Guide for Oracle Access Management

Activating Reverse Proxy for Apache v2 and IHS v2

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:

Order deny, allow
#
Deny from all
Allow from all
#
Allow from .domain.com


■

URLs to be protected are mentioned in both the ProxyPass and the
ProxyPassReverse directives.
For example:

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.

Testing: To access the proxy URL, access http://:80/testproxy/
Note:

While testing, make sure the URLs have a trailing forward slash.
Sometimes resources cannot be accessed without the forward slash at
the end.
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.

Configuring Apache, OHS, IHS for 10g WebGates

31-21

Verifying httpd.conf Updates for Webgates

You can switch back to open mode for the Web server simply
by commenting out the preceding directives and restarting the server.

Note:

11. key.kdb: To generate the key.kdb, use the ikeyman utility (preferably in GUI

mode) provided in the IHS_install_dir/bin directory.
The ikeyman utility uses the gsk7bas utility. However, you
need to apply fix pack PQ83048 on gsk7bas.

Note:

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 ****

LoadModule obWebgateModule "WebGate_install_
dir\access\oblix\apps\webgate\bin\webgatessl.d ll"
WebGateInstalldir "WebGate_install_dir"
WebGateMode PEER


LoadModule obWebgateModule "WebGate_install_
dir\access\oblix\apps\webgate\bin\webgate.dll"

31-22 Administrator's Guide for Oracle Access Management

Verifying httpd.conf Updates for Webgates

WebGateInstalldir "WebGate_install_dir"
WebGateMode PEER


SetHandler obwebgateerr


AuthType Oblix
require valid-user

#*** 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"

LoadModule obWebgateModule "/home/qa/netpoint/703/c1-copy/wg/access/oblix/
apps/webgate/bin/webgatessl.so"


LoadModule obWebgateModule "/home/qa/netpoint/703/c1-copy/wg/access/oblix/
apps/webgate/bin/webgate.so"

WebGateInstalldir "/home/qa/netpoint/703/c1-copy/wg/access"
WebGateMode PEER

SetHandler obwebgateerr


SetHandler obwebgateerr


AuthType Oblix
require valid-user

#*** 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

SetHandler obwebgateerr


Configuring Apache, OHS, IHS for 10g WebGates

31-23

Verifying httpd.conf Updates for Webgates


AuthType Oblix
require valid-user

#*** 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.
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.

Important:

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.
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.

Note:

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.

31-24 Administrator's Guide for Oracle Access Management

Tuning OHS /Apache Prefork and Worker MPM Modules for OAM

3.

4.

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.

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.
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.

Note:

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:















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.

Configuring Apache, OHS, IHS for 10g WebGates

31-25

Tuning OHS /Apache Prefork and Worker MPM Modules for OAM

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

31-26 Administrator's Guide for Oracle Access Management

Tuning Apache/IHS v2 Webgates for Access Manager

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).

Configuring Apache, OHS, IHS for 10g WebGates

31-27

Tuning Apache/IHS v2 Webgates for Access Manager

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.
See Also:

"SELinux Issues" on page E-25

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

When the Webgate is installed in a separate directory from the
Access Manager, be sure to register the Webgate installation directory
separately.

Note:

5.

Compile and deploy the policy files as follows:
cd $SELINUX_SRC
make load
Label Oracle Access Manager files

31-28 Administrator's Guide for Oracle Access Management

Tuning Apache/IHS v2 Webgates for Access Manager

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.
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.

Note:

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.

Configuring Apache, OHS, IHS for 10g WebGates

31-29

Removing Web Server Configuration Changes After Uninstall

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

31-30 Administrator's Guide for Oracle Access Management

32
Configuring the ISA Server for 10g WebGates
32

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.
Access Manager Client Certificate authentication is not
supported for the ISA Server.

Note:

Configuring the ISA Server for 10g WebGates 32-1

Compatibility and Platform Support

See Also: Oracle Fusion Middleware Administrator's Guide for
Oracle Access Management for more information about authentication
management and policy domains.

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.
See Also:

"Compatibility and Platform Support" on page 32-2

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

32-2 Administrator's Guide for Oracle Access Management

Configuring the ISA Server for the ISAPI Webgate

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.
During Webgate installation, do not automatically update the
ISA Server configuration. Instead, choose "No" when asked about
automatic updates to the ISA Server configuration.

Note:

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:

2.

■

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

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
Configuring the ISA Server for 10g WebGates 32-3

Configuring the ISA Server for the ISAPI Webgate

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.
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:

Note:

action= "/access/dummy"
For form based authentication, postgate.dll must be installed and
should be at a higher level than webgate.dll.
The following procedure describes how to register Access Manager plug-ins in the ISA
Server.
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
Note:

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.
See Also: Your ISA Server documentation for details about ISA
Firewall Policies and rules

32-4 Administrator's Guide for Oracle Access Management

Configuring the ISA Server for the ISAPI Webgate

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.
After you perform the following procedure, when you create a
listener in the authentication click Allow client authentication over
HTTP in Advanced Properties.

Note:

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.
If you are using secured connections, see the server connection
security settings provided by ISA Server.

Note:

8.

9.

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.

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.

Configuring the ISA Server for 10g WebGates 32-5

Configuring the ISA Server for the ISAPI Webgate

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.

32-6 Administrator's Guide for Oracle Access Management

Removing Access Manager Filters Before Webgate Uninstall on ISA Server

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.

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.
See Also:

Chapter 30 for details about uninstalling 10g Webgates

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

Configuring the ISA Server for 10g WebGates 32-7

Removing Access Manager Filters Before Webgate Uninstall on ISA Server

32-8 Administrator's Guide for Oracle Access Management

33
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

Configuring the IIS Web Server for 10g WebGates 33-1

WebGate Guidelines for IIS Web Servers

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.
Note: Unless explicitly stated, details apply equally to 32-bit and
64-bit Webgates.

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.

33-2 Administrator's Guide for Oracle Access Management

WebGate Guidelines for IIS Web Servers

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.

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.
See Also:
■

Webgates for IIS v7 on page 33-4

■

Webgates for IIS v6 on page 33-4

32-bit versus 64-bit Webgates: Unless explicitly stated, all information applies equally
to both 32-bit and 64-bit Webgates.
See Also:
■

Webgates for IIS v6 on page 33-4

■

Finishing 64-bit Webgate Installation on page 33-24

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:
See Also:
■

Completing Webgate Installation with IIS

■

Finishing 64-bit Webgate Installation

■

Confirming Webgate Installation on IIS

Configuring the IIS Web Server for 10g WebGates 33-3

WebGate Guidelines for IIS Web Servers

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.
See Also:

Multiple Webgates with a Single IIS 6 Instance

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.
You can install Webgate 10g (10.1.4.3) for IIS in any location,
separate from that of Policy Manager.

Note:

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.
33-4 Administrator's Guide for Oracle Access Management

Prerequisite for Installing Webgate for IIS 7

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:

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
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.

Note:

You can install multiple Webgates on different Web sites of the same IIS Web server
instance. However, several manual steps are required.
See Also: "Installing and Configuring Multiple Webgates for a
Single IIS 6 Instance" on page 33-19

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  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  entry is not present in
Configuring the IIS Web Server for 10g WebGates 33-5

Updating IIS 7 Web Server Configuration on Windows 2008

the applicationHost.config file. If the entry is present, you must remove it, as described
next
To locate and remove the  entry
1. Go to Windows\System32\inetsrv\config and open the applicationHost.config
file.
2.

Search for the  module.

3.

Remove the entry  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

...

...

33-6 Administrator's Guide for Oracle Access Management

Completing Webgate Installation with IIS

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.
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

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.
The procedures here reflect the sequence for IIS v5. Your
environment might be different.

Note:

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.
Configuring the IIS Web Server for 10g WebGates 33-7

Completing Webgate Installation with IIS

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.
This task is the same whether you are installing one or more
Webgates per IIS Web server instance.

Note:

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:

33-8 Administrator's Guide for Oracle Access Management

Completing Webgate Installation with IIS

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.
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.

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.
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:

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.
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.

Note:

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

Configuring the IIS Web Server for 10g WebGates 33-9

Completing Webgate Installation with IIS

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.
See Also:

"IIS Web Server Issues" on page E-18

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
Value: 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".

33-10 Administrator's Guide for Oracle Access Management

Completing Webgate Installation with IIS

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.
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:

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.
Skip this task if you are using IIS 6.0 Web server in Worker
Process Isolation Mode.

Note:

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.

Configuring the IIS Web Server for 10g WebGates

33-11

Completing Webgate Installation with IIS

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.
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:

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
postgate.dll is not supported when you have more than one
Webgate installed and configured for a single IIS Web server instance.

Note:

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:

33-12 Administrator's Guide for Oracle Access Management

Completing Webgate Installation with IIS

\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.
Note: Consider using net stop iisadmin and net start w3svc to
help ensure that the Metabase does not become corrupted.

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.
See Also: "Setting Access Permissions, ISAPI filters, and Directory
Security Authentication" on page 33-25

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.

Configuring the IIS Web Server for 10g WebGates

33-13

Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance

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
See Also:

"Confirming Multiple Webgate Installation" on page 33-24

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.

33-14 Administrator's Guide for Oracle Access Management

Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance

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.
4.

5.

6.

7.

Save and apply these changes.

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.

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".

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".

Ensure that there is no webgate.dll in the top level (the hostname level).
Configuring the IIS Web Server for 10g WebGates

33-15

Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance

8.

9.

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

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.
This task must be performed for each Webgate that protects an
individual Web site for a single IIS Web server instance.

Note:

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:

33-16 Administrator's Guide for Oracle Access Management

Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance

■

■

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.
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.

Note:

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.

Configuring the IIS Web Server for 10g WebGates

33-17

Installing and Configuring Multiple 10g WebGates for a Single IIS 7 Instance

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.
"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.

Note:

■

Click the Web Site name.

■

In the Action pane, click Basic Settings.

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

33-18 Administrator's Guide for Oracle Access Management

Installing and Configuring Multiple Webgates for a Single IIS 6 Instance

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.
9.

Save the profile.

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.
See Also: "Installing and Configuring Multiple 10g WebGates for a
Single IIS 7 Instance" on page 33-14

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.

Configuring the IIS Web Server for 10g WebGates

33-19

Installing and Configuring Multiple Webgates for a Single IIS 6 Instance

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
See Also:

"Confirming Multiple Webgate Installation" on page 33-24

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.
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.

Note:

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.

33-20 Administrator's Guide for Oracle Access Management

Installing and Configuring Multiple Webgates for a Single IIS 6 Instance

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

3.

4.

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.

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.

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.

5.

6.

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".

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".

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

Configuring the IIS Web Server for 10g WebGates

33-21

Installing and Configuring Multiple Webgates for a Single IIS 6 Instance

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:

9.

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

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.
This task must be performed for each Webgate that protects an
individual Web site for a single IIS Web server instance.

Note:

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:

33-22 Administrator's Guide for Oracle Access Management

Installing and Configuring Multiple Webgates for a Single IIS 6 Instance

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.
Procedures in this topic apply equally to 32-bit and 64-bit
Webgates, and IIS 6, unless stated otherwise.

Note:

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".
Configuring the IIS Web Server for 10g WebGates

33-23

Finishing 64-bit Webgate Installation

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.
See Also:
■

"Finishing 64-bit Webgate Installation" on page 33-24

■

"Confirming Webgate Installation on IIS" on page 33-26

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:

33-24 Administrator's Guide for Oracle Access Management

Finishing 64-bit Webgate Installation

■

■

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.

Configuring the IIS Web Server for 10g WebGates

33-25

Confirming Webgate Installation on IIS

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.
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.

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.

33-26 Administrator's Guide for Oracle Access Management

Removing Web Server Configuration Changes Before Uninstall

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.

Configuring the IIS Web Server for 10g WebGates

33-27

Removing Web Server Configuration Changes Before Uninstall

33-28 Administrator's Guide for Oracle Access Management

34
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
The information here presumes that you are familiar with your
operating system commands, Lotus Notes, and the Domino Web
server.

Note:

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.
You need to register if this is the first time you download from
lotus.com.

Note:

To download the Domino Web server on UNIX
1.

Download Lotus Domino from the following URL:

Configuring Lotus Domino Web Servers for 10g WebGates 34-1

Setting Up the First Domino Web Server

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.
Be sure to put Domino data directory in your $PATH before
you proceed from here.

Note:

34.3 Setting Up the First Domino Web Server
After successfully installing, you must set up the first Domino server.

34-2 Administrator's Guide for Oracle Access Management

Enabling SSL (Optional)

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.

■

5.

Keep passwords simple, and record them in a safe location. For example,
oracleoracle.

Run all commands as the UNIX user that you've configured for this Domino Web
server.
WARNING:

Do not run as root.

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.

Configuring Lotus Domino Web Servers for 10g WebGates 34-3

Installing a Domino Security (DSAPI) Filter

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.

34-4 Administrator's Guide for Oracle Access Management

Installing a Domino Security (DSAPI) Filter

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.
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.

Note:

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.

Configuring Lotus Domino Web Servers for 10g WebGates 34-5

Installing a Domino Security (DSAPI) Filter

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.

34-6 Administrator's Guide for Oracle Access Management

Part VIII
Managing the Adaptive Authentication
Service and Oracle Mobile Authenticator

Part VIII

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
53

[25The
]
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.
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.

Note:

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.

Introducing the Adaptive Authentication Service

35-1

Working with the Adaptive Authentication Service

■

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.)

35-2 Administrator's Guide for Oracle Access Management

Working with the Adaptive Authentication Service

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."

Note:

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.

Introducing the Adaptive Authentication Service

35-3

Working with the Adaptive Authentication Service

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 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.
The OMA mobile app is not used for the OTP through Email
or OTP through SMS options.

Note:

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.
The OMA refreshes the OTP every 30 seconds so the OTP
entered by a user is valid only for that period of time.

Note:

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
35-4 Administrator's Guide for Oracle Access Management

Working with the Adaptive Authentication Service

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.
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.

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.

Introducing the Adaptive Authentication Service

35-5

Understanding Adaptive Authentication Service and OMA Configurations

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."
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.

Note:

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

35-6 Administrator's Guide for Oracle Access Management

Configuring the Adaptive Authentication Service

■

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://:/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.

Introducing the Adaptive Authentication Service

35-7

Configuring the Adaptive Authentication Service

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 Name of the user attribute
e
in which the secret key is
stored.

Attribute
description

OTP using OMA,
Time based OTP

TotpTimeWindow

3

OTP using OMA,
Time based OTP

false

Access Request
Notifications (iOS)

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.

PushAPNsProdServer If set to true, the APNS
production server will be
used to send notifications.
PushProxyHost

Name of the proxy host if
notifications are to sent to
the server using a proxy.

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
false
Authentication Service
requires UMS to send Email
and SMS, set to true.

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

35-8 Administrator's Guide for Oracle Access Management

Access Request
Notifications

Configuring the Adaptive Authentication Service

Table 35–1 (Cont.) Adaptive Authentication Plugin Properties
Property

Description

Default Value

Totp_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

Email_Enabled
Sms_Enabled
Push_Enabled

Required for
Challenge Method

NOTE: Properties
should be set to
false only when the
Administrator
wants to disable a
particular feature
for all users.

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.
Table 35–2

Server Side Configuration for Adaptive Authentication Service

Configuration

Information

Challenge Method

iOS
Certificate/Password

https://developer.apple.com/libr Access Request (Push)
ary/mac/documentation/Networking notification using iOS
Internet/Conceptual/RemoteNotifi
cationsPG/Chapters/ApplePushServ
ice.html

API Key

https://developers.google.com/we Access Request (Push)
b/updates/2015/03/push-notificat notification using Android
ons-on-the-open-web?hl=en

UMS Credential

UMS credentials that OAM will use
to establish the connection to UMS
Web service.

Email/SMS

1.

cd /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.

Introducing the Adaptive Authentication Service

35-9

Configuring the Adaptive Authentication Service

6.

Run one or more of the following commands to set credentials for the UMS server,
iOS or Android depending on your deployment.
Replace , ,  and  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 OTP for email/SMS only:
createCred(map="OAM_CONFIG", key="umsKey", user="",
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="")

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="")

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.
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.

Note:

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 /config/fmwconfig directory of the
Oracle Access Management installation.

35-10 Administrator's Guide for Oracle Access Management

Configuring the Adaptive Authentication Service

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.
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
Note:

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.

Introducing the Adaptive Authentication Service

35-11

Configuring the Adaptive Authentication Service

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.

35-12 Administrator's Guide for Oracle Access Management

36
Configuring the Oracle Mobile Authenticator
36

[26The
]
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.
Note: For details on the secret key, see Section 35.4.1, "Generating a
Secret Key for the Oracle Mobile Authenticator."

■

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::=
&ServiceType::=SharedSecret/Notification/Both&
SharedSecretAuthServerType::=HTTPBasicAuthentication/OAuthAuthentication
&LoginURL::=http://:/secretKeyURL
&NotificationAuthServerType::= HTTPBasicAuthentication

Configuring the Oracle Mobile Authenticator 36-1

Understanding Oracle Mobile Authenticator Configuration

&PushPreferencesEndpoint::=http://:/preferencesURL
&ChallengeAnswerEndpoint::=http://:/challengeAnswerURL
&SenderID::=
&OAuthClientID::=
&OAMOAuthServiceEndpoint::=http://:/oauthserviceURL
&OAuthScope::=

Table 36–1 documents definitions for the location URL parameters.
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.

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."
Note:

■

Oracle recommends using online configuration.

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

36-2 Administrator's Guide for Oracle Access Management

Using the Oracle Mobile Authenticator App on iOS

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::=
&AccountName::=&SharedSecretEncoding::=Base32/Base64String
&OTPAlgorithm::=TOTP
&HashingAlgorithm::=MD5/SHA-1/SHA-224/SHA-256/SHA-384/SHA-512
&OTPLength::=&TimeStep::=

Table 36–2 contains details regarding the parameters.
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

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

Configuring the Oracle Mobile Authenticator 36-3

Using the Oracle Mobile Authenticator App on iOS

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.

36-4 Administrator's Guide for Oracle Access Management

Using the Oracle Mobile Authenticator App on iOS

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

Configuring the Oracle Mobile Authenticator 36-5

Using the Oracle Mobile Authenticator App on iOS

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.

36-6 Administrator's Guide for Oracle Access Management

Using the Oracle Mobile Authenticator App on Android

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

Configuring the Oracle Mobile Authenticator 36-7

Using the Oracle Mobile Authenticator App on Android

■

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.

36-8 Administrator's Guide for Oracle Access Management

Using the Oracle Mobile Authenticator App on Android

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.
Configuring the Oracle Mobile Authenticator 36-9

Using the Oracle Mobile Authenticator App on Android

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.

36-10 Administrator's Guide for Oracle Access Management

Using the Oracle Mobile Authenticator App on Android

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 Oracle Mobile Authenticator

36-11

Configuring the Google Authenticator App

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.

36-12 Administrator's Guide for Oracle Access Management

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

[27A
]
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.
Introducing Identity Federation in Oracle Access Management 37-1

Deploying Identity Federation with Oracle Access Management

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:

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.
Note:

Calls are routine HTTP calls.

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

37-2 Administrator's Guide for Oracle Access Management

Using Identity Federation

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.
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.

Note:

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

Introducing Identity Federation in Oracle Access Management 37-3

Using Identity Federation

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.
37-4 Administrator's Guide for Oracle Access Management

Initiating Federation SSO

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)

Introducing Identity Federation in Oracle Access Management 37-5

Exchanging Identity Federation Data

■

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
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.

Note:

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

37-6 Administrator's Guide for Oracle Access Management

Exchanging Identity Federation Data

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: SP/IdP will use the applicable user attribute to
unspecified
populate/process the NameID value

Introducing Identity Federation in Oracle Access Management 37-7

Exchanging Identity Federation Data

Table 37–1 (Cont.) Supported SAML 2.0 NameID Formats
NameID Format

Description

urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
emailAddress
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
X509SubjectName
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
WindowsDomainQualifiedName
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format: SP/IdP will use the applicable user attribute to
kerberos
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format: SP/IdP will use either:
persistent
■
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: IdP will generate a random value
transient
custom value

When this NameID format is used, OIF/IdP will
use a user attribute to populate the NameID
value

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

37-8 Administrator's Guide for Oracle Access Management

Exchanging Identity Federation Data

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–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 documents the SAML 2.0 URLs for use when Identity Federation is
configured to act as an SP.
Table 37–3

SAML 2.0 URLs for Identity Federation Acting as Service Provider

Description

URL

Assertion Consumer Service http://public-oam-host:public-oam-port/oam/server/fed/sp/s
URL for Artifact binding
so
Assertion Consumer Service http://public-oam-host:public-oam-port/oam/server/fed/sp/s
URL for HTTP POST
so
binding
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

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.
Introducing Identity Federation in Oracle Access Management 37-9

Exchanging Identity Federation Data

■

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.
Table 37–4

Supported SAML 1.1 NameID Formats

NameID Format

Description

urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
unspecified
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
emailAddress
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
X509SubjectName
populate/process the NameID value
urn:oasis:names:tc:SAML:1.1:nameid-format: SP/IdP will use the applicable user attribute to
WindowsDomainQualifiedName
populate/process the NameID value
urn:oasis:names:tc:SAML:2.0:nameid-format: SP/IdP will use the applicable user attribute to
kerberos
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

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.

37-10 Administrator's Guide for Oracle Access Management

Exchanging Identity Federation Data

■

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–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 documents the SAML 1.1 URL for use when Identity Federation is
configured to act as an SP.
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

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

Introducing Identity Federation in Oracle Access Management 37-11

Exchanging Identity Federation Data

■

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

37-12 Administrator's Guide for Oracle Access Management

Exchanging Identity Federation Data

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–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 documents the OpenID 2.0 URLs for use when Identity Federation is
configured to act as an SP.
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

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

Introducing Identity Federation in Oracle Access Management 37-13

Administrating Identity Federation

Middleware WebLogic Scripting Tool Command Reference for Identity and Access
Management.
Partial administration of the WS-Federation 1.1 partners is
available using the Oracle Access Management Console.

Note:

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.
Not all WLST command functionality is duplicated in the
Oracle Access Management Console and not all console functionality
is duplicated on the command line.

Note:

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–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 outlines the tasks required to implement identity federation using the
Oracle Access Management Console.
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

37-14 Administrator's Guide for Oracle Access Management

Enabling Identity Federation

Table 37–10

(Cont.) Implementing Identity Federation

Task

Reference

Configure an authentication or authorization policy.

Chapter 40

Protect a resource with this policy.

Chapter 25

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.
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.
Note:

Figure 37–1 Available Services Page

Introducing Identity Federation in Oracle Access Management 37-15

Enabling Identity Federation

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.

37-16 Administrator's Guide for Oracle Access Management

38
Managing Identity Federation Partners
38

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

Managing Identity Federation Partners 38-1

Administering Identity Federation As A Service Provider

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.
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

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.

38-2 Administrator's Guide for Oracle Access Management

Administering Identity Federation As A Service Provider

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.

Managing Identity Federation Partners 38-3

Administering Identity Federation As A Service Provider

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.

38-4 Administrator's Guide for Oracle Access Management

Administering Identity Federation As A Service Provider

Table 38–2 (Cont.) Identity Provider Partner Settings
Element

Description

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.

Managing Identity Federation Partners 38-5

Administering Identity Federation As A Service Provider

Table 38–2 (Cont.) Identity Provider Partner Settings
Element

Description

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.

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.

Note:

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.

38-6 Administrator's Guide for Oracle Access Management

Administering Identity Federation As A Service Provider

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.

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:
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

Managing Identity Federation Partners 38-7

Administering Identity Federation As A Service Provider

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:
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

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.

38-8 Administrator's Guide for Oracle Access Management

Administering Identity Federation As A Service Provider

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

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.

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.

Managing Identity Federation Partners 38-9

Administering Identity Federation As An Identity Provider

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.

38-10 Administrator's Guide for Oracle Access Management

Administering Identity Federation As An Identity Provider

Table 38–6 (Cont.) Service Provider Partner Settings
Element

Description

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.

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.

Managing Identity Federation Partners

38-11

Using Attribute Mapping Profiles

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.

6.

■

Enable Global Logout

■

Encrypt Assertion

■

SSO Response Binding (HTTP POST or Artifact)

Click Save to keep the changes.
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:

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.
The protocol used by the provider must support the feature;
for example, OpenID 2.0.

Note:

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

38-12 Administrator's Guide for Oracle Access Management

Using Attribute Mapping Profiles

Access Manager attribute when including it in an Assertion or outgoing message.
Table 38–7 documents some sample SP attribute mappings.
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

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.
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.

Note:

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–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

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

session

Managing Identity Federation Partners

38-13

Using Attribute Mapping Profiles

Table 38–8 (Cont.) Attribute Mapping Value Expressions
Value Type

Accepted Values

Expression

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

- request:

-

expression
(Based on the
identifiers
defined above
and qualified
with the type
of data)

■

■

■

$request.httpheader.HTTP_
HEADER_NAME
$request.cookie.COOKIE_
NAME
$request.client_ip

- session:

■

■

-

$session.authn_level

■

■

$session.authn_scheme

■

■

$session.count

■

■

$session.creation

■

■

$session.expiration

■

■

$session.attr.ATTR_NAME

■

$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
Access Manager Session Attribute

-

■

■

COOKIE_NAME being the name of a
cookie

■

■

- from user:

HTTP_HEADER_NAME being the
name of an HTTP Header

ATTR_NAME being the name of an
LDAP User Attribute

■

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.

38-14 Administrator's Guide for Oracle Access Management

Mapping Federation Authentication Methods to Access Manager Authentication Schemes

■

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.
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

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.
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.

Note:

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.

Managing Identity Federation Partners

38-15

Mapping Federation Authentication Methods to Access Manager Authentication Schemes

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.

Note:

Table 38–10 lists the default, out-of-the-box mappings between FAMs and Access
Manager Authentication Schemes.
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

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:

38-16 Administrator's Guide for Oracle Access Management

Mapping Federation Authentication Methods to Access Manager Authentication Schemes

■

■

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).
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.

Note:

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.
Managing Identity Federation Partners

38-17

Using the Attribute Sharing Plug-in for the Attribute Query Service

■

A setting containing the alternate Authentication Scheme to use.
If the SP requested a specific Authentication Scheme,
evaluation does not apply.

Note:

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 
requestor and the IdP is an  responder. The Attribute Sharing
Plug-in depends on the Attribute Query Service, a request/response protocol
transported using SOAP.
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.

Note:

Identity Federation (when configured as an SP) can send a SAML 2.0
 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.

38-18 Administrator's Guide for Oracle Access Management

Using the Attribute Sharing Plug-in for the Attribute Query Service

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  using the requested attribute names over
a SOAP/HTTP/SSL channel to the IdP's Attribute Responder Service.
When invoking the Attribute Sharing plug-in, the framework
will provide the following for inclusion in the :

Note:
■
■

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

The Attribute Responder Service (at the remote IdP) receives the ,
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  (with
an  containing the attribute values) and returns a 
with the assertion to the SP. On receiving the , 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

Managing Identity Federation Partners

38-19

Using the Attribute Sharing Plug-in for the Attribute Query Service

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.
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.

Note:

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




alice@example.com







Example 38–2 is a sample SOAP attribute response.
Example 38–2

Sample SOAP Attribute Response




Success

alice@example.com

alice





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.
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.

Note:

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:

Managing Identity Federation Partners

38-21

Using the Attribute Sharing Plug-in for the Attribute Query Service

http://:/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.
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 .
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.

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.
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.

The following sections have additional details on parameters and how they determine
how the Attribute Sharing process.
■

NameID

■

NameID Format

■

IdP

■

RequestedAttributes

38-22 Administrator's Guide for Oracle Access Management

Using the Attribute Sharing Plug-in for the Attribute Query Service

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)
Use the NameID Format specified in the request.

1.
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.

Managing Identity Federation Partners

38-23

Using the Federation Proxy

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)
Use the IdP name included with the request sent to the Attribute Sharing plugin.

1.
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)
If the  from the SP contains requests for specific attribute values,
return values for those attributes.

1.
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
38-24 Administrator's Guide for Oracle Access Management

Using WLST for Identity Federation Administration

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.
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:

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.
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.

Note:

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.

Managing Identity Federation Partners

38-25

Using WLST for Identity Federation Administration

38-26 Administrator's Guide for Oracle Access Management

39
Managing Settings for Identity Federation
39

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 Settings for Identity Federation 39-1

Managing General Federation Settings

Figure 39–1 Identity Federation Service Settings Page

Table 39–1 outlines the types of federation settings you can configure.
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

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.

39-2 Administrator's Guide for Oracle Access Management

Managing Proxy Settings for Federation

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.
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

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.

Managing Settings for Identity Federation 39-3

Defining Keystore Settings for Federation

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.
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.

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.

39-4 Administrator's Guide for Oracle Access Management

Defining Keystore Settings for Federation

Figure 39–2 Keystore Settings

Table 39–4 describes each element on the Keystore Settings section of the Federation
Settings page.
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.

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)
AM denotes Access Manager, STS denotes Security Token
Service, and IF denotes Identity Federation in this discussion.

Note:

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.

Managing Settings for Identity Federation 39-5

Defining Keystore Settings for Federation

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.

39-6 Administrator's Guide for Oracle Access Management

Exporting Metadata

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.

Managing Settings for Identity Federation 39-7

Exporting Metadata

39-8 Administrator's Guide for Oracle Access Management

40
Managing Federation Schemes and Policies
04

[28To
]
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.
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

Note:

Managing Federation Schemes and Policies 40-1

Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)

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.

40-2 Administrator's Guide for Oracle Access Management

Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)

Table 40–1 (Cont.) FederationScheme Element Definitions
Element

Description

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.

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.

Managing Federation Schemes and Policies 40-3

Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)

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.

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.
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.

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.

40-4 Administrator's Guide for Oracle Access Management

Using Authentication Schemes and Modules for Identity Federation 11g Release 2 (11.1.2.2)

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
In the Oracle Access Management Console, click Application Security at the top
of the window.

1.
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"):

6.

■

Name

■

Authentication Scheme

Add these Global Policy Elements and Specifications:
■

Description (optional)

■

Success URL

■

Failure URL

Managing Federation Schemes and Policies 40-5

Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1

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).
The schemes used for Identity Federation in 11g Release 2
(11.1.2.3) are described in Section 40.2.

Note:

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.
See Also: For additional information about schemes, see
Section 22.9.
■

About Scheme OIFScheme

■

About the OIFMTLDAPPlugin Authentication Module

40-6 Administrator's Guide for Oracle Access Management

Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1

■

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).
See Section 40.2 for the schemes available with Identity
Federation 11g Release 2 (11.1.2.3).

Note:

Figure 40–5 OIFScheme

Table 40–4 describes the scheme OIFScheme.
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.

Managing Federation Schemes and Policies 40-7

Using Authentication Schemes and Modules for Oracle Identity Federation 11g Release 1

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.
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.

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.

40-8 Administrator's Guide for Oracle Access Management

Managing Access Manager Policies for Use with Identity Federation

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
In the Oracle Access Management Console, click Application Security at the top
of the window.

1.
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 Federation Schemes and Policies 40-9

Managing Access Manager Policies for Use with Identity Federation

Figure 40–7 Authorization Policy Response Tab

Table 40–6 describes the elements for a policy response.
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

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.

40-10 Administrator's Guide for Oracle Access Management

Managing Access Manager Policies for Use with Identity Federation

■

value is "sales".
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".

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:

Managing Federation Schemes and Policies 40-11

Testing Identity Federation Configuration

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:

40-12 Administrator's Guide for Oracle Access Management

Testing Identity Federation Configuration

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")

The Test SP Module should be disabled in a production
environment.

Note:

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.

Managing Federation Schemes and Policies 40-13

Using the Default Identity Provisioning Plug-in

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:
■

■

■

3.

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)

Enable user provisioning with the default plug-in by executing the WLST
command:
putBooleanProperty("/fedserverconfig/userprovisioningenabled","true")

40-14 Administrator's Guide for Oracle Access Management

Configuring the Identity Provider Discovery Service

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")

Managing Federation Schemes and Policies 40-15

Configuring the Identity Provider Discovery Service

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.
Check that the URL query parameter values are correctly
URL-encoded.

Note:

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.

40-16 Administrator's Guide for Oracle Access Management

Configuring the Identity Provider Discovery Service

<%@ 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");
%>






Select an Identity Provider



Provider ID


<%
Iterator idpIT = idps.iterator();
while(idpIT.hasNext())
{
String idp = (String)idpIT.next();
%>
<%=idp%>
<%
}
%>











Managing Federation Schemes and Policies 40-17

Configuring the Federation User Self-Registration Module





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.

40-18 Administrator's Guide for Oracle Access Management

Configuring the Federation User Self-Registration Module

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()

Managing Federation Schemes and Policies 40-19

Integrating OAM Identity Provider With Microsoft Office 365 Service Provider

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.
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.

The following sections contain the configuration details.
■

Configuring Microsoft Office 365 for OAM Integration

40-20 Administrator's Guide for Oracle Access Management

Integrating OAM Identity Provider With Microsoft Office 365 Service Provider

■

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=""
$url="https://server_host:port/oamfed/idp/samlv20"
$uri=""
$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

The values for some of these parameters can be found in the
OAM Identity Provider metadata.

Note:

3.

Create a user in the Federated domain by running the New-MsolUser PowerShell
command.
New-MsolUser -DisplayName  –UserPrincipalName
 -UsageLocation 
-BlockCredential $false -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=

■

uid=
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.

Note:

4.

Assign a license to the user to make the applications provided by Office 365
available to the user.

Managing Federation Schemes and Policies 40-21

Integrating OAM Identity Provider With Microsoft Office 365 Service Provider

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
For details on how to use the WLST commands needed in this
procedure, see the Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference.

Note:

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.

Table 40–7

Message Attribute Mapping

Message Attribute Name

Value

Always Send

IDPEmail

$user.attr.mail

true

5.

Create a Service Provider Partner for Office 365 using the attributes and values
documented in Table 40–8.

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

40-22 Administrator's Guide for Oracle Access Management

Integrating OAM Identity Provider With Microsoft Office 365 Service Provider

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(, )

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(, "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.
It is recommended to use BasicSessionlessScheme because
Office 365 only validates user credentials to get an assertion.

Note:

2.

Use the updatePartnerProperty WLST command to update the configuration to
send certificates in XML signatures.
updatePartnerProperty(,"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.

Managing Federation Schemes and Policies 40-23

Integrating OAM Identity Provider With Microsoft Office 365 Service Provider

■

2.

http://www.outlook.com/test.com: you should be automatically redirected to
the OAM login page.

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
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.

Note:

2.

Check that you can send and receive email successfully.

40-24 Administrator's Guide for Oracle Access Management

Part X
Part 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

[29The
]
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 is primarily based on the OASIS
WS-Trust protocol but it also delegates the processing of other WS-*
protocols present in the SOAP message.

Note:

Security Token Service brokers trust between a Web Service Consumer (WSC) and a
Web Service Provider (WSP) and provides security token lifecycle management

Introducing the Oracle Access Management Security Token Service 41-1

Using the Security Token Service

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
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".

Note:

The Security Token Service 11g infrastructure is described in Table 41–1.

41-2 Administrator's Guide for Oracle Access Management

Security Token Service Key Terms and Concepts

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)

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.
To provide interoperable security tokens, the Security Token
Service must be trusted by both the Web service client and the Web
service.

Note:

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.

Introducing the Oracle Access Management Security Token Service 41-3

Security Token Service Key Terms and Concepts

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:
■

ActAs

Token Exchange

the external entity represented by the token in the OnBehalfOf element.

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

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.

41-4 Administrator's Guide for Oracle Access Management

Security Token Service Key Terms and Concepts

Table 41–2 (Cont.) Security Token Service Terms
Term

Description

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.,

Introducing the Oracle Access Management Security Token Service 41-5

Integrating the Oracle Web Services Manager

Table 41–2 (Cont.) Security Token Service Terms
Term

Description

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:
■

■

■

Kerberos

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.

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).

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.
See Also: "About Access Manager Security Keys and the Embedded
Java Keystore"

41-6 Administrator's Guide for Oracle Access Management

Integrating the Oracle Web Services Manager

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:
■

■

Policy Interceptors

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.

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:

OPSS 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

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.

Introducing the Oracle Access Management Security Token Service 41-7

Architecting the Security Token Service

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

41-8 Administrator's Guide for Oracle Access Management

Deploying Security Token Service

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
See Also: "Scenario: Identity Propagation with the Access Manager
Token" on page 42-2

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

Introducing the Oracle Access Management Security Token Service 41-9

Deploying Security Token Service

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.

41-10 Administrator's Guide for Oracle Access Management

Installing Security Token Service

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.

Introducing the Oracle Access Management Security Token Service

41-11

Administrating the Security Token Service

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".

41-12 Administrator's Guide for Oracle Access Management

42
Security Token Service Implementation
Scenarios
42

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.

Security Token Service Implementation Scenarios

42-1

Scenario: Identity Propagation with the Access Manager Token

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).
■

■

2.

A Token Requestor could be an End User (generally not registered with the
Token Issuing Authority).

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:
■
■

3.

A Token Requestor could be a Partner of the Token Issuing Authority
(generally registered with the Token Issuing Authority).

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.

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.
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.

Note:

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.

42-2 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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.
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.

Note:

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,

Security Token Service Implementation Scenarios

42-3

Scenario: Identity Propagation with the Access Manager Token

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

42-4 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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

Security Token Service Implementation Scenarios

42-5

Scenario: Identity Propagation with the Access Manager Token

■

■

■

■

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
Client prepares the request by:

1.

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:

5.

6.

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

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

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

42-6 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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.
■

7.

If absent, Security Token Service will retrieve the Default Relying Party
Partner Profile from the Requester Partner Profile.

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

Security Token Service Implementation Scenarios

42-7

Scenario: Identity Propagation with the Access Manager Token

■

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/
Note: Replace  with the path configured in the STS
Endpoints section.

■

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

42-8 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

■
■

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.

Security Token Service Implementation Scenarios

42-9

Scenario: Identity Propagation with the Access Manager Token

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.

42-10 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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.

Security Token Service Implementation Scenarios

42-11

Scenario: Identity Propagation with the Access Manager Token

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

42-12 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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.
See Also:

"Introduction to Policy Responses for SSO" on page 25-68.

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).
See Also: "Adding and Managing Policy Responses for SSO" on
page 25-75.

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

Security Token Service Implementation Scenarios

42-13

Scenario: Identity Propagation with the Access Manager Token

■

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 

–

Password 

–

Confirm Password 

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:

42-14 Administrator's Guide for Oracle Access Management

Scenario: Identity Propagation with the Access Manager Token

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.

Security Token Service Implementation Scenarios

42-15

Scenario: Web Service Security With On Behalf Of Username Token

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.

42-16 Administrator's Guide for Oracle Access Management

Scenario: Web Service Security With On Behalf Of Username Token

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:
■
■

■

5.

■

■

Knowing the Requester Partner, Security Token Service will retrieve the
Requester Partner Profile associated with this Requester.

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.

Security Token Service then examines the AppliesTo field:
■

■

7.

Validates the credentials contained in the Username token against the Security
Token Service Partner store, thus mapping this token to a Requester Partner.

Security Token Service then validates the token present in the OnBehalfOf field:
■

6.

Validates the format of the Username token.

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.

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.
Security Token Service Implementation Scenarios

42-17

Scenario: Web Service Security With On Behalf Of Username 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:
■

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/

42-18 Administrator's Guide for Oracle Access Management

Scenario: Web Service Security With On Behalf Of Username Token

Note: Replace  with the path configured in the STS
Endpoints section.

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.

Security Token Service Implementation Scenarios

42-19

Scenario: Web Service Security With On Behalf Of Username Token

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

42-20 Administrator's Guide for Oracle Access Management

Scenario: Web Service Security With On Behalf Of Username Token

■

Trusted

■

Username Token Authentication

■

–

Username 

–

Password 

–

Confirm Password 

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.


Security Token Service Implementation Scenarios

42-21

Scenario: Web Service Security With On Behalf Of Username Token


requester-testwelcome1
http://docs.oasis-open.org/ws-sx/
ws-trust/200512/RST/Issue
http
://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAM
LV1.1
user-alice
<
/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.
http://docs.oasis-open.org/ws-sx/ws-t
rust/200512/RSTRC/IssueFinal

http://docs.oasis-open.org/wss/oa
sis-wss-saml-token-profile-1.1#SAMLV1.1
user-alice@example
.com
urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
user-alice-last



42-22 Administrator's Guide for Oracle Access Management

Scenario: Web Service Security With On Behalf Of Username Token


1GF2ZT9h+gs8sxyO+/yG/N6jxk8=

InZVb5aRM5+KKI1VqXg9HiIgLjKyGm0VkD6sMJ/8SIbFbbxuNm7Mnky5W35p2
P0c5bCPRx02uzLEE4KhLkyM2GsLsVaDNkRztGMphQW/Mcg7DprJIEyR2OYMYDOQSipa/k2K98C4zO/RNiv
o1KvyJsd6a3h6CBHwoO1RKip039w=
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=
id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-
id-1LNkSUVcpbH7O0oQwbHJ5JOd5fs-
2011-04-22T18:48:05Z2011-0422T19:48:05Z

Security Token Service Implementation Scenarios

42-23

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

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
Configuring Security Token Service Settings 43-1

Introduction to Security Token Service Configuration

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
See Also: Oracle Fusion Middleware Security and Administrator's Guide
for Web Services

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

43-2 Administrator's Guide for Oracle Access Management

Introduction to Security Token Service Configuration

2.

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

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
Managed servers hosting Security Token Service must be
registered with Access Manager as described in Chapter 6, "Managing
Server Registration".

Note:

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.

Configuring Security Token Service Settings 43-3

Introduction to Security Token Service Configuration

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.
See Also: "WS-Trust Policies and Configuration Steps" in Oracle
Fusion Middleware Security and Administrator's Guide for Web
Services

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

43-4 Administrator's Guide for Oracle Access Management

Introduction to Security Token Service Configuration

■
■

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.
See Also:
■

■

"Introduction to Oracle Access Management Keystores" on
page 5-31
Chapter 44, "Managing Security Token Service Certificates and
Keys"

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.
See Also:
■
■

Chapter 42, "Security Token Service Implementation Scenarios"
"About the Oracle Web Services Manager Keystore
(default-keystore.jks)" on page 44-3

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:
Configuring Security Token Service Settings 43-5

Introduction to Security Token Service Configuration

■

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
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

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.

43-6 Administrator's Guide for Oracle Access Management

Enabling and Disabling Security Token Service

Figure 43–2 WS-Security 1.0 and 1.1 Policies

See Also: "Using and Managing WSS Policies for Oracle WSM
Agents"

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

Configuring Security Token Service Settings 43-7

Enabling and Disabling Security Token Service

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.
43-8 Administrator's Guide for Oracle Access Management

Defining Security Token Service Settings

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.
See Also:

Chapter 2 for the following topics:

■

Logging Into the Oracle Access Management Console

■

Signing Out

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.

Configuring Security Token Service Settings 43-9

Defining Security Token Service Settings

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.

43-10 Administrator's Guide for Oracle Access Management

Defining Security Token Service Settings

Table 43–1 (Cont.) Security Token Service Settings
Element

Description

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.

Configuring Security Token Service Settings

43-11

Using and Managing WSS Policies for Oracle WSM Agents

Table 43–1 (Cont.) Security Token Service Settings
Element

Description

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).

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

43-12 Administrator's Guide for Oracle Access Management

Using and Managing WSS Policies for Oracle WSM Agents

■

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.
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

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.
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

Task overview: Managing WSS Policies for Security Token Service: Classpath
1. Define an OWSM Assertion Template.
2.

3.

Proceed as follows, depending on your need:
■

Modify an OWSM Policy

■

Define a Policy using the OWSM Assertion Template

Bundle the Assertion Template and policy in the sts-policies.jar file:
META-INF/assertiontemplates/oracle of the $ORACLE_IDM_HOME/oam/server/policy/

Configuring Security Token Service Settings

43-13

Using and Managing WSS Policies for Oracle WSM Agents

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.
All of Oracle WSM's functionality is accessible to
Administrators from Oracle Enterprise Manager Fusion Middleware
Control.

Note:

See Also: Oracle Fusion Middleware Security and Administrator's
Guide for Web Services
■

Part II, "Basic Administration"

■

Part III, "Advanced Administration"

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".

43-14 Administrator's Guide for Oracle Access Management

Configuring OWSM for WSS Protocol Communication

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
See "About Oracle WSM Agent WS-Security Policies for Security Token Service"

1.
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
See Also: Chapter 44, "Managing Security Token Service Certificates
and Keys"

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: "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 Security Token Service Settings

43-15

Configuring OWSM for WSS Protocol Communication

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
Enter the WSLT scripting environment.

1.
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
Locate keytool.

1.
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".

43-16 Administrator's Guide for Oracle Access Management

Configuring OWSM for WSS Protocol Communication

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
Locate keytool.

1.
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 Security Token Service Settings

43-17

Configuring OWSM for WSS Protocol Communication

■

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
See Also: Chapter 44, "Managing Security Token Service Certificates
and Keys"

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.
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

43-18 Administrator's Guide for Oracle Access Management

Managing and Migrating Security Token Service Policies

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.
Be sure to update policies and stspolicies.prop as needed
before migration.

Note:

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.

Configuring Security Token Service Settings

43-19

Logging Security Token Service Messages

See Also: "Using and Managing WSS Policies for Oracle WSM
Agents" on page 43-12.
■

■

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.
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.

Note:

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

43-20 Administrator's Guide for Oracle Access Management

Auditing the Security Token Service

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
Security Token Service integrates with Oracle Business
Intelligence Publisher which provides a pre-defined set of compliance
reports.

Note:

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

Configuring Security Token Service Settings

43-21

Auditing the Security Token Service

■

Configuring the audit store to point to the data source
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

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.
See Also: "About Audit Reports and Oracle Business Intelligence
Publisher" on page 8-4

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.
See Also: The topic on audit logs in the chapter on configuring and
managing auditing in the Oracle Fusion Middleware Security Guide

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

43-22 Administrator's Guide for Oracle Access Management

44
Managing Security Token Service Certificates
and Keys
44

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.

Managing Security Token Service Certificates and Keys 44-1

Introducing the Security Token Service Certificates and Keys

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

■

Validates SAML Assertions

■

Uses Web Services Security (WSS) protocol
communication

Between Requesters and Security Token Service (with OWSM
Agent)

Security Token Service uses the Relying Party's encryption
certificate to encrypt the outgoing token
Security Token Service uses the Issuing Authority's signing
certificate to verify the signature of the incoming SAML
Assertion

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
See Also: "Introduction to Oracle Access Management Keystores" on
page 5-31

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.
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.

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.
44-2 Administrator's Guide for Oracle Access Management

Introducing the Security Token Service Certificates and Keys

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.
Oracle strongly recommends that the Oracle WSM Agent
keystore and the Security Token Service keystore always be different.

Note:

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
See Also:
■

"Configuring OWSM for WSS Protocol Communication" on
page 43-15

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

Managing Security Token Service Certificates and Keys 44-3

Managing Security Token Service Encryption/Signing Keys

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
See Also: "Configuring OWSM for WSS Protocol Communication"
on page 43-15

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)
See Also: Oracle Fusion Middleware WebLogic Scripting Tool
Command Reference

To reset system and trust keystore passwords
Enter the WSLT scripting environment, as usual.

1.

44-4 Administrator's Guide for Oracle Access Management

Managing Security Token Service Encryption/Signing Keys

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.
See Also:
■

About Managing Token Issuance Templates

■

Searching for an Existing Template

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

Managing Security Token Service Certificates and Keys 44-5

Managing Security Token Service Encryption/Signing Keys

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.
See Also:

"About Security Token Service Settings" on page 43-9

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).

44-6 Administrator's Guide for Oracle Access Management

Managing Partner Keys for WS-Trust Communications

2.

Create a URL. For example:
http(s)://osts-hostname:osts-port/sts/servlet/samlcert?id=&encoding=, with:
■
■

3.

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)

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

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.

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.

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 Security Token Service Certificates and Keys 44-7

Managing Partner Keys for WS-Trust Communications

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".

44-8 Administrator's Guide for Oracle Access Management

Managing Certificate Validation

44.5 Managing Certificate Validation
This section describes managing certificate validation. Conditions for certificate
validation are described in Table 44–4.
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

Successful validation requirements are listed in Table 44–5.
Table 44–5

Successful Certificate Validation Requirements

Certificates Must ...

How ...

Be linked to 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:

by being a trusted anchor
or by having its issuer being a trusted
anchor

■

Against a list of CRLs that were uploaded
by the Administrator

■

Against an OCSP server

■

CRL Distribution Points

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.
Notification is performed using the JMX Notification
Framework and might take some time, depending on the notification
refreshing time (60 seconds by default).

Note:

Prerequisites
Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password
To manage the Trust Anchors store (amtruststore)
1. Locate keytool.

Managing Security Token Service Certificates and Keys 44-9

Managing Certificate Validation

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.
See Also:

"Managing Certificate Validation and Revocation" on

page 3-7
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.
Using a Custom Trust Anchor Store is an optional feature that
most customers will not need.

Note:

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.

44-10 Administrator's Guide for Oracle Access Management

45
Managing Templates, Endpoints, and Policies
45

[30The
]
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.

Managing Templates, Endpoints, and Policies 45-1

Searching for an Existing Template

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
Note:

Partners might need to be provisioned.

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

45-2 Administrator's Guide for Oracle Access Management

Searching for an Existing Template

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.

Managing Templates, Endpoints, and Policies 45-3

Searching for an Existing Template

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

Choose the token protocol from those listed:

Validation Template only

■

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

Provides the following functions that can be performed on a selection in the results table:

Shown: Actions for Validation
Template

Note: Actions menu functions mirror command buttons above the results table. For example:
■

■

■

■

View menu
Validation Template only
View menu
Issuance Template only
Up-Down Arrows

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.

A list from which you can identify Validation Template information to display in the results
table.
A list from which you can identify Issuance Template information to display in the results
table.
Controls you can choose to define the order of items listed in the results table:
■

Ascending

■

Descending

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.
See Also:

"About Template Search Controls"

45-4 Administrator's Guide for Oracle Access Management

Managing Token Issuance Templates

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
Templates the View menu in the Security Token Service section.

3.

Edit Search Criteria (Table 45–1). For example:

4.

■

Match: All

■

Name: contains em

■

Token Type: equals Username

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.
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

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.

Managing Templates, Endpoints, and Policies 45-5

Managing Token Issuance Templates

Figure 45–3 Issuance Template: General Details and Defaults

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.

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–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.

45-6 Administrator's Guide for Oracle Access Management

Managing Token Issuance Templates

Table 45–4 (Cont.) Issuance Properties: Username Token Type
Element

Description

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
Password Attribute Store

Attribute to be used to populate the Password element in the
Username Token.
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

Issuance Properties: SAML Token Types
SAML 1.1 and 2.0 token types require the issuance properties illustrated in
Figure 45–5.
These issuance properties differ from those for Username
token type.

Note:

Figure 45–5 Issuance Properties: SAML Token Types

Managing Templates, Endpoints, and Policies 45-7

Managing Token Issuance Templates

Table 45–5 describes all Issuance Properties by token type. Only SAML token types
require issuance properties.
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)

Security Details: SAML Tokens
Only SAML token types require Security Details, as shown in Figure 45–6 and
described in Table 45–6.

45-8 Administrator's Guide for Oracle Access Management

Managing Token Issuance Templates

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 References the key to be used to sign assertions created with this
Id
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

Compute Holder-of-Key
Symmetric Key

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

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 Templates, Endpoints, and Policies 45-9

Managing Token Issuance Templates

Table 45–6 (Cont.) Security Details: SAML Tokens
Elements

Description

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:

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.
See Also:

Table 45–7

Token Mapping attributes in Figure 45–9 and Table 45–11.

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.

45-10 Administrator's Guide for Oracle Access Management

Managing Token Issuance Templates

Table 45–7 (Cont.) Issuance Template: Attribute Mapping, SAML Token
Element

Description

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.
■

■
■

■
■

Attribute Value Filters

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.

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.

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.

Managing Templates, Endpoints, and Policies

45-11

Managing Token Issuance Templates

■

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.
See Also:
■

About Managing Token Issuance Templates

■

Searching for an Existing Template

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"

4.

f.

Click Apply (or click Revert without saving it).

g.

Close the definition.

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.

45-12 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

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.

6.

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).

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 Templates, Endpoints, and Policies

45-13

Managing Token Validation Templates

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.

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.

45-14 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

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
Token Protocol

Optional.
The type of Validation Template to be created. Type can be either:
■

■

Token Type

WS-Security: This template will be used to validate and map tokens
located in the Security SOAP Header of the incoming message

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:
■

■

Default Partner Profile

WS-Trust: This template will be used to validate and map tokens
included in the OnBehalfOf element of the WS-Trust request.

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

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"

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.

Managing Templates, Endpoints, and Policies

45-15

Managing Token Validation Templates

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
Validation Source

Description
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.

45-16 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

Table 45–10

(Cont.) New Validation Template: Authentication Details

Element

Description

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.

Connection Inactivity
Timeout

Maximum amount of inactivity time for an LDAP connection, before closing it.

Connection Read
Timeout

Maximum number of concurrent opened LDAP connections.

Default: 5000 (seconds)
Default: 5000 (seconds)
Default: 5000 (seconds)

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"
Managing Templates, Endpoints, and Policies

45-17

Managing Token Validation Templates

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

45-18 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

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 Templates, Endpoints, and Policies

45-19

Managing Token Validation Templates

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
Element
Map Token to

New Validation Template: Token Mapping
Description
WS-Security Validation Template: Map Token to list
■

: 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).

45-20 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

Table 45–11

(Cont.) New Validation Template: Token Mapping

Element

Description

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.

Managing Templates, Endpoints, and Policies

45-21

Managing Token Validation Templates

Table 45–11

(Cont.) New Validation Template: Token Mapping

Element

Description

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.

45-22 Administrator's Guide for Oracle Access Management

Managing Token Validation Templates

Table 45–11

(Cont.) New Validation Template: Token Mapping

Element

Description

Enable Simple Partner Only for WSS Validation Template and for the following token types: Username,
Mapping
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
■

■

Enable Partner Name
Identifier Mapping

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.

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.

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.

Managing Templates, Endpoints, and Policies

45-23

Managing Token Validation Templates

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
See Also:
■

"About Managing Token Validation Templates"

■

"Searching for an Existing Template"

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

3.

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).

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).

45-24 Administrator's Guide for Oracle Access Management

Managing Security Token Service Endpoints

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.
The WS-Security policy protecting the endpoint must be
compatible with the WSS Validation Template bound to the endpoint.

Note:

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

Managing Templates, Endpoints, and Policies

45-25

Managing Security Token Service Endpoints

Table 45–12 describes the required Endpoints categories.
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/",
")
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.

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

4.

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.

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).

45-26 Administrator's Guide for Oracle Access Management

Managing Token Issuance Policies, Conditions, and Rules

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.
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.

Note:

Managing Token Issuance Conditions is similar to managing Authorization
Conditions and Rules. Figure 45–4 shows the Conditions tab of a Token Issuance
Policy.

Managing Templates, Endpoints, and Policies

45-27

Managing Token Issuance Policies, Conditions, and Rules

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

45-28 Administrator's Guide for Oracle Access Management

Managing Token Issuance Policies, Conditions, and Rules

Table 45–13

(Cont.) Conditions tab: Token Issuance Policy

Element

Description

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.

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.
You can add Token Issuance Policies to the IAM Suite
Application Domain.

Note:

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:

4.

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.

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.

Managing Templates, Endpoints, and Policies

45-29

Managing TokenServiceRP Type Resources

5.

6.

Add Conditions to a Policy: The only types available are Token Requester
Identity or True.
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.

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.
7.

Click the Save button on the Condition Details panel.

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.

45-30 Administrator's Guide for Oracle Access Management

Managing TokenServiceRP Type Resources

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.

Note:

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).
See Also: Part XI, "Managing Oracle Access Management Mobile
and Social" for details about Configuring Access Manager for Mobile
and Social Authentication Service

■

■

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.
Both the MissingRP and UnknownRP are defined in the IAM
Suite Application Domain.

Note:

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

Managing Templates, Endpoints, and Policies

45-31

Managing TokenServiceRP Type Resources

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.
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"

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.

45-32 Administrator's Guide for Oracle Access Management

Making Custom Classes Available

3.

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.

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
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.

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.

Managing Templates, Endpoints, and Policies

45-33

Making Custom Classes Available

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
Token Type Name

Description
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.

45-34 Administrator's Guide for Oracle Access Management

Making Custom Classes Available

Table 45–14

(Cont.) New Custom Token Elements

Element
XML Element Namespace

Description
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.

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.

Managing Templates, Endpoints, and Policies

45-35

Making Custom Classes Available

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

45-36 Administrator's Guide for Oracle Access Management

Making Custom Classes Available

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
See Also:
■

"Making Custom Classes Available" on page 45-33

■

"About Narrowing a Search for Custom Tokens" on page 45-35

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:
■

■

■

2.

3.

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.

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.

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.

Managing Templates, Endpoints, and Policies

45-37

Managing a Custom Security Token Service Configuration

c.
4.

Reset the Search Form: Click the Reset button.

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.

5.

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.

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"

45-38 Administrator's Guide for Oracle Access Management

Managing a Custom Security Token Service Configuration

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 Templates, Endpoints, and Policies

45-39

Managing a Custom Security Token Service Configuration

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.

45-40 Administrator's Guide for Oracle Access Management

Managing a Custom Security Token Service Configuration

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.
See Also: Oracle Fusion Middleware Administrator's Guide for Oracle
Access Management

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

4.

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).

Edit a Template: Find the desired template, edit details, and click Apply.

Managing Templates, Endpoints, and Policies

45-41

Managing a Custom Security Token Service Configuration

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
In the Oracle Access Management Console Launch Pad, click Federation at the top
of the window.

1.
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

5.

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".

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

45-42 Administrator's Guide for Oracle Access Management

Managing a Custom Security Token Service Configuration

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.
5.

Click Apply, dismiss the confirmation window, and close the page (or click
Cancel to dismiss the page without submitting it).

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 Templates, Endpoints, and Policies

45-43

Managing a Custom Security Token Service Configuration

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.

45-44 Administrator's Guide for Oracle Access Management

46
Managing Token Service Partners and Partner
Profiles
64

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
See Also: Oracle Fusion Middleware WebLogic Scripting Tool Command
Reference

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.
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

Managing Token Service Partners and Partner Profiles 46-1

Introduction Token Service Partners and Partner Profiles

Table 46–1 (Cont.) Security Token Service Partners
Partner Type

Description

Issuing Authority

Represents an Assertion issuer. When validating an Assertion, its issuer must
be a known Issuing Authority Partner entry in Security Token Service

The Security Token Service is capable of interacting with client types described in
Table 46–2.
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.

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:
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.

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.
Table 46–4

Security Token Service Partner Profile Data

Client Type

Description

Requester

■
■

Relying Party
Issuing Authority

Claims Mappings
WS-Trust Validation Templates used to validate tokens present in
the OnBehalfOf element

■

Attributes to be sent to RP

■

Issuance Templates to be used

■

Attribute Name/Value Mapping settings

■

Specific Mapping Actions Rules used to map an incoming token
to a partner/user

46-2 Administrator's Guide for Oracle Access Management

Managing Token Service Partners

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 and Partner Profiles 46-3

Managing Token Service Partners

Table 46–5 (Cont.) Partner Elements for Partner Types
Partner Type

Description

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.

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.
Table 46–6

Elements for Security Token Service Partners

Element

Description

Partner Name

Enter a name for this partner.

Issuer ID

Unique identifier used in SAML Assertion Issuer field referencing this
Issuing Authority.

Issuing Authority Only
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

46-4 Administrator's Guide for Oracle Access Management

Managing Token Service Partners

Table 46–6 (Cont.) Elements for Security Token Service Partners
Element

Description

Username Token Authentication

Values can be entered for the following for Username Token
Authentication:

Requester only

■

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/

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.

Managing Token Service Partners and Partner Profiles 46-5

Managing Token Service Partners

3.

4.

5.

6.

7.

Select the desired partner type tab and proceed with following steps as needed.
■

Requesters

■

Relying Parties

■

Issuing Authorities

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.

Trusted: 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.

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.

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.

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.

46-6 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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 Partners and Partner Profiles 46-7

Managing Token Service Partner Profiles

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

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.

Requester Partner Profile Only

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.

46-8 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

Table 46–7 (Cont.) Profile: General
Element

Description

Default Token to Issue

This table indicates which Issuance Template to use to issue a
token for Relying Parties linked to this profile.

Relying Party Only

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.

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.
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.

Managing Token Service Partners and Partner Profiles 46-9

Managing Token Service Partner Profiles

Table 46–8 (Cont.) Requester Profile: Token and Attributes
Element

Description

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

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.

46-10 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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:
■

■

Attributes

Token Type list provides all supported (and custom) token
types deployed.
Issuance Template list contains all currently defined
Issuance Templates.

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".

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

Managing Token Service Partners and Partner Profiles

46-11

Managing Token Service Partner Profiles

■

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.

46-12 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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 Partners and Partner Profiles

46-13

Managing Token Service Partner Profiles

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).

46-14 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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.
■

■
■

Value Mapping

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

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.

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.

Managing Token Service Partners and Partner Profiles

46-15

Managing Token Service Partner Profiles

Figure 46–8 Issuing Authority Profile: Token Mapping Tab

46-16 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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.
■

■

Override User Name Identifier
Mapping

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

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.
■

■

Override Attribute Based User
Mapping

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.

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 Partners and Partner Profiles

46-17

Managing Token Service Partner Profiles

Table 46–11

(Cont.) Issuing Authority Token Mapping Elements

Element

Description

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.

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.

4.

■

Requester Profiles

■

Relying Party Profiles

■

Issuing Authority Profiles

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.

46-18 Administrator's Guide for Oracle Access Management

Managing Token Service Partner Profiles

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.
5.

6.

Click Save to submit (or click Cancel to dismiss the page) and then dismiss the
confirmation window.

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.

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.
7.

Click Apply to submit the changes (or Revert to cancel changes) and then
dismiss the confirmation window.

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 Partners and Partner Profiles

46-19

Managing Token Service Partner Profiles

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.

46-20 Administrator's Guide for Oracle Access Management

47
Troubleshooting Security Token Service
47

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:
  
   

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:

47-2 Administrator's Guide for Oracle Access Management

Mapping Operation Issues

[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: ] [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.
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.

Note:

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.

Troubleshooting Security Token Service 47-3

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

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.
Device fingerprinting and knowledge-based authentication
both require Oracle Adaptive Access Manager.

Note:

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

Understanding Mobile and Social

48-1

Introducing Mobile and Social

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.
Prior to version 11.1.2.3, Mobile and Social Services was
named Mobile Services.

Note:

■

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.
Prior to version 11.1.2.2, Social Identity was named Internet
Identity Services.

Note:

■

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.
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.

Note:

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.

48-2 Administrator's Guide for Oracle Access Management

Introducing Mobile and Social

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.

Note:

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.
Table 48–1

Features in Mobile and Social Based on the Companion Services Installed

Feature

Mobile and
Social Only

✔

✔

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)

Mobile and
Social +
OAAM

✔

Access Manager token support
using native Access Manager
authentication dialogs
JWT token support for
authentication and
authorization

Mobile and
Social +
Access
Manager

✔

Mobile and
Social +
Access
Manager +
OAAM
✔

✔

✔

✔

✔

✔

✔

✔

Understanding Mobile and Social

48-3

Introducing Mobile and Social

Table 48–1 (Cont.) Features in Mobile and Social Based on the Companion Services
Mobile and
Social +
Access
Manager

Mobile and
Social Only

Feature
Multi-step authentication
support (knowledge-based
authentication and one time
password support)

Mobile and
Social +
Access
Manager +
OAAM

Mobile and
Social +
OAAM
✔

✔

Interact with a Directory server ✔
and support User Profile
services

✔

✔

✔

✔

✔

✔

✔

Relying party support for
Internet-based Identity
Providers (Facebook, Google,
Twitter, LinkedIn, Yahoo)

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 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:

Note:

CFGFWK-64071- the selection conflicted with templates
already installed in the domain OAM with database policy
store 11.1.1.3.0

■

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.

48-4 Administrator's Guide for Oracle Access Management

Understanding Mobile and Social Services

■

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

48-5

Understanding Mobile and Social Services

■

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.
A non-mobile device can use either mobile services or
non-mobile services as long as the correct input is provided.

Note:

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.

48-6 Administrator's Guide for Oracle Access Management

Understanding Mobile and Social Services

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.

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.
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."

Note:

Understanding Mobile and Social

48-7

Understanding Mobile and Social Services

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.
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."

Note:

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.

48-8 Administrator's Guide for Oracle Access Management

Understanding Mobile and Social Services

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.
The Mobile SSO Agent is only supported on Android and iOS
devices.

Note:

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.
Table 48–3
SDK

Android, iOS, and Java Features of the Mobile and Social Services Client

Feature

Android

Build a mobile application that can acquire Client
Registration Handle, User, and Access Tokens
through a Mobile and Social Server

✔

iOS
✔

✔

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

Java

✔

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

Understanding Mobile and Social

48-9

Understanding the Mobile and Social Services Processes

■

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.
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:

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.
Applications are also typically configured to require a User
Token and an Access Token.

Note:

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

48-10 Administrator's Guide for Oracle Access Management

Understanding the Mobile and Social Services Processes

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.
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.

Note:

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.

Understanding Mobile and Social 48-11

Understanding the Mobile and Social Services Processes

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

Get App Profile
getSession() &
getAccessToken()

Present Login Page
User name/Password
Register (User, password, device attributes, appID)

*Authenticate (User, password, attributes)

Successful User Authentication
Register App (appID, device profile attribute)
OAAM Device Handle and
OAAM Session Handle
Mobile Client Registration Handle,
OAAM Device and Session Handles

Get User Token
Get Access Token

48-12 Administrator's Guide for Oracle Access Management

Understanding the Mobile and Social Services Processes

Figure 48–2 Mobile SSO Agent Requests Access Token from Access Manager

Mobile User

Customer
App (Mobile
Device)

Mobile
SSO
Agent

Mobile and
Social
Server

Access
Manager

OAAM

Access App
Get App Profile

getSession() &
getAccessToken()

Present Login Page
User name/ Password
Authenticate (User, password, attributes)

Successful Authentication

Register App (appID, oaam device handle,
device profile attributes)
OAAM Result/ Action
Client Registration

Handle for Customer App

Get Access Token

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
Understanding Mobile and Social 48-13

Understanding the Mobile and Social Services Processes

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
Client Web Tier
REST/SOAP
User App

Client
REST/
SOAP
Server

3

Mobile SSO Agent

b.

2
Authentication

Mobile and Social

1
Access
Token

Access
Manager

OAAM

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).

48-14 Administrator's Guide for Oracle Access Management

Understanding the Mobile and Social Services Processes

Figure 48–4 Mobile SSO Agent Does Not Have Valid Access Token in Credential Store

Client App (Mobile)
1

Request User Token

Mobile SSO Agent
2

Oracle
SDK

Mobile and Social Server
(Server)

• If valid User token exists in
localcredential store,
return the token to App.
Else continue below.

3

• Publishes ID context to
Access Manager

• Present login page.
5

Use token to make
REST/SOAP calls to
client server protected by
Access Manager or OEG

• Invokes OAAM for risk
analysis

• Accept username/password.
• Extract device attributes
and ID contexts.

• Responds User/Access
Tokens

• Makes authentication call
with user/password, and
device attributes.
4

• Authenticates with
Access Manager

• Stores User/Access Token
• Returns token to Client App

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.

Understanding Mobile and Social 48-15

Understanding the Mobile and Social Services Processes

Figure 48–5 User Authentication Using REST

Native App #1...#n

Client Web Tier

1

7

REST/SOAP

IDM SDK

2

Agent

Mobile Device

Client
REST/
SOAP
Server

6

Mobile SSO Agent
Device
Registration

5 Store Credential
Mobile and Social
SDK

4

Mobile
and Social

3 Prompt Login
Access
Manager
OAAM

• Register Device/App

Device
Database
Provisioning
/Deprovisioning

• Authenticate User
• Get Access Token
• Get User Attributes

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.)

48-16 Administrator's Guide for Oracle Access Management

Understanding the Mobile and Social Services Processes

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

Mobile User

Browser
(Mobile
Device)

Mobile
SSO
Agent

App Web
Server

Mobile and
Social Server

Access
Manager &
OAAM

Access Web URL
Redirect to Access Manager
Redirect to local app
Redirect
Present Login Page
User name/Password
Fingerprint & Authenticate
Access Token
Inject cookie
Redirect
App Pages
Redirected to original Web URL

Pages from App Web Server

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."

Understanding Mobile and Social 48-17

Understanding the Mobile and Social Services Processes

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:

3.

■

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

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.)

48-18 Administrator's Guide for Oracle Access Management

Using Mobile and Social Services

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

Understanding Mobile and Social 48-19

Using Mobile and Social Services

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.
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.

Note:

Table 48–4

Token Requirements for the Mobile and Social Server

Device or App Type
Seeking to Register
Non-Mobile Device
(Unregistered)
Mobile SSO Agent App

Token(s), Credentials, and/or Data
Required by the Mobile and Social
Server
Type of Token Returned
An ID and password associated with Client Token
a client application sent over
HTTPS.
■

■

■

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.

48-20 Administrator's Guide for Oracle Access Management

Client Registration
Handle

Using Mobile and Social Services

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

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.

Client Registration
Handle

- 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.

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)
Understanding Mobile and Social 48-21

Understanding Social Identity

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

48-22 Administrator's Guide for Oracle Access Management

Understanding Social Identity Processes

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.
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

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.

Understanding Mobile and Social 48-23

Understanding Social Identity Processes

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."

Note:

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.

48-24 Administrator's Guide for Oracle Access Management

Understanding Social Identity Processes

Figure 48–8 Authenticating a Returning User with a Local Account
AAA/Idm or App
User

Browser
AuthUI

Mobile and
Social
Server

Local
Auth

ID Repository

Local
Reg

IDP

AuthUI
IDP Select

SSO + Attr Protocol (Eg: OPENID)
New or Existing User?
Existing user:
AuthN flow

POST 
Existing User: Authentication

New Session

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:

Understanding Mobile and Social 48-25

Understanding Social Identity Processes

■

■

6.

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.

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.

48-26 Administrator's Guide for Oracle Access Management

Understanding Social Identity Processes

Figure 48–9 Authenticating a New User with No Local Account
AAA/IdM or App
User

Browser
AuthUI [C1]

Mobile and
Social
Server

Local
Auth

ID Repository

Local
Reg

IDP

AuthUI
IDP Select

SSO + Attr Protocol (Eg: OPENID)
New or Existing User
New User:
Initiate REG flow

New User: Retrieve user attrs

New User: POST 
New User: Registration
Registration Complete
New Session

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

Understanding Mobile and Social 48-27

Understanding Social Identity Processes

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.

48-28 Administrator's Guide for Oracle Access Management

Understanding Social Identity Processes

Figure 48–10

Authenticating a User With an OAuth Identity Provider

AAA/Idm or App
Browser

User

Mobile and
Social
Server

Client
App

ID Repository

Local
Reg

OAuth SP

1 Client Apps UI to access
OAuth resource
2 User accesses
protected
resource

3 Get Access Token
for given scope

4 Access Token not found.
Get authorization code with Mobile and Social ID, scope, and redirect URL

5.1 User authenticates with the Provider 5.2 and gives consent to allow resources to be accessed by the client

6 OAuth Provider returns authorization code to Mobile and Social

7 Get Access Token using the authorization code, OAuth Client ID and
Credential used by the Mobile and Social Server.

8 OAuth Provider returns token to Mobile and Social

9 Persist Access Token with User ID, scope, and return Access Token
to client URL.

10

Access the resource using the Access Token

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.

Understanding Mobile and Social 48-29

Understanding Social Identity Processes

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.

48-30 Administrator's Guide for Oracle Access Management

Understanding Social Identity Processes

Figure 48–11

User
Browser

Protected
Application

Authenticating a User with Access Manager

WebGate

Credential
Collector

Access
Manager

Mobile and
Social

Social
Identity
Provider

1 User tries to access
protected application

2 WebGate Intercepts
and redirects to Access Manager

3 Access Manager Identifies the authentication policy and redirects for Credential Collection

4 Credential collector presents Identity Provider Login Selection Page.

5 Access Manager reads the selection and redirect to Mobile and Social as per the contract
6 Mobile and Social
completes the
authentication process

7 Mobile and Social redirects to the Access Manager Auth scheme with status and user attributes

8 Access Manager creates a session and completes the access protection

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.
■
■

4.

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.

The Access Management Service creates a session for the user and the user
accesses the protected resource.

Understanding Mobile and Social 48-31

Using Social Identity

Figure 48–12

Authenticating a User Locally
AAA/Idm or App

User

Browser
AuthUI

Mobile and
Social
Server

Local
Auth

ID Repository

Local
Reg

IDP

AuthUI
Local Login
Select

Existing User: authentication

New Session

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.

48-32 Administrator's Guide for Oracle Access Management

Using Social Identity

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.

Understanding Mobile and Social 48-33

Using Social Identity

48-34 Administrator's Guide for Oracle Access Management

49
Configuring Mobile and Social Services
49

[31Mobile
]
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
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.

Note:

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.

WARNING:

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.

Configuring Mobile and Social Services 49-1

Understanding Mobile and Social Services Configuration

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
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.

Note:

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

49-2 Administrator's Guide for Oracle Access Management

Understanding Mobile and Social Services Configuration

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.
Configuring Mobile and Social Services 49-3

Defining Service Providers

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

49-4 Administrator's Guide for Oracle Access Management

Defining Service Providers

■

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.
See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a Webgate.

Note:

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.

Configuring Mobile and Social Services 49-5

Defining Service Providers

Table 49–1

Pre-configured Authentication Service Providers

Authentication
Service

Mobile and Social Service
Provider Name

Access Manager

OAMAuthentication

Description
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

49-6 Administrator's Guide for Oracle Access Management

Defining Service Providers

Table 49–1 (Cont.) Pre-configured Authentication Service Providers
Authentication
Service

Mobile and Social Service
Provider Name

JWT-OAM Token
Provider

JWTOAMAuthentication

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

Description
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.

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

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."

Configuring Mobile and Social Services 49-7

Defining Service Providers

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.
■
■

■

4.

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.

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).
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.

Note:

■

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.

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."

49-8 Administrator's Guide for Oracle Access Management

Defining Service Providers

Table 49–2 (Cont.) Access Manager Authentication Service Provider Default Attributes
Name

Default Value

Notes

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

Type the Webgate agent name that
identifies the Webgate instance to which
you are connecting.

Webgate ID

Encrypted Password

■

Notes

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–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.

Configuring Mobile and Social Services 49-9

Defining Service Providers

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 is specific to the JWTOAMAuthentication and the
MobileJWTOAMAuthentication Service Provider types.
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.

49-10 Administrator's Guide for Oracle Access Management

Defining Service Providers

Table 49–5 (Cont.) JWT-OAM Authentication Service Provider Default Attributes
Name

Default Value

user.Authenticator

■

■

Notes

Default value
for
JWTOAMAuthent
ication
provider:
oracle.securi
ty.idaas.rest
.provider.tok
en.OAMSDKToke
nServiceProvi
der

Optional. Specify which of two available
authenticators to use for user
authentication.
■

■

Default value
for
MobileJWTOAMA
uthentication
provider:
oracle.securi
ty.idaas.rest
.provider.tok
en.JWTTokenSe
rviceProvider

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.

Configuring Mobile and Social Services

49-11

Defining Service Providers

Table 49–5 (Cont.) JWT-OAM Authentication Service Provider Default Attributes
Name

Default Value

Notes

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.

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).

49-12 Administrator's Guide for Oracle Access Management

Defining Service Providers

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).

Configuring Mobile and Social Services

49-13

Defining Service Providers

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.

49-14 Administrator's Guide for Oracle Access Management

Defining Service Providers

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.)

Configuring Mobile and Social Services

49-15

Defining Service Providers

- KEY_SEARCH_BASE_URL: ou=users,dc=ngam,dc=oracle,dc=com
e.
4.

On the Steps Orchestration tab, choose UI from the Initial Step menu.

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.

6.

7.

8.

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.

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.

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).

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.

49-16 Administrator's Guide for Oracle Access Management

Defining Service Providers

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.
■
■

■

4.

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.

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.

Configuring Mobile and Social Services

49-17

Defining Service Providers

Table 49–6 (Cont.) Access Manager Authorization Service Provider Default Attributes
Name

Value

Notes

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.

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.

Table 49–7

Webgate Agent for Authorization Service Provider Default Attributes

Name

Value

Type the Webgate agent name that
identifies the Webgate instance to which
you are connecting.

Webgate ID

Encrypted Password

6.

Notes

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.

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)

49-18 Administrator's Guide for Oracle Access Management

Defining Service Providers

■

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.
■
■

4.

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.

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, If accessControl is enabled, specify the
ou=myrealm,dc=base_domain 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.

Configuring Mobile and Social Services

49-19

Defining Service Providers

Table 49–8 (Cont.) User Profile Service Provider Default Attribute Names and Values
Name

Value

Notes

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.

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.
■

■

■

6.

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."

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.
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.

49-20 Administrator's Guide for Oracle Access Management

Defining Service Providers

Table 49–9 (Cont.) User Profile Service Provider Default Attribute Names and Values
Name

Default Value

Notes

adminGroup

cn=Administrators,ou=groups, If accessControl is enabled, specify the
ou=myrealm,dc=base_domain
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.

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, ...}, ... }

Configuring Mobile and Social Services

49-21

Defining Service Profiles

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.
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."

Note:

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.

49-22 Administrator's Guide for Oracle Access Management

Defining Service Profiles

The Authentication Service Profile Configuration page displays.
3.

Enter values for the Authentication Service Profile general properties.

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.

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–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.

Configuring Mobile and Social Services

49-23

Defining Service Profiles

Table 49–11

(Cont.) Token Support and URI Category Information Default Properties

Name

Notes

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.

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.

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.

49-24 Administrator's Guide for Oracle Access Management

Defining Service Profiles

Table 49–12

(Cont.) Authorization Service Profile Default General Properties

Name

Notes

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.

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.

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.

Configuring Mobile and Social Services

49-25

Defining Security Handler Plug-ins

Table 49–13

(Cont.) User Profile Service Profile Default General Properties

Name

Notes

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.

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.
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.

Note:

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

49-26 Administrator's Guide for Oracle Access Management

Defining Security Handler Plug-ins

■

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.

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.

4.

Enter name-value pairs for the Security Handler Plug-in Attributes.
■

■

5.

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.

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.

Configuring Mobile and Social Services

49-27

Defining Application Profiles

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.

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.

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.
■

■

■

5.

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.

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."

49-28 Administrator's Guide for Oracle Access Management

Defining Application Profiles

■

6.

Mobile Configuration - Select this option to expose additional mobile
configuration settings on the Application Profile Configuration page.

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  in its
.
Note:

The scheme (xyz) should be the same as the URL scheme.

For details regarding the  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

Configuring Mobile and Social Services

49-29

Defining Service Domains

application is signed. On Linux, you can obtain the signature using the
following command:
keytool -exportcert -alias  -keystore 
-storepass  | xxd -c 256 -ps
The signature obtained using the above command will have a
carriage return after 256 characters. Remove it before entering the
signature in this field.

Note:

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.

Table 49–16

Service Domain General Properties

Name

Notes

Name

Type a unique name for this Service Domain.

49-30 Administrator's Guide for Oracle Access Management

Defining Service Domains

Table 49–16

(Cont.) Service Domain General Properties

Name

Notes

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."

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.

Table 49–17
Name

Application Profile Selection Properties
Notes

Application Profile Name The name that uniquely identifies the client application to Mobile
and Social.

Configuring Mobile and Social Services

49-31

Defining Service Domains

Table 49–17

(Cont.) Application Profile Selection Properties

Name

Notes

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.

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.

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."

49-32 Administrator's Guide for Oracle Access Management

Defining Service Domains

Table 49–18

(Cont.) Service Profile Selection Properties

Name

Notes

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."

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.

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.

b.

If you previously selected an Authorization Service for this Service Domain,
configure the security settings to protect it.

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.

9.

Click Next to verify your selections.

10. Click Finish to create the Service Domain.

Configuring Mobile and Social Services

49-33

Using the Jailbreak Detection Policy

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.
OAAM's BLOCK and Mobile and Social's DENY mean the
same thing.

Note:

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."

49-34 Administrator's Guide for Oracle Access Management

Using the Jailbreak Detection Policy

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
Version.
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

49-35

Configuring Mobile and Social Services with Other Oracle Products

■

■

■

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
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.

Note:

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.

49-36 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

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.

Name

Value

PASSPHRASE

The passwd value from step 2.

KEYSTORE

/oam-domain/config/fmwconfig/oamclient-keystore.jks

TRUSTSTORE

/oam-domain/config/fmwconfig/oamclient-truststore.jks

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.
Configuring Mobile and Social Services

49-37

Configuring Mobile and Social Services with Other Oracle Products

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.
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.

Note:

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.

49-38 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

Name: userPrincipalAttrValue
Value: 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
Value: 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.
See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a Webgate.

Note:

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
Note: If using an OAM 11.1.1.n release console, enable Allow
Management 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.

Configuring Mobile and Social Services

49-39

Configuring Mobile and Social Services with Other Oracle Products

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.

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.
Use the following command to display the wallet before and
after the merge for verification that the merge has been successful.

Note:

orapki wallet display -wallet wallet_location
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




49-40 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products


File-based credential provider



















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:")
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

49-41

Configuring Mobile and Social Services with Other Oracle Products

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:

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
Note: See the Administrator's Guide for Oracle Adaptive Access Manager
for information on how to set up OAAM rule and policy ordering.

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.
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

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.

49-42 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

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

■

■

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.

Configuring Mobile and Social Services

49-43

Configuring Mobile and Social Services with Other Oracle Products

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.

49-44 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

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

49-45

Configuring Mobile and Social Services with Other Oracle Products

■

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
1.

Creating a Generic Strings Group to Store Blacklisted Application Names

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
1.

Creating a New Blacklisted Application Rule

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.

49-46 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

■
■

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.

9.

Complete the form as follows and click Search:
■

Condition Name - Type Check Current Session

■

Type - Choose In Session from the menu.

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

49-47

Configuring Mobile and Social Services with Other Oracle Products

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.
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.

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
49-48 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

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.
Note:

Configure either SMTP or UMS. Do not configure both.

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.

Configuring Mobile and Social Services

49-49

Configuring Mobile and Social Services with Other Oracle Products

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://:/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."

49-50 Administrator's Guide for Oracle Access Management

Configuring Mobile and Social Services with Other Oracle Products

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://:/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

49-51

Configuring Mobile and Social Services with Other Oracle Products

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.

49-52 Administrator's Guide for Oracle Access Management

50
Configuring Social Identity
05

[32Mobile
]
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
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.

Note:

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.

WARNING:

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.

Configuring Social Identity 50-1

Understanding Social Identity Configuration

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."
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.

Note:

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.

50-2 Administrator's Guide for Oracle Access Management

Defining Social Identity Providers

■

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

Configuring Social Identity 50-3

Defining Social Identity Providers

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.

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 Choose a signature algorithm. Mobile
key length
and Social uses this value internally to
algorithm
configure the Session Type and
Association Type properties for
SHA1 is a 160-bit
communicating with the Identity
key length
Provider.
algorithm
None

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

■

Provide values required by the Identity Provider implementing the OAuth
protocol as specified in Table 50–2.

50-4 Administrator's Guide for Oracle Access Management

Defining Social Identity Providers

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.

Configuring Social Identity 50-5

Defining Social Identity Providers

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.

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

■

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.

50-6 Administrator's Guide for Oracle Access Management

Defining Social Identity Providers

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.

Note:

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.
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.

■

6.

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.

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.

Configuring Social Identity 50-7

Defining Social Identity Providers

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
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.

Note:

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.

50-8 Administrator's Guide for Oracle Access Management

Defining Social Identity Providers

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.

Configuring Social Identity 50-9

Defining Social Identity Providers

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

50-10 Administrator's Guide for Oracle Access Management

Defining Service Provider Interfaces

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:

Configuring Social Identity

50-11

Defining Service Provider Interfaces

■

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.
■
■

4.

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.

Enter values for the Interface Information properties as specified in Table 50–7.

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.

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.

50-12 Administrator's Guide for Oracle Access Management

Defining Application Profiles

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.
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.

Note:

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,

Configuring Social Identity

50-13

Defining Application Profiles

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

■

4.

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.

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.
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.

■

■

■

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

50-14 Administrator's Guide for Oracle Access Management

Defining Application Profiles

attributes are used to pre-populate the registration page with the User's profile
data.
■

■

■

■

5.

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.

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.

Configuring Social Identity

50-15

Integrating Social Identity With Mobile Applications

■

■

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.
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.

■

■

7.

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.

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.

50-16 Administrator's Guide for Oracle Access Management

Linking Social Identity Provider Accounts

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.

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.

Note:

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.

Configuring Social Identity

50-17

Linking Social Identity Provider Accounts

■

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

2

Mobile Services
(REST)

User logs in using
Enterprise ID

1 User Clicks Login
9

Return to user

Third-Party
Application

IDP account is
linked to Enterprise
account
6
7
IDP account
successfully linked

3
8

Authenticated
user, requests
account linking
via IDP

Internet Identity
Services (RP)

Account linking
response
comp lete

User
authenticated
by IDP
5
4

Internet Identity
(Google, Yahoo, etc.)

User is
redirected to IDP
for authentication

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.

50-18 Administrator's Guide for Oracle Access Management

Linking Social Identity Provider Accounts

■

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.
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:

Note:

■

■

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.

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.
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.

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

Configuring Social Identity

50-19

Linking Social Identity Provider Accounts

correct. For example, the MatchLDAPAttribute should match the username
attribute set in the relying party Application Profile, typically uid.

50-20 Administrator's Guide for Oracle Access Management

51
Configuring Social Identity System Settings
51

[3This
]
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.
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.

Note:

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.
Configuring Social Identity System Settings 51-1

Logging and Auditing

■

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.

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

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.

51-2 Administrator's Guide for Oracle Access Management

Deploying Mobile and Social With Oracle Access Manager

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 /cwallet.sso /tmp/oam
# cp config/fmwconfig/cwallet.sso /tmp/oic

c.

Create file merge-creds.xml:




File-based credential provider




















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 Social Identity System Settings 51-3

Configuring a Webgate to Support Social Identity

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

WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /ms_oauth/*


51-4 Administrator's Guide for Oracle Access Management

Configuring a Webgate to Support Social Identity

# the following directive proxies all the OAM managed server requests.

WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /oam/*

4.

5.

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.

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:

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://:/oam/server/dap/cred_submit ", user="="", password="
DCC5332B4069BAB4E016C390432627ED", desc="");

51-6 Administrator's Guide for Oracle Access Management

Enabling the REST Client to Specify the Tenant Name

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

If you do not specify the JVM option, the server will expect the
client to use the default header name, X-ID-TENANT-NAME.

Note:

3.

Save the file.

Configuring Social Identity System Settings 51-7

Enabling the REST Client to Specify the Tenant Name

51-8 Administrator's Guide for Oracle Access Management

Part XII
Part 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
25

[34OAuth
]
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 52-1

Understanding OAuth Services Authorization for Web Clients

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.
OAuth does not impose special requirements on the
interaction between a Resource Server and an Authorization Server.

Note:

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

52-2 Administrator's Guide for Oracle Access Management

Understanding OAuth Services Authorization for Web Clients

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.
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:

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.
The Authorization Code grant type is required for 3-legged
authorization. See Section 52.4.3, "Understanding Clients" for details.

Note:

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.
Understanding OAuth Services 52-3

Understanding OAuth Services Authorization for Web Clients

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

User
Agent

Client
Application

OAM User
Login

Resource
Server

Token
Service

Authorization
Service

1. Access Client App
2. Authorization request
3. Redirect to OAM user login
4. OAM user login UI
5. Enter user credentials
6. OAM redirect to authorization after valid login
7. User
needs
to give
consent

8. Show user consent page
9. User gives consent
10. Return authorization code client app
11. Access token request
12. Verify client and
user consent

13. Return access token after validation
14. Access the resource with access token
15. Validate access
token
16. Access token
validation response
17. Return resource details to client

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
52-4 Administrator's Guide for Oracle Access Management

Understanding OAuth Services Authorization for Mobile Clients

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.
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:

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.
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."

Note:

■

■

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.

Understanding OAuth Services 52-5

Understanding OAuth Services Authorization for Mobile Clients

Figure 52–2 Using a Split Request to get a Client Verification Code

User

Mobile Client
App

Token
Service

Push Service

APNS / GCM
Service

Typical communication pattern involving APNS
1. Launch app
2. Acquire
pre-Authorization code
3. Return first part of
pre-authorization code
4. Request second part of pre-authorization code
5. Receive second part of pre-authorization

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.

52-6 Administrator's Guide for Oracle Access Management

Understanding OAuth Services Authorization for Mobile Clients

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 52-7

Understanding OAuth Services Authorization for Mobile Clients

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.

52-8 Administrator's Guide for Oracle Access Management

Requested resources received.

Access token received.

Client token assembled along
with a refresh token.

Authorization code assembled
in preparation for the access
token request.

Client token assembled along
with a refresh token.

Authorization code assembled
in preparation for the client token
request.

Push Service

6. Authorization request with pre-authorization code

APNS / GCM
Service

16. Show user challenge question

32. Token validation response

30. Request resources with AT

29. Return to complete
access token (AT)

28. Acquire AT with client
token + authorization
code

27. Client receives the second part of the authorization code

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).

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.

OAM User
Login

7. Redirect to
OAM user login

19. Return first part of authorization code through mobile redirect URL

Resource
Server

33. Resource response

31. Validate access token

18. Plug-in validates the
challenge answer

15. Plug-in may
decide to challenge

Adaptive
Access Plug-in

14. Check with plug-in
before returning to
authorization code

11. User needs
to give consent

Authorization
Service

10. OAM redirect to authorization after valid login

8. OAM user login UI

User Agent

12. Show user consent page

21. Client receives the second part of the authorization code

20. Request the second part of the authorization
code (in preparation for requesting a client token)

17. User provides challenge answer

13. User gives consent

Token
Service

Steps 2-5: Get a pre-authorization code by sending a split request to the Token Service and the APNS/GCM Service.

Mobile Client
App

9. Enter user ID and password

1. Launch app

User

Understanding OAuth Services Authorization for Mobile Clients

Figure 52–3 The Complete Mobile App Authorization Request Flow

Understanding OAuth Services 52-9

Understanding the OAuth Services Components

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

52-10 Administrator's Guide for Oracle Access Management

Understanding the OAuth Services Components

■

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 OAuth Services

52-11

Understanding the OAuth Services Components

(For general information about the OAuth specification grant
types, see http://tools.ietf.org/html/rfc6749#section-1.3.

Note:

■

■

■

■

■

■

■

■

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.

52-12 Administrator's Guide for Oracle Access Management

Understanding the OAuth Services Components

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.

Note:

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."

Understanding OAuth Services

52-13

Understanding the OAuth Services Components

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.
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

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 The OAuth client can request
create, read, search, update, and
POST allows create
delete privileges for any user
profile.
PUT allows update

PUT allows update

DELETE allows delete
http://host:port/ms_oauth/
resources/userprofile/groups

GET allows read, search The OAuth client can request
create, read, search, update, and
POST allows create
delete privileges for any group
profile.
PUT allows update
DELETE allows delete

http://host:port/ms_oauth/
GET allows read
resources/userprofile/secretkey
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.

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.

52-14 Administrator's Guide for Oracle Access Management

Understanding the OAuth Services Components

■

■

■

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) Resource
Method URI

UserProfile.me

GET

/me

uid, mail, description,
commonname, firstname, lastname

/users

uid, mail, description,
commonname, firstname, lastname

/groups

name, description

PUT
UserProfile.users

GET

Attributes

POST
PUT
DELETE
UserProfile.groups

GET
POST
PUT
DELETE

Understanding OAuth Services

52-15

Understanding the OAuth Services Components

Table 52–2 (Cont.) User Profile Resource Server - Scope Settings
HTTP(S) Resource
Method URI

Scope

UserProfile.secretkey.ma GET
nagement
POST

Attributes

/secretkey There are no attributes needed.

DELETE

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."
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."

Note:

52-16 Administrator's Guide for Oracle Access Management

Understanding the OAuth Services Components

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.
Note:

Multiple Consent Management Services are not necessary.

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
Understanding OAuth Services

52-17

Understanding OAuth Services Tokens

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.
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.

Note:

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

52-18 Administrator's Guide for Oracle Access Management

Understanding OAuth Services Tokens

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 OAuth Services

52-19

Understanding the Authorization and Authentication Endpoints

■

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)://:/ms_
oauth/oauth2/endpoints//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)://:/ms_
oauth/oauth2/endpoints//token

52-20 Administrator's Guide for Oracle Access Management

Understanding Mobile OAuth Services Server-Side Single Sign-on

■

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)://:/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)://:/ms_
oauth/oauth2/ui//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.
Note:

WebGates do not support validating access tokens.

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

Understanding OAuth Services

52-21

Understanding Mobile OAuth Services Server-Side Single Sign-on

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
52-22 Administrator's Guide for Oracle Access Management

Understanding Mobile OAuth Services Server-Side Single Sign-on

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 OAuth Services

52-23

Understanding Mobile OAuth Services Server-Side Single Sign-on

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

52-24 Administrator's Guide for Oracle Access Management

Understanding OAuth Services Plug-ins

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

52-25

Understanding OAuth Services Plug-ins

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.

Note:

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.

52-26 Administrator's Guide for Oracle Access Management

53
Configuring OAuth Services
53

[35Oracle
]
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
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.

Note:

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"

Configuring OAuth Services 53-1

Configuring OAuth Services Components in an Identity Domain

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.)

53-2 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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 53-3

Configuring OAuth Services Settings

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."

53-4 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

■
■

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.
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.

Note:

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.

Configuring OAuth Services 53-5

Configuring OAuth Services Settings

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.
53-6 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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 53-7

Configuring OAuth Services Settings

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
For details, see Section 53.4, "Configuring OAuth Services for
Third-Party JWT Bearer Assertions."

Note:

Table 53–1

OAuth Service Profile Configuration Attributes

Name

Value

Notes
Private key alias name for the signing
certificate in the keystore. The default
alias will be used if this attribute is not
specified.

jwt.cert.alias

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.CryptoScheme

RS512

jwt.issuer

www.oracle.example. This issuer of the tokens (that is, the iss
com
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

53-8 Administrator's Guide for Oracle Access Management

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

Table 53–1 (Cont.) OAuth Service Profile Configuration Attributes
Name

Value

Notes

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

oauthServerSelfClientId Value to be specified

The tenant claim name in the tokens
issued by OAuth Services. By default this
is set using the identity domain name.
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 Value in seconds to be The default value is 300sec. This attribute
tyInSec
is related to oauthServerSelfClientId
specified
(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."

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).
Configuring OAuth Services 53-9

Configuring OAuth Services Settings

■

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.

53-10 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

53-11

Configuring OAuth Services Settings

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:

53-12 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

■

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

53-13

Configuring OAuth Services Settings

■

■

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.
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.

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
53-14 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

53-15

Configuring OAuth Services Settings

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.

53-16 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

■

■

■

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

53-17

Configuring OAuth Services Settings

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
Note:

Only one Service Provider can be configured at a time.

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.

53-18 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

oam.OAM_SERVER_1_MAX_CONN 4

oam.OAM_SERVER_2

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:5575 Specify the host name and port number
of the secondary Oracle Access
Management server.

oam.OAM_SERVER_2_MAX_CONN 4

oam.AuthNURLForUID

Specify the host name and port number
of the primary Oracle Access
Management server.

Specify the maximum number of
connections that this Mobile and Social
instance can establish with OAM_
SERVER_2. The default value is 4.

wl_
authen://sample_
ldap_no_pwd_
protected_res

Configuring OAuth Services

53-19

Configuring OAuth Services Settings

Table 53–3 (Cont.) OAuth Service Provider Attributes for Access Manager
Name

Value

Notes

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.

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.

53-20 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

53-21

Configuring OAuth Services Settings

■

■

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.

53-22 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

53-23

Configuring OAuth Services Settings

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.
Table 53–4

User Profile Service Attributes

Name

Value

accessControl

false

adminGroup

cn=Administrators,ou=groups,ou=myrealm,dc=base_domain

selfEdit

true

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://:/.../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.

53-24 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

■

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

53-25

Configuring OAuth Services Settings

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.
53-26 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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

53-27

Configuring OAuth Services Settings

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.
See Section 48.1.2, "Deploying Mobile and Social" for
information about deploying Mobile and Social with a WebGate.

Note:

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.

53-28 Administrator's Guide for Oracle Access Management

Configuring OAuth Services Settings

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.
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.

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
Configuring OAuth Services

53-29

Configuring OAuth Services Settings

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

53-30 Administrator's Guide for Oracle Access Management

Configuring OAuth Services for Third-Party JWT Bearer Assertions

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.
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

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)."
Note:

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

Configuring OAuth Services

53-31

Configuring OAuth Services for Third-Party JWT Bearer Assertions

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:

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 --> .
 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
Any changes made during this procedure require a restart of
the OAM server.

Note:

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:

53-32 Administrator's Guide for Oracle Access Management

Configuring OAuth Services for Third-Party JWT Bearer Assertions

■

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_password
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  element.
1.

In a text editor, open the keystore settings file:
$DOMAIN_HOME/config/fmwconfig/jps-config.xml

2.

Find the  node for the keystore.provider Provider, and add
the following:





Configuring OAuth Services

53-33

Configuring OAuth Services for Third-Party JWT Bearer Assertions







Where:
■

service-instance-name = Any service-instance-name

■

keystore-location = Path to the keystore file

Example 53–3

Update jps-config.xml










3. Find the  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  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




... other serviceInstanceRef elements ...


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

53-34 Administrator's Guide for Oracle Access Management

Configuring OAuth Services for Third-Party JWT Bearer Assertions

■

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

53-35

Configuring OAuth Services for Third-Party JWT Bearer Assertions

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

53-36 Administrator's Guide for Oracle Access Management

Configuring a WebGate to Protect OAuth Services

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.
A WebGate proxy is required to use the 3-legged authorization
scenario with an external LDAP directory server.

Note:

1.

Install the Oracle HTTP Server 11g Webgate for OAM using the instructions in
Installing Webgates for Oracle Access Manager.
Configuring OAuth Services

53-37

Configuring a WebGate to Protect OAuth Services

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

WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /ms_oauth/*

# the following directive proxies all the OAM managed server requests.

WebLogicHost host123.us.example.com
WebLogicPort 17100
Debug ON
WLLogFile /tmp/weblogic.log
MatchExpression /oam/*


53-38 Administrator's Guide for Oracle Access Management

Configuring OAM Session Synchronization

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.
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.

Note:

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.

■

Value - Enter: ${session.id}

Click Add.

Configuring OAuth Services

53-39

Configuring Mobile OAuth for SSO Servlet Authentication

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:

53-40 Administrator's Guide for Oracle Access Management

Configuring Mobile OAuth for SSO Servlet Authentication

■

■

■

■

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://:/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://: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://:/ms_
oauth/mobilesso?OAM_ID=1234&resource_
url=http://: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 OAuth Services

53-41

Configuring Mobile OAuth for SSO Servlet Authentication

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.)

53-42 Administrator's Guide for Oracle Access Management

Configuring the Mobile Security Manager Plug-in

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 OAuth Services

53-43

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

[36The
]
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
Configuring the Access Portal Service 54-1

Overview of the Access Portal Service Deployment Process

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.

54-2 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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

Configuring the Access Portal Service 54-3

Deploying the Access Portal Service

■

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

54-4 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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: 
IDSTORE_PORT: 
IDSTORE_DIRECTORYTYPE: ad
IDSTORE_BINDDN: \Administrator
IDSTORE_PASSWD: 
IDSTORE_USERNAMEATTRIBUTE: cn
IDSTORE_LOGINATTRIBUTE: cn (or another login attribute)>

Configuring the Access Portal Service 54-5

Deploying the Access Portal Service

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 : 
ESSO_IDSTORE_PORT : 
ESSO_IDSTORE_BINDDN : \Administrator
ESSO_IDSTORE_TYPE : ad
IS_ESSO_PRESENT : true
ESSO_IDSTORE_PASSWD : 

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.

54-6 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

■

■

■

■

■

■

■

■

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
Configuring the Access Portal Service 54-7

Deploying the Access Portal Service

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

54-8 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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.

■

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

Configuring the Access Portal Service 54-9

Deploying the Access Portal Service

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.

54-10 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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
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:
Note:

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_OAMADMINUSER

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
Configuring the Access Portal Service 54-11

Deploying the Access Portal Service

the Identity Store Configuration File.
This command does the following:
■
■

5.

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.

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.

54-12 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

After you run idmConfigTool, several files are created that you
need for subsequent tasks. Keep these in a safe location.

Note:

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.

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:
/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.

Configuring the Access Portal Service 54-13

Deploying the Access Portal Service

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.
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:

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

7.

Test the connection and correct any errors if necessary, then click Apply.

8.

Update the LDAP authentication module:

9.

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.

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.

54-14 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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:

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
f.

fully qualified DN of the repository root

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:

Configuring the Access Portal Service 54-15

Deploying the Access Portal Service

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.

54-16 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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  section and add the following
line inside it:
schema.ms.xml

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:








b.

Add the following to the system.web section:






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:

Configuring the Access Portal Service 54-17

Deploying the Access Portal Service

Field

Value

Path

ColumbiaWindowsAgent/V1/AgentAcl

Type

ColumbiaWindowsAgent.Rest.AgentAcl, OAMAgent

Name

OAMAgent

6.

7.

8.

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.

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.

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:
ColumbiaWindowsAgent/V1/AgentAcl
iis-server-hostname
54-18 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

https
Name="Port" Type="xsd:string">iis-server-port
Name="Version" Type="xsd:string">1
Name="ADPath" Type="xsd:string">AD-server-hostname:port

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.
-1

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.

Configuring the Access Portal Service 54-19

Deploying the Access Portal Service

The listCred command in OPSS has been deprecated in this
release; keystore passwords must now be retrieved programmatically.

Note:

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:
If a keystore type is not explicitly specified in the embedded
trust provider configuration section of the following file:

Note:

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
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

54-20 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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:

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

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:
Configuring the Access Portal Service 54-21

Deploying the Access Portal Service

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.
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.
1.

Launch the 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.

54-22 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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.

Configuring the Access Portal Service 54-23

Deploying the Access Portal Service

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

54-24 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

3.

4.

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

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
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.

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:
Configuring the Access Portal Service 54-25

Deploying the Access Portal Service

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).

54-26 Administrator's Guide for Oracle Access Management

Deploying the Access Portal Service

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  block in the httpd.conf file.

5.

Enable CGI for the following block into the  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:
Configuring the Access Portal Service 54-27

Deploying the Access Portal Service

/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.
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."

Note:

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):

3.

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.

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.

54-28 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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:
■
■

■

6.

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.

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.
Configuring the Access Portal Service 54-29

Enabling Form-Fill Single Sign-On for an Application

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):
■
■

■

■

■

■
■

9.

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.

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.

54-30 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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.

Configuring the Access Portal Service 54-31

Enabling Form-Fill Single Sign-On for an Application

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.
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.

Note:

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:

3.

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.

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.

54-32 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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.

Configuring the Access Portal Service 54-33

Enabling Form-Fill Single Sign-On for an Application

■

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.

54-34 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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

AuthTrans fn="set-variable" set-headers="referer=https://#ORIGIN_
HOST#/$1"

#Rewrite the http referer header

AuthTrans fn="set-variable" set-headers="referer=http://#ORIGIN_
HOST#/$1"

#Remove potential headers that may interfere with mixed proxy
content

Output fn="sed-response-header" name="content-security-policy"
sed="s|script-src |script-src 'self' |g"


Output fn="set-variable"
remove-srvhdrs="access-control-allow-origin"

#rewrite the location header when origin server is redirecting from
HTTP to HTTPS

Output fn="set-variable"
$srvhdrs{'location'}="https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#$2"


Configuring the Access Portal Service 54-35

Enabling Form-Fill Single Sign-On for an Application


Output fn="set-variable"
$srvhdrs{'location'}="http://$urlhost:#OTD_HTTP#/#PROXY_MAP#/$2"

#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"

54-36 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

#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|/\\([^/][^<]*\\)|/#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"

Configuring the Access Portal Service 54-37

Enabling Form-Fill Single Sign-On for an Application

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:

Route fn="set-origin-server"
origin-server-pool="origin-server-pool-https-www-originapp-com"
rewrite-host="true"


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

54-38 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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:

AuthTrans fn="set-variable"
set-headers="referer=https://www.oracle.com/$1"

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.

Note:

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:



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:

54-40 Administrator's Guide for Oracle Access Management

Enabling Form-Fill Single Sign-On for an Application

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:

Configuring the Access Portal Service 54-41

Enabling Form-Fill Single Sign-On for an Application

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.

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.
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 ""
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
For example, adding the following to obj.conf
54-42 Administrator's Guide for Oracle Access Management
Enabling Form-Fill Single Sign-On for an Application
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=""
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.
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).
For example:

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):
Configuring the Access Portal Service 54-43
Enabling Form-Fill Single Sign-On for an Application
■
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"
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.
Note:
Then, add one or more of the following parameters to obj.conf for the header
injection SAF and the credential capture filter:
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.
For example:
NameTrans fn="EssoBasicAuth" policy="BasicAuth1" realm="realm1"
Output fn="insert-filter" filter="esso_output_capture" policy="BasicAuth1"
realm="realm1"
54-44 Administrator's Guide for Oracle Access Management
Enabling Form-Fill Single Sign-On for an Application
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
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:
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:

NameTrans fn="EssoClean"

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.
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
Configuring the Access Portal Service 54-45
Adding a Federated Partner Provider Application
being passed, add the following rewrite rule to the Oracle Traffic Director
configuration to strip out the GUID value:

AuthTrans fn="set-variable" set-reqpb="query=$1$3"

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:
4.
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.
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.
54-46 Administrator's Guide for Oracle Access Management
Creating an Application Configuration Package
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:
4.
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.
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.
Configuring the Access Portal Service 54-47
Creating an Application Configuration Package
■
■
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.*
54-48 Administrator's Guide for Oracle Access Management
Creating an Application Configuration Package
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:

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-participant-myapplication-com
inet
https

participant.myapplication.com


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:

NameTrans fn="assign-name" id="route-myapplication"
name="route-myapplication"

Configuring the Access Portal Service 54-49
Creating an Application Configuration Package
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:
The package generation tool requires an up-to-date Java
Runtime Environment installation.
Note:
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 generatedprefix. 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:

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:
54-50 Administrator's Guide for Oracle Access Management
Managing Password Generation Policies

paste contents here

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.
Configuring the Access Portal Service 54-51
Managing Password Generation Policies
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.
2.
Click the Create Password Generation Policy button to launch the New Password
Policy tab, which contains two sub-tabs:
■
Summary
■
Password Constraints
On the Summary tab, enter the following information:
■
A distinct name for the policy.
■
(Optional) A meaningful description to identify the policy.
■
3.
(Optional) Internal reference information describing the version/variant of the
policy.
Click the Password Constraints tab.
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).
Note:
On the Password Constraints tab, specify the following:
■
Length Constraints
54-52 Administrator's Guide for Oracle Access Management
Managing Password Generation Policies
■
■
■
–
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
–
■
■
■
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
–
■
Enter a list of specific characters to exclude from a password. Do not use
any delimiters.
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.
Configuring the Access Portal Service 54-53
Managing Password Generation Policies
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.
Note:
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.
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.
54-54 Administrator's Guide for Oracle Access Management
Managing Credential Sharing Groups
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.
Configuring the Access Portal Service 54-55
Managing Credential Sharing Groups
Applications will share credentials only for their initial
deployment unless you enable credential sharing groups.
Note:
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:
54-56 Administrator's Guide for Oracle Access Management
Managing Credential Sharing Groups
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:
4.
–
Username
–
Password
–
Third Field
–
Fourth Field
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.
Note: This field is available only if Key credential within group is
set to None.
7.
Click Save to complete policy configuration, or Cancel to close the tab without
saving the group.
Configuring the Access Portal Service 54-57
Managing Credential Sharing Groups
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.
54-58 Administrator's Guide for Oracle Access Management
Managing Global Agent Settings
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
Configuring the Access Portal Service 54-59
Managing Global Agent Settings
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:
54-60 Administrator's Guide for Oracle Access Management
Managing Global Agent Settings
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.
Configuring the Access Portal Service 54-61
Managing Global Agent Settings
–
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
Note:
■
Values less than 2 are treated as 2.
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:
7.
–
.*http://login\.company\.com/.*
–
.*http://.*\.company\.com/.*
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.
54-62 Administrator's Guide for Oracle Access Management
Managing Global Agent Settings
8.
In the Masked Fields Security settings, specify the following.
■
■
■
9.
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.
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.
Configuring the Access Portal Service 54-63
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
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.
Using Identity Context 55-1
Introducing Identity Context
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.
55-2 Administrator's Guide for Oracle Access Management
Understanding Identity Context
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
Using Identity Context 55-3
Working With the Identity Context Service
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
Type
Virtual
Primary
Publisher
oracle:idm:claims:n value
ameid
string
no
OAM
Indicates a unique user identifier.
Access Manager currently
publishes User DN
oracle:idm:claims:n format
ameid
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 qualifier
ameid
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.
Namespace
Attribute
55-4 Administrator's Guide for Oracle Access Management
Description
Working With the Identity Context Service
Table 55–1 (Cont.) Identity Context Schema Attributes
Type
Virtual
Primary
Publisher
oracle:idm:claims:n spprovidedid
ameid
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
Indicates fingerprint of the client
OESSO,
device.
Oracle
Access
Manageme
nt Mobile
and Social
(OMS)
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 newdevice
sk
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 level
sk
integer
no
OAAM
Indicates risk level. Level
increases after unsuccessful logins.
oracle:idm:claims:ri safeforuser
sk
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 fingerprint
sk
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
Namespace
Attribute
Description
Using Identity Context 55-5
Working With the Identity Context Service
Table 55–1 (Cont.) Identity Context Schema Attributes
Namespace
Attribute
Type
Virtual
Primary
Publisher
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.
55-6 Administrator's Guide for Oracle Access Management
Description
Working With the Identity Context Service
Table 55–1 (Cont.) Identity Context Schema Attributes
Namespace
Attribute
Type
Virtual
Primary
Publisher
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.)
Description
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.
Using Identity Context 55-7
Working With the Identity Context Service
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.
55-8 Administrator's Guide for Oracle Access Management
Using the Identity Context API
Table 55–2
Mapping Identity Context Operations
Role and Context
Operation
Description
Publisher - publishes Trusted security framework protecting an
Identity Context
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.
Propagator propagates Identity
Context
Evaluators evaluate 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.
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.
Components
■
OAM – Session,
Federation, and identity
store attributes
■
OAAM – Risk attributes
■
OESSO – Device attributes
■
■
■
■
■
■
■
■
OMS Mobile SDK - Device
attributes
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
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.
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 iterNamespace = idCtxDict.getAllNamespaces();
while (iterNamespace != null && iterNamespace.hasNext()) {
String namespace = iterNamespace.next();
System.out.println("Namespace : " + namespace);
Iterator
Using Identity Context 55-9
Using the Identity Context API
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 ('', '','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
import
import
import
import
Working with Identity Context Runtime
java.security.AccessController;
java.security.PrivilegedAction;
oracle.security.jps.internal.api.runtime.AppSecurityContext;
oracle.security.idm.IdentityContext;
…
// get runtime ID Context from OPSS
private static Object getIDContext() {
Object idc = AccessController.doPrivileged(new PrivilegedAction