Best practice for creating and testing policies in AM (All versions)

Tips for creating policies

The following recommendations should be followed when creating your policies:

• Always create the rules in the same order - Typically you will want to create 3 rules for all 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.
• Use deny rules with caution - It is preferable to add explicit allow rules for each protected area individually, rather than create one big global rule and restrict access through deny rules where needed. If you have a global access policy, this allows access to all authenticated users unless you explicitly define a deny policy; forgetting to set the deny policy or setting it incorrectly could be a security risk. When deciding on the use of deny policies for restricted areas, you should take into account the balance between maintainability, performance and security.
• Never include a forward slash in policy names - You will not be able to edit or delete policies with the forward slash character in their names if you are running Apache Tomcat™ or JBoss® web containers without setting: ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=truein the CATALINA_OPTS environment variable before starting the AM web container. However, it is strongly recommended that you do not set this option when running AM in production as it introduces a security risk. When Tomcat is deployed behind a reverse proxy, this setting can expose you to a directory traversal security vulnerability (CVE-2007-0450); see Apache Tomcat 6.x Vulnerabilities for further information. Therefore, it is preferable to avoid policy names that contain slashes. If this is not possible, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM (All versions)? for further information.
• Never include special characters in your policy names - The special characters to avoid are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

Creating a complex policy

If you want to create a complex policy, that is one that includes multiple subject and environment conditions, 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. Create a policy for the default application type (iPlanetAMWebAgentService) and specify resources and actions to which the policy applies.
2. Add a subject condition, select All Authenticated Users as the subjects who the policy applies to. You can refine this access later but it is preferable to start with everyone having access when creating a new complex policy.
3. Test your simple policy (as detailed in the Testing a policy section).
4. Define an environment condition and test.
5. Create further subject and environment conditions as needed, testing as you go to make sure each addition works correctly.
6. Add any response attributes you require and test.

See Authorization 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 XACMLRequestProcessor class directly.

You would use a curl command similar to this. For example: $ curl -X POST -H "iPlanetDirectoryPro: AQIC5...DU3*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0" -d '{ "resources": [ "http://www.example.com/index.html", "http://www.example.com/do?action=run" ], "application": "iPlanetAMWebAgentService" }' https://am.example.com:8443/am/json/realms/root/policies?_action=evaluate

Example responses:

• Example response that shows both resources being accepted (actions are populated and set to true): [{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/index.html","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}},{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/do?action=run","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}}]
• Example response that shows the first resource being denied (empty response for actions signifying a deny) and the second one being accepted: [{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/do?action=run?help","actions":{},"attributes":{}},{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/index.html","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}}]

See Request policy decisions over REST for further information and example curl commands.

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 AM 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 AM and Agents with date and timestamps that correspond to the AM and Agent 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 AM and Agent debug logs. There are some use cases that require analysis of the LDAP server logs from the AM 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
   • AM and policy configuration exports.
   • Log files from:
     • AM
       • AM 7 and later: /path/to/am/var/debug and /path/to/am/var/audit
       • AM 6.x: /path/to/am/debug and /path/to/am/log
     • Agent - /path/to/policy_agent/[agent_instance]/logs/debug directory where the 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 AM 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 DS, these log files are located in the /path/to/am/opends/logs directory by default and for external DS, they are located in the /path/to/ds/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 AM and Agent versions; some issues are version specific so knowing your version will help us focus on relevant issues only.

See Also

Troubleshooting AM and Agents

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs

N/A