|Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
Release 11g (11.1.1)
Part Number E15480-06
|PDF · Mobi · ePub|
This section describe a process to enable you to more easily solve a complex problem. It contains the following topics:
You can work your way through some simple troubleshooting techniques to try to solve a problem.
|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 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||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.|
|Divide||Break the problem down|
Steps to reduce the problem to a manageable issue are listed in this section.
|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.|
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
The process flow of analysis is presented below:
State the problem.
Specify the problem.
Develop possible causes from:
Knowledge and experience
Distinctions and changes
Test possible causes against the specification.
Determine most probable cause.
Verify the solution.
Stating the problem is the most important step to solving the issue.
|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.|
Describe problems in detail and ask focused questions to gather pertinent information.
|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.
If the component did not work before, performing these steps:
|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:
|Consider if the solutions is just to change perception||What can you see that causes you to think there's a problem?
Consider what the problem is, what it isn't, and what it could be.
|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.|
Problem solving involves developing possible causes.
|Knowledge and experience||You can use your knowledge and experience to recognize possible causes
|Distinctions and changes||You can make a list of distinctions and changes to narrow down causes:
|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:
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 so that you can devise an action plan.
Devise ways to test the possible causes
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.
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
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
OAAM Specific Tools
Table 23-2 provides items to check for when troubleshooting the system.
Table 23-2 Troubleshooting Tips
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
Connection Pool Errors
Errors While Starting the Managed Server After Upgrade
OAAM CLI Script Issues
SOAP Call Issues
Native Integration Issues
UIO ISA 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.
Ensure the database access credentials are correct when the firewall logging properties in Microsoft ISA use the SQL Database as the log storage format.
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 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.
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 Web site, 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
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 schema. You can use the
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 need to do the following:
Change the header of the XML file to use
<?xml version="1.0" encoding="utf-8"?><BharosaProxyConfig xmlns="http://bharosa.com/">
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.
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
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.
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 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 etc. The user has to use Apache 2.2.8 only.
Adding appid to HTTP Headers
TestConfig.xml, should we be adding
appid to HTTP headers for both the PSFT URLs and the
Answer/Solution: No, just to the
/asa/ URLs. It should be adding the
app-id to only the
/asa/ URLs, not needed for
Question/Problem: Should a condition with "contains" match if there is an exact match?
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.
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.
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
bharosa_server.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 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
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
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 make sure that the backgrounds directory 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 directory.
Check the properties file to make sure that the backgrounds directory setting is correct.
Check that the system is configured to assign images for personalization.
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:
Use the Oracle Adaptive Access Manager extensions shared library to package the jar.
Add the jar to "
Deploy the jar.
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.
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.
Answer/Solution: Globalized virtual authentication device image files including the authentication registration flows are not provided. The deployment team develop these.
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.
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.
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.
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.
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.
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.