29 FAQ/Troubleshooting

This chapter provides troubleshooting tips and answers to frequently asked questions. It contains the following sections:

29.1 Using My Oracle Support for Additional Troubleshooting Information

You can use My Oracle Support (formerly MetaLink) to help resolve Oracle Fusion Middleware problems. My Oracle Support contains several useful troubleshooting resources, such as:

  • Knowledge base articles

  • Community forums and discussions

  • Patches and upgrades

  • Certification information


You can also use My Oracle Support to log a service request.

You can access My Oracle Support at https://support.oracle.com.

29.2 Techniques for Solving Complex Problems

This section describe a process to enable you to more easily solve a complex problem. It contains the following topics:

29.2.1 Simple Techniques

You can work your way through some simple troubleshooting techniques to try to solve a problem.

Steps Description
Experience You have seen this problem before or it is simply something you know the answer to.
Post to the Forum This is not the first step. Only valid once basics have been applied and a second opinion is needed. Appropriate during rigorous analysis, but not before.
Intuitive leap (or guess) The problem just inspires a guess at a cause. You have a feel for the problem or rather its cause. This can be very effective and result in a quick resolution, but without proper confirmation, it often leads to the symptom being fixed and not the real cause being resolved.
Review basic diagnostics Check the logs for errors and the flow. Check flow (HTTP headers, network packet trace, SQL trace, strace). Run through and document the flow. Cross check with configuration details to ensure flow is expected.
Read the error message Reading the error and the flow information will give a big clue. Taken with some knowledge of the way the component works, this can give a lot of insight. Always check knowledge (Oracle and search engine) for matches. Perform any diagnostics needed to establish if the error is key. With multiple errors, look to see which is likely the cause and which are just consequences.
Compare Compare the logs and flows with a working system. Perform a test case. If it occurs only at a certain site, then compare the differences.
Divide Break the problem down

29.2.2 Divide and Conquer

Steps to reduce the problem to a manageable issue are listed in this section.

Process Description
Simplify the problem Make a problem as simple as possible.
Remove components that are not needed Most problems involve complex components and connections between them. Most involve third party components. So where ever possible, eliminate third party components first and then as many components and custom components as possible (for example, command line not application, SQLPLUS is not an application.)
Reduce complexity Test to see if a simpler version of the problem exists with the same symptoms. (for example, remove components of a complex Select, or a search filter, check if a single request or few requests will suffice).
Like fixing an underground pipe with a leak Imagine a complex configuration as being a underground hose pipe with a leak. You know something is wrong, there is a leak someplace, but not where it is.
List the components Draw a box for each components and a line where it is connected to the next. Note the protocols used to join them.
Check both ends What goes in should come out the same. If you see data in and out results in a problem then it is one of the ends that is wrong. If the flow is not as expected the problem is in between.
Lazy Y Test points in the configuration to find where the deviation occurs. Once established (beyond doubt) that a piece of the configuration behaves as expected it can be ignored.
Repeat Repeat this loop to close in on the problem
Help When 3rd party components are involved in the issue, get help from the others and work on the issue together.

29.2.3 Rigorous Analysis

All or part of the process should be applied if:

  • a problem is complex

  • a problem is highly escalated

  • a problem was not solved with the first attempts

  • a problem is getting out of control

  • a problem has potential for getting out of control

29.2.4 Process Flow of Analysis

The process flow of analysis is presented as follows:

  1. State the problem.

  2. Specify the problem.

    Develop possible causes from:

    1. Knowledge and experience

    2. Distinctions and changes

  3. Test possible causes against the specification.

  4. Determine most probable cause.

  5. Verify the solution. State the Problem

Stating the problem is the most important step to solving the issue.

Step Description
Ensure a clear and concise problem statement Stating the problem is the most important step. It is the most commonly ignored or at least the problem statement is assumed. It is pointless trying to solve a problem until the problem statement is stated. Otherwise what are you actually trying to fix? If you do not know what it is you are fixing how can you fix it?
Consider if the problem stated can be explained If so, then it is not the problem statement --If the problem statement can be explained then back up and try and get a more correct problem statement. This is a case to start communicating if you are helping someone solve his problem. Either ask some direct questions to narrow down the issue or just pick up the telephone and talk to the person to clarify the real issue. If there are lots of issues then start noting them down as separate issues.
Do not settle for a vague statement Vague problem statements, like "bad performance", "something crashes" are of no use and commonly are the cause for issues to be long running and out of control.
Never combine problems in a single statement Ensure there is only one problem being dealt with. Do not accept combined problems. The combined problem is either multiple distinct problems or some of the problems are actually symptoms. Specify the Problem

Describe problems in detail and ask focused questions to gather pertinent information.

Step Description
Specify the problem These are symptoms of the problem.
Start by asking questions Ask questions such as What, Where, When, and to what Extent?
What? What tends to be the obvious question and is mostly a list of facts and symptoms; what deviated from the expectation?
Where? Where may or may not be relevant, but is worth asking as it is often significant and often overlooked.
When When is very important as time lines helps identify patterns and establish what change triggered the problem.
Extent Extent or how many is particularly useful in establishing probable causes. If it is all the systems for example then check if it affects all systems or try a testcase. How often is also important. Once a week is quite different from many times every second and tells us much about the type of issue to look for.
List the symptoms and facts List the symptoms and facts and how they are significant
What changed? Something changed that is certain unless the problem has always been there. This is a special case.
Assumptions Verify the data provided and check for conflicts and contradictions.

Always check for any assumptions. Be careful to identify any information that is not verified and thus is only assumed. In fact this is particularly a mistake made by analysts that have more technical experience. Though also occurs a lot when inexperienced analysts are given details from people they perceive as having more knowledge. However trivial an assumption seems, always look for proof and confirmation. What It Never Worked

If the component did not work before, performing these steps:

Considerations Description
Consider behavior and expectation if performance issue For cases when the issue is about something that never worked correctly the first issue is to establish what correct behavior really is and if it is reasonable? This also allows us to set proper expectations from the outset. This is especially true for performance issues.
Confirm that there is no misunderstanding Establish that the requirement is reasonable.
Do not compare Apples with Oranges Agree on a specific goal. Focus on that issue only.
Consider all components involved Consider all components involved:
  • Not just the software

  • Hardware is fast enough?

Consider if the solutions is just to change perception What can you see that causes you to think there's a problem?
  • Human factors

  • Perception IS and IS NOT but COULD BE

Consider what the problem is, what it is not, and what it could be.

Step Description
IS and IS NOT but COULD BE For every fact or symptom ask this question: IS and IS NOT but COULD BE
Provide comparison A test case often is the key to establishing something to compare the problem with.

If it reproduces the issue then it does not help the problem analysis as such, but it is extremely useful when passing the problem to the next team to work on the fix. It also allows quicker testing of potential fixes and solutions (workarounds), not to mention you would be gaining experience.

If there is no comparison, create a test case If it does not reproduce then it provides something to compare the problem system with and perhaps even a possible work around. Develop Possible Causes

Problem solving involves developing possible causes.

Development Description
Knowledge and experience You can use your knowledge and experience to recognize possible causes
  • Seen before

  • Seen it in the documentation

  • Support note or through search engine

Distinctions and changes You can make a list of distinctions and changes to narrow down causes:
  • Only at this site or on one platform

  • Just after upgrade

  • When load increased

  • Only on Thursdays

Examine each of the symptoms and comparisons Consider each of the facts and ensure that they are relevant and that they are not conflicting Test Each Candidate Cause Against the Specification

Test each candidate cause against the specification:

  • Each possible cause must fit all the items in the specification

  • If you end up with no causes then go back and refine the process

  • Causes must explain both the IS and the IS not but COULD be

  • Determine the most probable cause

  • Do not discount any causes that fit Confirm the Cause

Confirm the cause so that you can devise an action plan.

You can:

  • Devise ways to test the possible causes

  • Observe

  • Test assumptions

  • Experiment

  • Test solution and monitor

The main point is to devise action plans to prove or disprove the theories. It is important to communicate the reason for each action plan. Especially when asking for a negative test, that is, a test that is to prove something is not true. People might assume all action plans are attempts to solve the problem and resist any thing they think is not directed in the direction. Failures

When one solution fails, just start back at the beginning and apply the approach once again, updated with the new results. Really complex problems will often take several iterations.

The process is not infallible.

Main causes of failure are:

  • Poor or incorrect problem statement

  • Inaccurate or vague information

  • Missing the key distinctions in IS vs. IS NOT

  • Allowing assumptions to distort judgment

  • Not involving a broader set of skills

29.3 Troubleshooting Tools

This section contains information about tools and processes you can use to investigate and troubleshoot issues with your system.

Table 29-1 lists the general and OAAM-specific tools you can use for troubleshooting problems.

Table 29-1 Troubleshooting Tools

Category Description

General Tools

  • Oracle Enterprise Manager Fusion Middleware Control

  • Database Enterprise Manager

  • Monitor Data in DMS

  • Audit Data

  • Ping/Network Check Tools

OAAM Specific Tools

  • Dashboard

  • Monitor Data

  • Log files

Table 29-2 provides items to check for when troubleshooting the system.

Table 29-2 Troubleshooting Tips

Tips Reason

Check the operating system

Some issues may be platform specific. For example, Java keystores created on non-IBM platforms will not work on IBM platforms

Check WebLogic Server version

Make sure OAAM is installed on a WebLogic Server certified for 11g

Check the JDK (Sun or JRockit)

Make sure the JDK is certified for the Identity Management 11g Suite

Change logging configuration through Oracle Enterprise Manager Fusion Middleware Control

Make sure the log level is changed appropriately before tracing and debugging

Search for log messages through Oracle Enterprise Manager Fusion Middleware Control

Log messages record information you deem useful or important to know about how a script executes.

Use the Execution Context ID to search for log messages

The ECID is a unique identifier used to correlate individual events as being part of the same request execution flow.

Use the Oracle WebLogic Administration Console to monitor database connection pool

Check the health of the connection pool through the Oracle WebLogic Administration Console.

Table 29-3 summarizes problems and the checks you can perform to troubleshoot and solve the problem.

Table 29-3 Problems and Tips

Problem Checks You Can Perform

Common Troubleshooting Use Cases

  • Most of the operations are slow

  • Server is throwing out of memory exceptions

  • Server is throwing encryption related exceptions

  • Connection pool related errors occur when starting the server

  • Errors while starting managed servers after upgrade from to 11.1.2

  • OAAM CLI script issues

  • SOAP call issues

  • Native integration issues

Most of the Operations are Slow

  • Check performance of OAAM policies

    Use the dashboard to see the performance of the rules

    Tune rules or their parameters if necessary

  • Check the database using Oracle Enterprise Manager Fusion Middleware Control and see if there are any queries that are slow. Follow recommendation for adding suggested indexes in Oracle Fusion Middleware Performance and Tuning Guide.

  • Check if the application server CPU is high

    Take a thread dump if possible

  • Check the connectivity and network speed between application server and database

  • Use the IP of the database machine in data source settings

Server is Throwing Out of Memory Exceptions

  • Check the configuration of the OAAM's WebLogic Server domain

  • See if all the OAAM web applications are deployed on the same managed servers

  • Increase the heap size of the managed server

Connection Pool Errors

  • Make sure the database listener is running

  • Use IP address rather than name in JDBC URL

  • Make sure the database service name is correct

  • Make sure the connection pool is not too "large"

    Check if there are too many managed servers accessing the same database

Errors While Starting the Managed Server After Upgrade

  • Make sure encryption keys are properly copied

  • Make sure all manual steps are followed that are in the upgrade documentation

  • Check the Oracle WebLogic Administration Console and make sure all web applications are targeted properly to their managed servers

OAAM CLI Script Issues

  • Make sure the JAVA_HOME environment variable is set to the JDK certified for the Identity Management Suite for 11g

  • Make sure CLI related properties are set in the oaam_cli.properties file.

SOAP Call Issues

  • Known issues exist with time-outs in SOAPGenericImpl

  • Oracle Web Services Manager (OWSM) is enabled by default, so you must set the OWSM policy before using SOAP

  • Make sure the SOAP server URL including the port number is valid

Native Integration Issues

  • Make sure the appropriate version of the OAAM Extensions Shared Library is used (the WAR file should use the WAR file version and EAR file should use the EAR file version

  • Make sure the OAAM data source is created and the JNDI name is correct (it should match the JNDI name of the OAAM Server)

  • Make sure the native application is using the same keys that are used by the OAAM Admin and OAAM server

  • Issues with the encryption keys

    Make sure all the managed servers are on the same WebLogic Server domain or copy the keys across the domains

    If using non-11g servers, use the Java keystores

  • Shared library usage by many applications on the same server

    Currently the OAAM Extensions Shared Library cannot be used by more than one application on the same managed server

29.4 Configurable Actions

Moving Configurable Action from testing environment to a production environment

Question/Problem: I defined a custom configurable action in the test environment and now I want to move the custom action template from test and to production.

Answer/Solution: To do this:

  1. Use the Oracle Adaptive Access Manager extensions shared library to package the JAR file.

  2. Add the JAR file to "oaam-extensions\WEB-INF\lib" folder.

  3. Repackage oracle.oaam.extensions.war.

  4. Deploy the JAR file.

For detailed instructions, see Chapter 7, "Using the OAAM Extensions Shared Library to Customize OAAM."

29.5 Device Fingerprinting

Stale Cookies

Question/Problem: How will OAAM behave in Flash cookie and secure cookie stale scenarios?

Answer/Solution: See Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

  • What if persistent cookies are disabled?

    Oracle Adaptive Access Manager uses different pieces of information about a machine to develop the "device fingerprint". If persistent cookies are disabled, Oracle Adaptive Access Manager still has other information to use in identifying the machine.

    Each feature standing on its own is not sufficient to secure the session; it is the combination of device fingerprint, IP, location, time, behavioral analysis, behavioral analysis as it relates to past behavior, and others.

  • What if secure cookies are deleted?

    Oracle Adaptive Access Manager's fingerprinting technology does not solely rely on one element. Oracle Adaptive Access Manager uses dozens of attributes to recognize and "fingerprint" the device you typically use to login, providing greater "coverage" for an institution's customer base. If secure cookies are missing or disabled, Oracle Adaptive Access Manager uses other elements such as Flash object and HTTP headers for device identification.

  • What if Flash is not enabled?

    Oracle Adaptive Access Manager's fingerprinting technology does not solely rely on one element. Oracle Adaptive Access Manager uses dozens of attributes to recognize and "fingerprint" the device you typically use to login, providing greater "coverage" for an institution's customer base. If Flash is not enabled, Oracle Adaptive Access Manager uses other elements such as secure cookie and HTTP headers for device identification.

29.6 Device Registration

Device Registration

Question/Problem: The user has an option in the challenge questions registration page to register a device:

"Check to register the device that you are currently using as a safe device"

If he skipped during the registration flow, he does not seem to have an option later on from the user preferences page. Is there a way to turn it on?

Answer/Solution: Device registration is set up to ask the user to register the device during registration and when being challenged.

You can turn it on in the register questions page of user preferences by setting:


Currently the central user preferences page only enables for unregistering devices.

The user can register the device during registration, but he is also given the option to register the device when being challenged.

Question/Problem: The registration of devices does not appear in the registration flow. Device ID policies have been imported into OAAM Admin.

Answer/Solution: Device registration is not enabled by default. To enable device registration, bharosa.uio.default.registerdevice.enabled should be set to true.

29.7 Failure Counter

For the auto failure counter increment to work, Client Type for updateAuthStatus must be set to 9 (Question/Answer).

29.8 Knowledge-Based Authentication

Prompt a User with Two Challenge Questions

Question/Problem: I would like to prompt a user with two challenge questions when they attempt to logon from a new device. How can this be achieved given that the questions are randomly picked, raising the possibility that the same question may be displayed twice?

Answer/Solution: The OAAM "one question at a time" flow is by design. It is better security practice to present one question and only show the next question once the user has successfully answered the challenge. This protects the questions from being harvested for use in a phishing exercise. As well, OAAM allows users to have multiple attempts at a question which entails keeping track of how many wrong answers they have entered. If there were more than one question displayed at a time it would be difficult to maintain and possibly confusing to end users. To challenge a user with more than one question you should do so by presenting them in separate sequential screens. OAAM does not support authentication of more than one question at a time.

29.9 Localization

Customize and localize the virtual devices

Question/Problem: Can I make customizations and localize the virtual authentication devices?

Answer/Solution: The virtual authentication devices are provided as "samples" to use if you choose to. These samples are provided in English only. Source art and documentation are provided to allow you to develop your own custom virtual authentication device frames, keys, personalization images and phrases. Localization is included in these customizations. Custom development is not supported. Localization of the KeyPad may have issues since not all languages have the same number of characters. Portuguese for example has special characters not found in English. The key layout may be a bit different when these character keys are added. When adding keys to the layout it is vital that there is still enough free space around the keys to allow the "jitter" to function. General best practice is a space at least as large as a single key all the way around the bank of keys when they are positioned in the center of the jitter area. The source art contains notes with the pixel sizes for this area.

Alteration of these samples is considered custom development.

The "Pad" frame and key images

The frame and key samples are provided in English only. Master files for the virtual authentication device frames and keys along with descriptions of the parts are provided on request. You may create your own custom frame and key images and deploy them using product documentation. Any and all alterations to these images or the properties that correspond to them are considered custom development. Some issues to be careful of are text, hot spot, and key sizes. It is not recommended that these be made smaller than the provided samples.

Background images and phrase text

A set of sample images are shipped with Oracle Adaptive Access Manager. These images are for use in the virtual authentication devices only. For security reasons they should never be available to end users outside the context of the virtual authentication devices. The content, file sizes, and other attributes were optimized for a broad range of user populations and fast download speed. The sample phrase text for each supported language is provided with the package. Any and all alterations to these images or text is considered custom development. If the images are to be edited, make sure not to increase the physical dimensions or change the aspect ratio of the sample images because distortions will occur. Also, there must be an identically named version of each image for each virtual authentication device used in your deployment.

Images displayed during registration

Question/Problem: The images displayed in the page before user registration appear in English instead of the locale language.

A non-globalized VAD image is shown.

Answer/Solution: Globalized virtual authentication device image files including the authentication registration flows are not provided. The deployment team develop these.

29.10 Man-in-the-Middle/Man-in-the-Browser

Question/Problem: I use mobile transaction authentication number to sign each transaction using an OTP through SMS. SMS costs are high. How can Oracle Adaptive Access Manager help? In addition, I want a solution that protects against Man-in-the-Middle (MiTM)/Man-in-the-Browser (MiTB) attacks.


  1. Use Oracle Adaptive Access Manager to assess risk and base the use of secondary authentication such as mTAN on risk. Then, SMS can be sent for transactions that are medium to high risk instead of all transactions.

  2. One of the best ways to protect against MiTM and MiTB is to perform transactional risk analysis. For example, verify if the target account has ever been used by this user before or if the user has ever performed a transfer over set dollar amount thresholds. To perform transactional analysis in real-time today requires native integration with the Web application.

  3. Use PinPad to input the target account number. This ensures that the account number entered by the user cannot be easily changed in a session hijacking situation. The account number is not sent over the wire and cannot be easily altered by a MiTM/MiTB.

  4. It is recommended that KeyPad and PinPad virtual authentication devices always be used over HTTPS. The virtual authentication devices send the one time random data generated on the end-user's machine (mouse click coordinates) to the server to be decoded and HTTPS provides the traditional encryption in addition. No client software or logic resides on the end-user's machine to be compromised.

  5. With Oracle Adaptive Access Manager extremely high risk transfers can be blocked all together. Blocking high risk transfers reduces the fraud regardless of the authentication methods used.

29.11 One-Time Password

Are numeric/alphanumeric and pluggable random algorithms supported?

Question/Problem: Are numeric/alphanumeric and pluggable random algorithms supported in OTP?

Answer/Solution: OTP is configurable with a set of two properties:

bharosa.uio.default.otp.generate.code.length = 5
bharosa.uio.default.otp.generate.code.characters = 1234567890

The pin generation method is in the base class (AbstractOTPChallengeProcessor), allowing integrators to override the generateCode method.

29.12 OAAM UIO Proxy


To troubleshoot the OAAM UIO Proxy Web publishing issues:

  • Ensure that the .NET2.0 framework is installed and enabled to successfully register the Bharosa Proxy DLL.

  • IP exceptions are defined for trusted IPs (like Router IP) when flood mitigation settings are enabled to mitigate flood attacks and worm propagation.

  • Ensure that the default inbound and outbound rules allow HTTP/HTTPS traffic to be forwarded to/from OAAM Server.

  • Check the order (precedence) of the rules to ensure that the default rule, deny, is not at a higher order; otherwise, it blocks all rules. If the rule is last in precedence, all rules are executed.

  • In the OAAM Server rule you must ensure that:

    • The external IP/name is mapped to the internal IP/name

    • The external port is mapped to the internal port where OAAM Server is listening

    • The /OAAM Server path is published

To troubleshoot problems experienced while configuring the UIO Proxy, enable tracing to a file and set the trace level to 0x8008f. Doing so will print detailed interceptor evaluation and execution information to the log file.

UIO Apache Proxy

Tips to troubleshoot problems with the UIO Apache Proxy are listed in this section.

  • On launching httpd, an error for loading mod_uio.so occurs. Ensure that mod_uio.so and all the libraries are placed in the proper directories. On Linux, use the ldd command to confirm that mod_uio.so can load all the dynamic libraries that it depends upon. On Windows, use Dependency Walker to find out any missing DLLs and in some cases, you may have to install the Microsoft Visual C++ 2005 Redistributable Package from the Microsoft website, if your server does not have these libraries pre-installed.

  • If nothing is working- no logs and so on, ensure that the user of httpd has permissions to read the uio directory. Typically httpd is run as a daemon user. Ensure the daemon user has write permissions for the logs directory.

  • In case of a parsing error in UIO_Settings.xml or any configuration XML, an error log will be created in httpd's logs directory with the name UIO_Settings.xml.log.

  • For errors, look in uio.log. Use log level of error for production use; info for more details; debug for debugging issues and trace for verbose logs.

  • Ensure that the config XML and settings XML are conforming to the RNG database schema. You can use the UIO_Settings.rng and UIO_Config.rng in any XML editor to edit the UIO_Settings.xml and application configuration XML files.

  • You can change the Apache httpd log level to debug for testing, or keep it at info to reduce log file size. The Apache httpd log is separate from UIO Apache Proxy log.

  • When migrating ISA configuration XML to be used with the UIO Apache Proxy, you must do the following:

    1. Change the header of the XML file to use

      <?xml version="1.0" encoding="utf-8"?><BharosaProxyConfig xmlns="http://bharosa.com/">
    2. Run your config XML file through libxml2's xmllint utility.

      For Windows, download the latest libxml2-2.x.x.win32.zip file from


      and unzip it.

      For Linux, if you have libxml2 installed then xmllint command should be available, or check with your Linux System Administrator.

      Copy the UIO_Config.rng file from the UIO Apache Proxy distribution and run following command:

      xmllint --noout --relaxng UIO_Config.rng your_config_xml_file

      And fix any errors that are reported.

  • The UIO Apache Proxy is not working or intercepting request.

    Problem: The following error appears:

    Failed to create session in memcached, err = 70015(Could not find specified
    socket in poll list.) proxy - Failed to create session, cannot process this
    request distsessions - memcache server localhost create failed 111 

    Possible Solutions:

    • Make sure "memcache" is installed and configured.

    • Make sure "memcache" process is up and running before creating the session.

Oracle Adaptive Access Manager Debug Mode

In debug mode, the value of any variable--user name, password, and any other information--is not displayed. In capture mode, the HTTP traffic is shown. Therefore, capture mode is not recommended in production.

In-Session/Transaction Analysis

The UIO Proxy is a solution for login security only. It does not support in-session capabilities. Options are provided below based on possible requirements:

  • If you are using a packaged application you do not have access to alter/integrate with, the UIO Proxy or Oracle Access Management Access Manager are options for real-time/in-line use cases like anti-malware, anti-phishing, risk-based authentication in the login flow.

  • If you have the ability to integrate with the application and require in-session/transactional use cases, then consider native integration. This is the most flexible option for this case.

  • If you want in-session/transactional use cases but do not have the ability to integrate with the application, a custom option could potentially be possible using either Oracle Adaptive Access Manager offline 10g or Oracle Adaptive Access Manager with a listener.

No Changes in Proxy in 11g

Question/Problem: Are there changes between 10g and 11g for the UIO Proxy?

Answer/Solution: There has been no changes in the proxy between 10g and 11g. There is no dependency on OHS. The user has to use Apache 2.2.8 only.

Adding appid to HTTP Headers

Question/Problem: In TestConfig.xml, should I be adding appid to HTTP headers for both the PSFT URLs and the /asa/ URLS?

Answer/Solution: No, just to the /asa/ URLs. It should be adding the app-id to only the /asa/ URLs, not needed for PSFT urls.

Contains Match

Question/Problem: Should a condition with "contains" match if there is an exact match?

Answer/Solution: Yes.

Request URL

Question/Problem: Can request URL be a partial URL? (Such as just first part of URL?)

Answer/Solution: No, URL must be an exact match and query parameters, such as anything after a "?" are not considered part of the URL, so they would have to be trapped with a condition, and not included as part of the URL.

29.13 Virtual Authentication Devices

Tips and troubleshooting steps for OAAM 11g customization capability

These are the guidelines in Chapter 8, "Customizing OAAM Web Application Pages."

Question/Problem: I am trying to use the registerQuestionHTML instead of registerQuestion by putting the following entry in the property file. I had tried put it in both oaam_custom.properties and client_resource.properties file and I do not see it is taking the value. bharosa.uio.default.RegisterQuestions.authenticator.device = DeviceHTMLControl bharosa.uio.default.ChallengeQuestion.authenticator.device=DeviceHTMLControl

Answer/Solution: The properties mentioned are only used if the AuthentiPad checkpoint is turned off, as mentioned in the property file. The property for authentipad checkpoint is bharosa.uio.default.use.authentipad.checkpoint=true. Alternatively (and recommended) would be to modify the policies in the authentipad checkpoint to have the desired device outcome for the page.

Tip: All user displayed strings should be customized in client_resource.properties or its locale specific variations (example: client_resource_es.properties)

Tip: Place custom user interface strings to WEB-INF/classes/client_resource.properties. Place custom frame file image to WEB-INF/classes/bharosa_properties/pad_images (because it has to be on classpath). Place frame file property to WEB-INF/classes/client_resource.properties and update the value for frame file, for example: "pad_images/authenticator_pad.png")

Tip: Custom JSPs cache issue: Oracle Weblogic seems to cache the custom JSP, so once the WAR file has been deployed with the JSP it is hard to see any additional changes to it. Some workarounds to get around this that are tested are by changing the file name (and property value) or by clearing the deployment directories used by Oracle Weblogic. ("DefaultDomain/servers/DefaultServer/tmp" and/or "o.j2ee/drs").

Disabling OAAM Authentication Pad

Question: Is there a way to disable OAAM authentipad when custom extensions war files are used?

For OAAM Server there are 2 options:

  • Modify the authentipad policy to always return "OAAM HTML Pad".

  • Set the following properties in OAAM Server:


Another alternative is that as of 11.1.2 the login page can be consolidated to one page with the following properties:


To effect challenges, you need to perform one of the two options above.

Accessible Versions of the Virtual Authentication Devices

Question/Problem: Users who access using assistive techniques need to use the accessible versions of the virtual authentication devices. How do I enable these versions?

Answer/Solution: Accessible versions of the TextPad, QuestionPad, KeyPad and PinPad are not enabled by default. If accessible versions are needed in a deployment, they can be enabled using the Properties Editor in OAAM Admin or using the Oracle Adaptive Access Manager extensions shared library.

The accessible versions of the virtual authentication devices contain tabbing, directions and ALT text necessary for navigation through the screen reader and other assistive technologies.

You will need to modify oaam_custom.properties.

To enable these versions, set the "is ADA compliant" flag to true.

For native integration the property to control the virtual authentication device is


For Oracle Adaptive Access Manager out-of-the-box, the property to control the virtual authentication device is


Visible Text Input or Password (Non-Visible) Input Setting

Question/Problem: How can I configure QuestionPad so that challenge answers can be enter as non-visible text?

Answer/Solution: Add the following property to oaam_custom.properties. This property determines whether the QuestionPad is set for visible text input or password (non-visible) input.


Valid values are text and password.

Can OAAM Restrict the Number of Devices used by a User

Question/Problem: Is there any way to configure the limit for a user to use fewer number of devices, such as 5 or 6 and block any access from the devices which are not in the configured list for specific user?

Answer/Solution: For usability and security reasons OAAM does not support limiting a user to a set number of devices. As well, this behavior is not required for proper security coverage since OAAM profiles the behavior of users including the devices they use. The total number of devices is not a good measure of risk as some end users may utilize many devices as part of their normal behavior. Instead OAAM keeps track of how often a user utilizes a specific device, who else has used that same device in the past and with what frequency. These evaluations can better assess the level of risk associated with an access request.

KeyPad or PinPad for KBA challenges?

Question/Problem: Can I use KeyPad or PinPad for KBA challenges?

Answer/Solution: KBA is designed for use with QuestionPad or plain HTML. Using KeyPad or PinPad is not recommended because KBA questions are not presented in that scenario.

How can the virtual authentication devices protect users from screen capture malware?

Question/Problem: How can virtual authentication devices protect users from screen capture malware?

Answer/Solution: These attacks currently require a manual process. An individual must look at the video or images captured to figure out the PIN or password. The virtual devices are primarily aimed at preventing automated attacks that affect large numbers of customers. If the Trojan did include OCR technology, finding the characters clicked on KeyPad and PinPad would be more difficult to read than other types of on-screen keyboards since Oracle Adaptive Access Manager keys are translucent so that background image can be seen and the font and key shapes can be randomized each session.

Also, the jitter would complicate the task. The virtual authentication devices are a good mix of security and usability for large scale deployments that want to keep the authentication already used and layer more security on top of it. Even if there were malware developed that is capable of deciphering the password, it does not necessarily cause fraud to occur. The virtual authentication devices are only one component of the full solution. Even if a fraudster has the PIN or password, the fraudster will have to pass the real-time behavioral/event/transactional analysis and secondary authentication. Oracle Adaptive Access Manager tracks, profiles and evaluates users/devices/locations activity in real-time regardless of authentication. Oracle Adaptive Access Manager takes proactive action to prevent fraud when it detects high risk situations. In this way, fraud could be prevented even if the standard form of authentication (password/PIN or another form.) is removed from the applications

Developing Custom Background Images

To develop custom background images for the virtual authentication devices the following must performed:

  1. Process images to correct resolution for each pad being used.

  2. Next you must add the images to correct directories for each virtual authentication device. TextPad images should be in the TextPad directory, and so on. The directory will be in the form bharosa.image.dirlist= {oracle.oaam.home}/oaam_images. This will resolve to "/scratch/user/Oracle/Middleware/Oracle_IDM1/oaam/oaam_images". In this directory there are three sub-directories named keypad, questionpad and textpad.

Disabling Date And Time Stamp Displayed In The Authentipad Image In .Net

  1. To disable date and time stamp, comment out:

    CreateAuthentiPad API
    AuthPad.TimeStampText = DateTime.Now.ToString();
    CreateQuestionPad API
    TimeStampText = DateTime.Now.ToString();
  2. To display Timestamp

    Example 1 (displays user defined string):

    ret.AuthPad.TimeStampText = "monster";
    ret.TimeStampText = "muppet";

    Example 2 (displays current time):

    AuthPad.TimeStampText = DateTime.Now.ToString();
    TimeStampText = DateTime.Now.ToString();

Changing the Limit of Characters for Passwords

To change the character limit for passwords entered in to OAAM server, update the value for the following property in the oaam_cli.properties file:


For existing Access Manager and OAAM integration deployments, the value for the property can be updated using the OAAM Administration Console or shared library.

KeyPad Troubleshooting

Question/Problem: I am having trouble with KeyPad. How should I troubleshoot the problem?

Answer/Solution: Refer to the following list:

KeyPad does not display.

  • Check the property in to oaam_custom.properties:

  • Make certain that the client application is pointing to the correct server application.

Buttons stop jittering.

  • Someone has changed the KeyPad settings. Check with your server personnel regarding property modifications they may have made.

Same image displayed to all users.

  • Check the properties file to ensure that the backgrounds folder setting is correct.

No image displayed in pad background.

  • User may have images disabled in the browser.

  • Users image may have been deleted from the backgrounds folder.

  • Check the properties file to ensure that the backgrounds folder setting is correct.

  • Check that the system is configured to assign images for personalization.