Contents

List of Figures

List of Tables

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

1 Introduction to the Developer's Guide

• 1.1 Native Integration
• 1.2 Universal Installation Option Integrations
• 1.3 Customizations and Extensions
• 1.4 Authentication and Password Management Integration
• 1.5 Migration and Lifecycle Management
• 1.6 Custom Development
• 1.7 Troubleshooting/FAQ

Part I Native Integration

2 Natively Integrating with Oracle Adaptive Access Manager

• 2.1 Overview
  • 2.1.1 Using Web Services and SOAP API
  • 2.1.2 Using Static Linking
• 2.2 Integration Options
  • 2.2.1 Integrating with Virtual Authentication Devices and Knowledge-Based Authentication
    • 2.2.1.1 User Name Page (S1)
    • 2.2.1.2 Device Fingerprint Flow (F1)
    • 2.2.1.3 Run Pre-Authentication Rules (R1)
    • 2.2.1.4 Run Virtual Authentication Device Rules (R2)
    • 2.2.1.5 Decode Virtual Authentication Device Input (P4)
    • 2.2.1.6 Validate User and Password (CP1)
    • 2.2.1.7 Run Post-Authentication Rules (R3)
    • 2.2.1.8 Check Registration for User (C2)
    • 2.2.1.9 Run Registration Required Rules (R4)
    • 2.2.1.10 Enter Registration Flow (P6)
    • 2.2.1.11 Run Challenge Rules (R5)
    • 2.2.1.12 Run Authentication Rules (R6)
    • 2.2.1.13 Challenge the User (S6)
    • 2.2.1.14 Check Answers to Challenge (C3)
    • 2.2.1.15 Lock Out Page (S2)
    • 2.2.1.16 Landing or Splash Page (S3)
  • 2.2.2 Integrating with Knowledge-Based Authentication
    • 2.2.2.1 User/Password (S1)
    • 2.2.2.2 Stages

3 Integrating Native .NET Applications

• 3.1 Introduction
• 3.2 Oracle Adaptive Access Manager .NET SDK
• 3.3 Configuration Properties
  • 3.3.1 How the API Uses Properties
  • 3.3.2 Encrypting Property Values
  • 3.3.3 Using User-Defined Enumerations to Define Elements
• 3.4 Oracle Adaptive Access Manager API Usage
  • 3.4.1 User Details
  • 3.4.2 User Logins and Transactions
  • 3.4.3 Rules Engine
    • 3.4.3.1 Device ID
    • 3.4.3.2 Creating and Updating Bulk Transactions
  • 3.4.4 Validating a User with Challenge Questions
  • 3.4.5 Resetting Challenge Failure Counters
  • 3.4.6 Virtual Authentication Devices
    • 3.4.6.1 Creating a Virtual Authentication Device
    • 3.4.6.2 Embedding a Virtual Authentication Device in a Web Page
    • 3.4.6.3 Validating User Input with a Virtual Authentication Device
  • 3.4.7 Specifying Credentials to the Oracle Adaptive Access Manager SOAP Server
  • 3.4.8 Tracing Messages
• 3.5 Integration Example Using Sample Applications
  • 3.5.1 ASP.NET Applications
  • 3.5.2 Sample Application Details
    • 3.5.2.1 SampleWebApp
    • 3.5.2.2 SampleWebAppTracker
    • 3.5.2.3 SampleWebAppAuthTracker
    • 3.5.2.4 SampleKBATracker
  • 3.5.3 Setting Up the Environment
    • 3.5.3.1 Modifying the web.config File
    • 3.5.3.2 Setting Properties for Images
    • 3.5.3.3 Running the Application
  • 3.5.4 Example: Enable Transaction Logging and Rule Processing

4 Integrating Native Java Applications

• 4.1 About the Oracle Adaptive Access Manager Shared Library
  • 4.1.1 Using Oracle Adaptive Access Manager Shared Library in Web Applications
  • 4.1.2 Using Oracle Adaptive Access Manager Shared Library in Enterprise Applications
  • 4.1.3 Customizing/Extending/Overriding Oracle Adaptive Access Manager Properties
• 4.2 OAAM Java InProc Integration
• 4.3 OAAM SOAP Integration
  • 4.3.1 Set up SOAP Security
  • 4.3.2 Set SOAP Related Properties in bharosa_server.properties
• 4.4 About VCryptResponse
• 4.5 Oracle Adaptive Access Manager APIs
  • 4.5.1 handleTrackerRequest
  • 4.5.2 createTransaction
  • 4.5.3 updateTransaction
  • 4.5.4 handleTransactionLog
  • 4.5.5 updateTransactionStatus
  • 4.5.6 updateLog
  • 4.5.7 getUserByLoginId
  • 4.5.8 generateOTP
  • 4.5.9 updateAuthStatus
  • 4.5.10 processPatternAnalysis
  • 4.5.11 markDeviceSafe
  • 4.5.12 IsDeviceMarkedSafe
  • 4.5.13 clearSafeDeviceList
• 4.6 Rules Engine
  • 4.6.1 processRules
• 4.7 Customer Care
  • 4.7.1 getFinalAuthStatus
  • 4.7.2 setTemporaryAllow
  • 4.7.3 cancelAllTemporaryAllows
  • 4.7.4 resetUser
  • 4.7.5 getRulesData
  • 4.7.6 getActionCount

5 Native API for OTP Challenge

• 5.1 OTP Integration Overview
  • 5.1.1 One Time Password (OTP)
  • 5.1.2 OAAM OTP Challenge Functionality
  • 5.1.3 Sample
• 5.2 OTP Registration and Challenge Experience
• 5.3 New User Registration
  • 5.3.1 User Name Entered on Login Page
  • 5.3.2 Password Page is Presented and User Enters Password
  • 5.3.3 User Enters Registration Flow
    • 5.3.3.1 User selects an authentication pad background image
    • 5.3.3.2 User registers challenge questions
    • 5.3.3.3 User Opts In to OTP
    • 5.3.3.4 User registers profile information
    • 5.3.3.5 User Agrees to Terms and Conditions
  • 5.3.4 User Continues into Application
• 5.4 User OTP Challenge
  • 5.4.1 User Name Entered on Login Page
  • 5.4.2 Password Page is Presented and User Enters Password
  • 5.4.3 OAAM Rules Determine User Should Be Challenged via OTP
    • 5.4.3.1 Generate OTP Code and Code is Delivered to the User through Custom Implementation
    • 5.4.3.2 User Presented with Challenge Page
    • 5.4.3.3 User Enters the Generated Code Sent to Him by the Application and is Validated by Custom Implementation
  • 5.4.4 User Continues Into the Application

Part II Universal Installation Option

6 Oracle Adaptive Access Manager Proxy

• 6.1 Introduction
  • 6.1.1 Important Terms
  • 6.1.2 Architecture
  • 6.1.3 References
• 6.2 Installing UIO ISA Proxy
  • 6.2.1 UIO Proxy Web Publishing Configuration
    • 6.2.1.1 Web Listener Creation
    • 6.2.1.2 Web Publishing Rule Creation
  • 6.2.2 Registering the UIO ISA Proxy DLL
  • 6.2.3 Settings to Control the UIO Proxy
    • 6.2.3.1 Configuration files
    • 6.2.3.2 Configuration Reload
    • 6.2.3.3 Session ID Cookie
    • 6.2.3.4 Configuring Session Id Cookie attributes via Global Variables
    • 6.2.3.5 Session Inactive Interval
    • 6.2.3.6 Settings for Troubleshooting
• 6.3 Installing UIO Apache Proxy
  • 6.3.1 UIO Proxy Files for Windows and Linux
    • 6.3.1.1 Windows
    • 6.3.1.2 Linux
  • 6.3.2 Apache httpd Requirements
    • 6.3.2.1 Windows
    • 6.3.2.2 Linux
  • 6.3.3 Copying the UIO Apache Proxy and Supported Files to Apache
    • 6.3.3.1 Windows
    • 6.3.3.2 Linux
  • 6.3.4 Configuring Memcache (for Linux only)
  • 6.3.5 Configuring httpd.conf
    • 6.3.5.1 Basic Configuration without SSL
    • 6.3.5.2 Configuration with SSL
  • 6.3.6 Modifying the UIO Apache Proxy Settings
    • 6.3.6.1 UIO_Settings.xml
    • 6.3.6.2 UIO_log4j.xml
    • 6.3.6.3 Application configuration XMLs
• 6.4 Setting Up Rules and User Groups
• 6.5 Setting Up Policies
• 6.6 Configuring the UIO Proxy
  • 6.6.1 Elements of the UIO Proxy Configuration File
    • 6.6.1.1 Components of Interceptors
    • 6.6.1.2 Conditions
    • 6.6.1.3 Filters
    • 6.6.1.4 Filter Examples - ProcessString
    • 6.6.1.5 Filter Examples - FormatString
    • 6.6.1.6 Actions
    • 6.6.1.7 Variables
    • 6.6.1.8 Application
  • 6.6.2 Interception Process
  • 6.6.3 Configuring Redirection to the Oracle Adaptive Access Manager Server Interface
• 6.7 Application Discovery
  • 6.7.1 Application Information
  • 6.7.2 Setting Up the UIO ISA Proxy
  • 6.7.3 Setting Up the UIO Apache Proxy
  • 6.7.4 Scenarios
• 6.8 Samples
  • 6.8.1 Descriptions for Interceptors
  • 6.8.2 Flow for BigBank without UIO Proxy
    • 6.8.2.1 Login
    • 6.8.2.2 Logout
  • 6.8.3 Flow for First-time User to Log In and Log Out of BigBank with UIO Proxy
• 6.9 Upgrading the UIO Apache Proxy
  • 6.9.1 UIO Apache Proxy Patch Installation Instructions
  • 6.9.2 UIO Apache Proxy Patch Backout Instructions
• 6.10 Upgrading the UIO ISA Proxy Server

Part III Customization and Extensions

7 Customizing Oracle Adaptive Access Manager

• 7.1 Overview
• 7.2 Add Customizations Using the OAAM Extensions Shared Library
• 7.3 User-Defined Enumerations

8 Customizing the OAAM Server

• 8.1 Architecture
• 8.2 OAAM Server Settings
• 8.3 Determining Application ID and User Group
  • 8.3.1 Determining the Application ID
  • 8.3.2 Determining Default User Groups
• 8.4 Customizing User Interface Branding
  • 8.4.1 Custom Header / Footer
  • 8.4.2 Custom CSS
  • 8.4.3 Custom Content and Messaging
• 8.5 Configuring Application Properties
  • 8.5.1 Property Extension
  • 8.5.2 User-Defined Enums
  • 8.5.3 Overriding Existing User-Defined Enums
  • 8.5.4 Disabling Elements

9 Customizing User Flow

• 9.1 OAAM Struts/Tiles Framework
• 9.2 Customizing the OAAM Interface Flow and JSP Layout
• 9.3 Customizing Java Server Pages (JSPs)
• 9.4 Overriding Struts Definitions
• 9.5 Interface Page Configuration File
  • 9.5.1 Rendering the Page
  • 9.5.2 tiles-def.xml
• 9.6 Struts Configuration File
  • 9.6.1 Action Path
  • 9.6.2 Action Type
  • 9.6.3 Struts Configuration File

10 Using Virtual Authentication Devices

• 10.1 Terminology
• 10.2 Virtual Authentication Devices and Set of Background Images
• 10.3 Virtual Authentication Types
  • 10.3.1 TextPad
  • 10.3.2 PinPad
  • 10.3.3 QuestionPad
  • 10.3.4 Keypad
• 10.4 Authenticator Composition
• 10.5 Virtual Authentication Device Properties
  • 10.5.1 Property Files Used in the Authenticator's Configuration
  • 10.5.2 TextPad Authenticator Properties
  • 10.5.3 PinPad Authenticator Properties
  • 10.5.4 QuestionPad Authenticator Properties
  • 10.5.5 KeyPad Authenticator Properties
  • 10.5.6 Frame Design and Element Positioning
    • 10.5.6.1 Background Images
    • 10.5.6.2 KeysSets
    • 10.5.6.3 TextPad Visual Elements
    • 10.5.6.4 PinPad Visual Elements
    • 10.5.6.5 QuestionPad Visual Elements
    • 10.5.6.6 KeyPad Visual Elements
  • 10.5.7 Customization Steps
• 10.6 Displaying Virtual Authentication Devices
  • 10.6.1 Setting Up Before Calling the get<pad type> Method
  • 10.6.2 Getting the AuthentiPads
  • 10.6.3 Setting Properties After Getting Authentipad Object
  • 10.6.4 Displaying Virtual Authentication Devices
• 10.7 Enabling Accessible Versions of Authenticators
• 10.8 Localizing Virtual Authentication Device in OAAM 11g
  • 10.8.1 Overview
  • 10.8.2 Example using German Locale

11 Implementing OTP Anywhere

• 11.1 About the Implementation
• 11.2 Concepts and Terms
  • 11.2.1 One Time Password (OTP)
  • 11.2.2 Oracle User Messaging Service (UMS)
  • 11.2.3 Challenge Processor
  • 11.2.4 Challenge Type
• 11.3 Prerequisites
  • 11.3.1 Install SOA Suite
  • 11.3.2 Configure the UMS Driver
    • 11.3.2.1 Email Driver
    • 11.3.2.2 SMPP Driver
• 11.4 OTP Setup Overview
• 11.5 Configuring OTP
  • 11.5.1 Integrating UMS
  • 11.5.2 Enabling OTP Challenge Types
  • 11.5.3 Enabling Registration and User Preferences
• 11.6 Customizing OTP
  • 11.6.1 Customizing Registration Fields and Validations
  • 11.6.2 Customizing Terms and Conditions
  • 11.6.3 Customizing Registration Page Messaging
  • 11.6.4 Customizing Challenge Page Messaging
  • 11.6.5 Customizing OTP Message Text
  • 11.6.6 Enabling Opt Out Functionality
• 11.7 Registering SMS Processor to Perform Work for Challenge Type
• 11.8 Configuring the Challenge Pads Used for Challenge Types
• 11.9 Customizing OTP Anywhere Data Storage
  • 11.9.1 com.bharosa.uio.manager.user.UserDataManagerIntf
  • 11.9.2 Default Implementation - com.bharosa.uio.manager.user.DefaultContactInfoManager
  • 11.9.3 Custom Implementation Recommendations
  • 11.9.4 Configuring Properties
• 11.10 Example Configurations
  • 11.10.1 Additional Registration Field Definitions Examples
    • 11.10.1.1 Email Input
    • 11.10.1.2 Phone Input
    • 11.10.1.3 IM Input
  • 11.10.2 Additional Challenge Message Examples
    • 11.10.2.1 Customize OTP Email Message
    • 11.10.2.2 Customize OTP IM Message
    • 11.10.2.3 Customize OTP Voice Message
  • 11.10.3 Additional Processors Registration Examples
    • 11.10.3.1 Register Email Challenge Processor
    • 11.10.3.2 Register IM Challenge Processor
    • 11.10.3.3 Register Voice Challenge Processor
• 11.11 Challenge Use Case

12 Configurable Actions

• 12.1 Integration
• 12.2 Executing Configurable Actions in a Particular Order and Data Sharing
• 12.3 How to Test Configurable Actions Triggering
• 12.4 Sample JUnit Code

13 Device Registration

14 Extending Device Identification

• 14.1 When to Use Extend Device Identification
• 14.2 Prerequisites
• 14.3 Developing a Custom Device Identification Plug-in
  • 14.3.1 Implement the Client Side Plug-in
  • 14.3.2 Add Properties related to Custom Device Identification Plug-in to OAAM Extensions Shared Library
  • 14.3.3 Extend/Implement the DeviceIdentification Plug-in class
    • 14.3.3.1 getPlugInHTML
  • 14.3.4 getFingerPrint
  • 14.3.5 getDigitalCookie
  • 14.3.6 getClientDataMap
• 14.4 Overview of Interactions
• 14.5 Compile, Assemble and Deploy
• 14.6 Important Note About Implementing the Plug-In

15 Flash Fingerprinting

• 15.1 Device Fingerprinting
• 15.2 Definitions of Variables and Parameters
• 15.3 Option 1
  • 15.3.1 Option 1 Flow
  • 15.3.2 Option 1 Code Example
• 15.4 Option 2
  • 15.4.1 Option 2 Flow
  • 15.4.2 Option 2 Code Example
• 15.5 Option 3
  • 15.5.1 Option 3 Flow
  • 15.5.2 Option 3 Code Example
• 15.6 Common Update

Part IV Authentication and Password Management Integration

16 Access and Password Management Integration

• 16.1 Benefits and Features of the Integration
• 16.2 Secure Password Collection and Management Scenarios

Part V Migration and Lifecycle Management

17 Migrating Native Applications to OAAM 11g

• 17.1 Preparing for Migration
• 17.2 Migrating Native Static Linked (In Proc) Applications to OAAM 11g
  • 17.2.1 Use the OAAM Shared Library Instead of Static Linking to OAAM Jars
  • 17.2.2 Move All Configurable Properties into bharosa_server.properties File
• 17.3 Migrating Native SOAP Applications to OAAM 11g
  • 17.3.1 Use OAAM Shared Library Instead of Static Linking to OAAM Jars
  • 17.3.2 Move All Configurable Properties into the bharosa_server.properties File
  • 17.3.3 Configure SOAP/WebServices Access
• 17.4 Migrating Native Applications that Cannot Use OAAM Shared Library
  • 17.4.1 Use the OAAM 11g Jar Files
  • 17.4.2 Copy the OAAM 11g Property Files
  • 17.4.3 Specify the Configurable Properties in the bharosa_server.properties File

18 Handling Lifecycle Management Changes

• 18.1 Oracle Virtual Directory (OVD) Host, Port, and SSL Enablement Changes
• 18.2 Oracle Identity Manager (OIM) URL Changes
• 18.3 Oracle Access Manager (OAM) Host and Port Changes
• 18.4 Oracle Internet Directory (OID) Host and Port Changes and SSL Enablement
• 18.5 Database Host and Port Changes
• 18.6 Moving Oracle Adaptive Access Manager to a New Production Environment
• 18.7 Moving Oracle Adaptive Access Manager to an Existing Production Environment

Part VI Custom Development

19 Creating OAAM Oracle BI Publisher Reports

• 19.1 Create Oracle BI Publisher Reports on Data in the OAAM Schema
  • 19.1.1 Create a Data Model
  • 19.1.2 Map User Defined Enum Numeric Type Codes to Readable Names
    • 19.1.2.1 Results Display
    • 19.1.2.2 English Only User Defined Enum Result Display
    • 19.1.2.3 Internationalized User Defined Enum Result Display
  • 19.1.3 Adding Lists of Values
    • 19.1.3.1 User Defined Enums as List of Values for Filtering, English Only
    • 19.1.3.2 User Defined Enums as List of Values for Filtering, Internalized
  • 19.1.4 Adding Geolocation Data
  • 19.1.5 Adding Sessions and Alerts
    • 19.1.5.1 Type Code Lookups
  • 19.1.6 Example
  • 19.1.7 Adding Layouts to the Report Definition
• 19.2 Building OAAM Transactions Reports
  • 19.2.1 Get Entities and Transactions Information
  • 19.2.2 Discover Entity Data Mapping Information
    • 19.2.2.1 Information about Data Types
    • 19.2.2.2 Discover Entity Data Details Like Data Type, Row and Column Mappings
    • 19.2.2.3 Build Entity Data SQL Queries and Views
  • 19.2.3 Discover Transaction Data Mapping Information
    • 19.2.3.1 Discover Transaction data details like Data Type, Row and Column mappings
    • 19.2.3.2 Build Transaction Data SQL Queries and Views
  • 19.2.4 Build Reports
    • 19.2.4.1 Building Entity Data Reports
    • 19.2.4.2 Building Transaction Data Reports
    • 19.2.4.3 Joining Entity Data Tables and Transaction data tables

20 Developing Custom Challenge Processors

• 20.1 What are Challenge Processors
• 20.2 Code Challenge Processors
  • 20.2.1 Class
  • 20.2.2 Methods
  • 20.2.3 Example: Email Challenge Processor Implementation
  • 20.2.4 Secret (PIN) Implementation
• 20.3 Define the Delivery Channel Types for the Challenge Processors
  • 20.3.1 Challenge Type Enum
  • 20.3.2 Example: Defining an OTP Channel Type
• 20.4 Configure User Input Properties
  • 20.4.1 Enable Registration and Preferences Input
  • 20.4.2 Set Contact Information Inputs
• 20.5 Configure the Challenge Pads Used for Challenge Types

21 Creating a View of a Non-OAAM Database

• 21.1 The OAAM_LOAD_DATA_VIEW
• 21.2 Schema Examples
  • 21.2.1 OAAM Schema
  • 21.2.2 Custom Schema Example

22 Developing a Custom Loader for OAAM Offline

• 22.1 Base Framework
  • 22.1.1 Overview
  • 22.1.2 Important Classes
  • 22.1.3 General Framework Execution
• 22.2 Default Implementation
  • 22.2.1 Default Load Implementation
  • 22.2.2 Default Playback Implementation
• 22.3 Implementation Details: Overriding the Loader or Playback Behavior
• 22.4 Implement RiskAnalyzerDataSource
  • 22.4.1 Extending AbstractJDBCRiskAnalyzerDataSource
  • 22.4.2 Extending AbstractTextFileAnalyzerDataSource
  • 22.4.3 Extending AbstractRiskAnalyzerDataSource
• 22.5 Implement RunMode
  • 22.5.1 Extending AbstractLoadLoginsRunMode
  • 22.5.2 Extending AbstractLoadTransactionsRunMode
  • 22.5.3 Extending PlaybackRunMode

Part VII Troubleshooting

23 FAQ/Troubleshooting

• 23.1 Techniques for Solving Complex Problems
  • 23.1.1 Simple Techniques
  • 23.1.2 Divide and Conquer
  • 23.1.3 Rigorous Analysis
  • 23.1.4 Process Flow of Analysis
    • 23.1.4.1 State the Problem
    • 23.1.4.2 Specify the Problem
    • 23.1.4.3 What It Never Worked
    • 23.1.4.4 IS and IS NOT but COULD BE
    • 23.1.4.5 Develop Possible Causes
    • 23.1.4.6 Test Each Candidate Cause Against the Specification
    • 23.1.4.7 Confirm the Cause
    • 23.1.4.8 Failures
• 23.2 Troubleshooting Tools
• 23.3 OAAM UIO Proxy
• 23.4 Knowledge-Based Authentication
• 23.5 Virtual Authentication Devices
• 23.6 Configurable Actions
• 23.7 One-Time Password
• 23.8 Localization
• 23.9 Man-in-the-Middle/Man-in-the-Browser
• 23.10 Failure Counter

Part VIII Glossary

Glossary

Index