Best practice for creating and testing policies in OpenAM 11.x
The purpose of this article is to provide best practice advice on creating and testing policies in OpenAM 11.x. This article also looks at the types of issues you may encounter when your policy is not evaluated as expected as well as troubleshooting your policy evaluation issues. These types of issue can be difficult to troubleshoot as the authorization process involves a succession of components, where policy evaluation is the last component in the process.
1 reader recommends this article
This article has been archived and is no longer maintained by ForgeRock.
Tips for creating policy rules
The following recommendations should be followed when creating your policy rules:
Always create the rules in the same order - Typically you will want to create 3 rules (for all policies, including referral policies) to define policies that access either the top level realm or a specific realm, depending on your setup:
We recommend you always create them in the same order to reduce the likelihood of forgetting to create a rule, especially if you have a lot of rules to create.
Top level realm
- root "/"
- pages "/*"
- pages with parameters "/*?*"
A specific realm, for example, /customers
- root "/customers"
- pages "/customers/*"
- pages with parameters "/customers/*?*"
- Always include a slash at the end of the root url - If you have to create a rule for the root address, such as: http://www.example.com, don't forget to put a "/" at the end. The final rule for this root url would be http://www.example.com/
- Always include the resource name in the name of the rule - Including the resource name in the rule name makes it easier to check that you have created all the rules you need; you can just check the list of policy rules rather than having to edit each rule to see what it applies to.
OpenAM 11.0.0 and Policy Agents 3.3.0.
There were a number of known policy evaluation issues with this combination of OpenAM and Policy Agent, including:
- OPENAM-3509 - further information about identifying this issue are detailed in Trailing forward slash removed from policy rules in OpenAM 11.0.0 and Policy Agents 3.3.0 which causes access denied error.
- OPENAM-3638 - further information about identifying this issue are detailed in Trailing wildcard in policy rules causes policy matching issues in OpenAM 11.0.0 and Policy Agents 3.3.0.
If you are using OpenAM 11.0.0 and Policy Agents 3.3.0, it is strongly recommended that you upgrade. Further information about the policy evaluation changes are given in the OpenAM 11.0.1 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality.
Policies using root or subtree mode
There are known issues with inconsistent policy evaluation using root or subtree mode: OPENAM-2085 (Unreliable policy evaluation results with com.sun.identity.agents.config.fetch.from.root.resource enabled).
It is recommended that you use non-root or self mode (default as of OpenAM 11.0.0). Details of how to change the mode are given in Unreliable policy evaluation results when using root or subtree mode in OpenAM 13.x.
Policies with referrals
When you have policies behind a referral policy, you must set up the 3 rules (root, pages and pages with parameters) to the referral policy as well. See OpenAM Administration Guide › Configuring Realms › To Delegate Policy Management for further information.
A common issue is to forget one of the rules to the referral policy and then try to use it in a sub-policy.
Creating a complex policy
If you want to create a complex policy, that is one that includes multiple conditions and subjects, we recommend that you split the process into separate steps. You can then test after completing each step to ensure it is correct prior to starting the next step. This will make troubleshooting a lot easier as you will know which step introduced the issue.
The recommended way to create a complex policy is:
- Configure the subject, with a type of Authenticated Users to allow all authenticated users access. You can refine this access later but it is preferable to start with everyone having access when creating a new complex policy.
- Create a rule for a specific page.
- Test your rule (as detailed in the Testing a policy section).
- Create your subject and test it.
- Create your condition and test it with your rule.
- Create further subjects and conditions as needed, testing as you go to make sure each addition works correctly.
- Add further rules if required (for example, for root and pages with parameters) and repeat this process of extending and testing (steps 2 to 6).
See OpenAM Administration Guide › Defining Authorization Policies › Configuring Policies for further information on creating policies.
Testing a policy
You should test your policy during creation (as discussed in the Creating a complex policy section) and after creation. We recommend you test your policy using the REST API as this calls the PolicyEvaluator class directly.
You would use a curl command similar to this:$ curl "https://openam.example.com:8443/openam/identity/authorize?uri=http%3A%2F%2Fwww.example.com%3A8080%2Fexamples%2Findex.html&subjectid=AQIC5wM2LY4SfcxuxIP0VnP2lVjs7ypEM6VDx6srk56CN1Q.*AAJTSQACMDE.*"
See OpenAM Developer's Guide › Using RESTful Web Services › Requesting Policy Decisions and OpenAM Developer's Guide › Using RESTful Web Services › Authorization for further information.
You could develop a test suite with the REST API to make testing policies easier; this is especially useful if you are likely to update your policies frequently.
Raising a support ticket for a policy issue
If you are experiencing issues with your policies, where they are not being evaluated as expected, you can raise a support ticket. You should follow this process to ensure you include all the necessary information in your ticket to help us investigate your issues more effectively:
It is very important that your timestamps match across the entire set of logs and HTTP trace. Failing to do this may mean you need to capture ALL the data again.
- Export OpenAM and policy configurations - it is essential to check if there is a configuration issue contributing to your policy issues. You can export these as described in How do I export and import policies in AM (All versions)? and How do I export and import Service configurations for AM (All versions) using Amster or ssoadm?
- Identify the stage at which the policy evaluation failed - if you have followed the steps in the Creating a complex policy section, you can let us know which step failed testing to help us identify the root cause.
- Generate a full set of debug logs and capture the HTTP trace while reproducing the issue. Refer to How do I collect all the data required for troubleshooting AM and Agents (All versions)? for information on how to collect this data.
- Capture HTTP container logs (Access and Error) for both OpenAM and policy agents with date and timestamps that correspond to the amAgent and OpenAM debug logs. HTTP container logs show all requests to the server, whether they were successful or not and any corresponding error messages.
- Capture LDAP server logs for your data store and configuration store with date and timestamps that correspond to the amAgent and OpenAM debug logs. There are some use cases that require analysis of the LDAP server logs from OpenAM's data store (user profile) and Configuration store.
- Attach the following diagnostic logs and outputs to your support request as detailed in Sending troubleshooting data to ForgeRock Support for analysis
- OpenAM and policy configuration exports.
- Log files from:
- OpenAM - $HOME/[openam_instance]/openam/debug and $HOME/[openam_instance]/openam/logs
- Policy Agent - /path/to/policy_agent/[agent_instance]/logs/debug directory where the policy agent is installed.
- HTTP trace - from the HTTP trace browser tool.
- HTTP container logs - the actual name and location of the server logs are specific to your web container. For example, for OpenAM deployed on Apache Tomcat, the Tomcat logs are called localhost_access_log.YYYY-MM-DD.log and catalina.out, and are located in the /path/to/tomcat/logs/ directory by default.
- LDAP server logs - for embedded OpenDJ, these log files are located in the $HOME/[openam_instance]/opends/logs directory by default and for external OpenDJ, they are located in the /path/to/opendj/logs directory.
- Output from the curl command and response.
- Update your ticket to let us know the timestamp(s) of when the issue was reproduced (so we can correlate this with the logs) and OpenAM and Policy Agent versions; some issues are version specific so knowing your version will help us focus on relevant issues only.
Refer to Best practice for raising an Identity Platform ticket with ForgeRock Support for further information on creating a ticket. Follow this guide for submitting technical information needed to help us resolve your issue as soon as possible.
FAQ: OpenAM Java SDK and policy decision cache
Trailing forward slash removed from policy rules in OpenAM 11.0.0 and Policy Agents 3.3.0 which causes access denied error
Trailing wildcard in policy rules causes policy matching issues in OpenAM 11.0.0 and Policy Agents 3.3.0
Unreliable policy evaluation results when using root or subtree mode in OpenAM 13.x
Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x
Best practice for creating and testing policies in AM (All versions)
OpenAM 11.0.1 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality
OpenAM Administration Guide › Defining Authorization Policies › Configuring Policies
OpenAM Developer's Guide › Using RESTful Web Services › Requesting Policy Decisions
Related Issue Tracker IDs
OPENAM-2085 (Unreliable policy evaluation results with com.sun.identity.agents.config.fetch.from.root.resource enabled)
OPENAM-3509 (PolicyEvaluation strips off trailing '/' from resource resulting in wrong enforcement on agent side)
OPENAM-3638 (Policy rule with trailing wildcard denies access to a valid resource URL)