Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
11g Release 1 (11.1.1)

Part Number E15480-08
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
PDF · Mobi · ePub

23 FAQ/Troubleshooting

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

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

23.1.1 Simple Techniques

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

Steps Description


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 together 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 the logs and flows with a working system. Perform a test case. If it happens only at a certain site, then compare the differences.


Break the problem down

23.1.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 this loop to close in on the problem


When 3rd party components are involved in the issue, get help from the others and work on the issue together.

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

23.1.4 Process Flow of Analysis

The process flow of analysis is presented below:

  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 tends to be the obvious question and is mostly a list of facts and symptoms; what deviated from the expectation?


Where may or may not be relevant, but is worth asking as it is often significant and often overlooked.


When is very important as time lines helps identify patterns and establish what change triggered the problem.


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.


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 isn't, and what it could be.

Step Description


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 here 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, i.e. 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

23.2 Troubleshooting Tools

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

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

Table 23-1 Troubleshooting Tools

Category Description

General Tools

  • Middleware Enterprise Manager

  • Database Enterprise Manager

  • Monitor Data in DMS

  • Audit Data

  • Ping/Network Check Tools

OAAM Specific Tools

  • Dashboard

  • Monitor Data

  • Log files

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

Table 23-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 Enterprise Manager

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

Search for log messages through Enterprise Manager

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 that can be used to correlate individual events as being part of the same request execution flow.

Use the WebLogic Console to monitor database connection pool

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

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

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

  • 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 parameterd if necessary

  • Check the database using Enterprise Manager and see if there are any queries that are slow. Follow Enterprise Manager recommendation to add suggested indexes

  • 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 WebLogic 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 WebLogic 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 file.

SOAP Call Issues

  • Known issues exist with time-outs in SOAPGenericImpl

  • OWSM is enabled by default, so you need to set 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 should use the war version and EAR should use the ear 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 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

23.3 OAAM UIO Proxy


To troubleshoot the OAAM UIO Proxy Web publishing issues:

To troubleshoot problems experienced while configuring the UIO Proxy, enable tracing to a file and set the trace level to 0x8008f. Doing so wil 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.

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:

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 etc. The user has to use Apache 2.2.8 only.

Adding appid to HTTP Headers

Question/Problem: In TestConfig.xml, should we 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.

23.4 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. If you want 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.

23.5 Virtual Authentication Devices

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 via the screen reader and other assistive technologies.

You will need to modify

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 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 specifc 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 onscreen 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, he 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

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.

Buttons stop jittering.

Same image displayed to all users.

No image displayed in pad background.

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

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

  3. Rejar oracle.oaam.extensions.war.

  4. Deploy the jar.

Refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM."

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

# Length of the Pin bharosa.uio.otp.generate.code.length = 5 
# Characters to use when generating the Pin bharosa.uio.otp.generate.code.characters = 1234567890 

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

23.8 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 here are text, hot spot, 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.

23.9 Man-in-the-Middle/Man-in-the-Browser

Question/Problem: I use mobile transaction authentication number to sign each transaction using an OTP via 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, check to see 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.

23.10 Failure Counter

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