Best practice for creating and testing policies in OpenAM 11.x

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:

  Top level realm	root "/" pages "/*" pages with parameters "/*?*"
  A specific realm, for example, /customers	root "/customers" pages "/customers/*" pages with parameters "/customers/*?*"

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

Known issues

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.

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:

1. 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.
2. Create a rule for a specific page.
3. Test your rule (as detailed in the Testing a policy section).
4. Create your subject and test it.
5. Create your condition and test it with your rule.
6. Create further subjects and conditions as needed, testing as you go to make sure each addition works correctly.
7. 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:

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.

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:

1. 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?
2. 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.
3. 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.
4. 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.
5. 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. 
6. 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.
7. 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.

​

See Also

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 Training

N/A

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)