# OpenAM Administration Guide
Chapter 3. Defining Authorization Policies

Sidebar | Prev | Up | Next

## 3.2. Configuring Policies

An OpenAM authorization policy defines who can access what, under what conditions. The OpenAM agents enforcing policy call upon OpenAM to make policy decisions. Decisions from OpenAM can be as simple as "allow" or "deny." Decisions from OpenAM can alternatively provide additional information required for policy enforcement. OpenAM policies use response providers to return such additional information.

Procedure 3.1. To Create a Policy

1. In the OpenAM console, select Access Control > `Realm Name` > Policies, then click New Policy.

2. Provide at minimum a name for the policy.

Procedure 3.2. To Configure a Policy For a Web Site

Once a policy is created, you can further specify rules, subjects, conditions, and response providers.

OpenAM has, by default, three kinds of resources that you can protect with a policy.

- A Discovery Service, used in federated access management, locates the web service providing the data needed to complete an operation. Your policy protects what clients can look up and what they can update.

- A Liberty Personal Profile Service, used in federated access management, provides an identity's basic profile information. Your policy protects what clients can query and what they can modify.

- A URL Policy Agent protects resources on a specific web site or web application. Your policy protects what URLs client applications can access with HTTP GET and POST operations.

Follow these steps to configure a policy to protect a web site or web application.

1. In the OpenAM console, select Access Control > `Realm Name` > Policies > `Policy Name` to display the policy to edit.

2. In the Rules table, click New, and then create at least one Rule, identifying a resource name to protect.

   A Rule can specify an individual URL or resource name to protect. Alternatively, a Rule can match URLs or resource names by using wildcards.

   - The wildcard `*` matches multiple levels in a path. When used at the end of a rule `*` matches one or more characters, not zero or more characters.

     For example, `http://www.example.com/*` matches `http://www.example.com/index.html` and also `http://www.example.com/company/images/logo.png`, but not `http://www.example.com/`.

   - The wildcard `-*-` matches a single level in a path.

     For example, `http://www.example.com/-*-` matches `http://www.example.com/index.html` but does not match `http://www.example.com/company/images/logo.png`.

   - Wildcards do not match `?`. You must explicitly add Rules to match URLs with query strings.

     For example, to match everything under `http://www.example.com/` specify three Rules, one for `http://www.example.com/`, one for `http://www.example.com/*`, and one for `http://www.example.com/*?*`.

     When defining Rules to match URLs with query strings, know that OpenAM sorts the query string field-value pairs by field name when normalizing URLs, before checking whether a policy matches. Therefore the query string `?subject=SPBnfm+t5PlP+ISyQhVlplE22A8=&action=get` is equivalent to the query string `?action=get&subject=SPBnfm+t5PlP+ISyQhVlplE22A8=`.

   - Duplicate and trailing slashes (`/`) are not considered part of the resource name to match.

     For example, `http://www.example.com/path`, `http://www.example.com/path/`, `http://www.example.com//path/`, and `http://www.example.com/path//` are all treated in the same way.

   - Wildcards can be used in protocols, host names, and port numbers.

     For example, `http*://*:*/*` matches `http://www.example.com/index.html`, `https://www.example.com/index.html`, and `http://www.example.net:8080/index.html`.

     When a port number is not explicitly specified, then the default port number is implied. Therefore `http://www.example.com/*` is the same as `http://www.example.com:80/*`, and `https://www.example.com/*` is the same as `https://www.example.com:443/*`.

   - Wildcards cannot be escaped.

   - Do not mix `*` and `-*-` in the same Rule.

   - By default, comparisons are not case sensitive. The delimiter, wildcards and case sensitivity are configurable. To see examples of other configurations, browse in the OpenAM Console to Configuration > Global > Policy Configuration > Resource Comparator.

   Follow these steps for each new Rule you create.

   1. Select URL Policy Agent (with resource name), and click Next.

   2. Name the new rule, add the URL to protect in the Resource Name field, and set whether to allow or deny HTTP GET and POST requests to the URL.

   3. Click Finish.

      The new rule is not yet saved until you click the Save button in the Edit Policy screen.

3. In the Subjects table, click New... to define a subject, identifying the users to whom the policy applies.

   1. In the Select Subject Type screen, make your selection, and then click next.

      - Authenticated Users refers to users who have authenticated with OpenAM, even if they do not have profiles in the realm where you define the policy.

      - OpenAM Identity Subject refers to users or groups you can find under Access Control > Realm Name > Subjects.

      - Web Services Clients are for federated access management.

   2. Name the subject.

   3. If you want to apply the policy to everyone but the subjects you identified, then select Exclusive.

      For example

   4. If you selected OpenAM Identity Subject, use the Filter section to find and add to your list the subjects to whom to apply the policy.

   5. Click Finish.

4. In the Conditions table, click New... to create a condition, constraining the circumstances under which the policy applies.

   1. Select the Condition Type from the list.

      - Active Session Time lets you make the policy depend on how long the user's session has been active, and even to terminate the session if deemed too old, such that the user must authenticate again.

      - Authentication by Module Chain lets you make the policy depend on the realm where the user authenticated, and on the authentication chain used to authenticate.

      - Authentication by Module Instance lets you make the policy depend on the realm where the user authenticated, and on the authentication module used to authenticate, as well as setting timeouts for application authentication.

      - Authentication Level (greater than or equal to) lets you make the policy depend on the realm where the user authenticated, and on a minimum acceptable authentication level.

      - Authentication Level (less than or equal to) lets you make the policy depend on the realm where the user authenticated, and on a maximum acceptable authentication level.

      - Authentication to a Realm lets you make the policy depend on the realm where the user authenticated.

      - Current Session Properties lets you make the policy depend on attributes set in the user's session.

      - Identity Membership lets you make the policy depend on a list of OpenAM subjects that you select, and whether the user belongs to the list of users or is a member of a group you selected.

      - IP Address/DNS Name lets you apply the policy to clients in specific IP address ranges or coming from a particular DNS domain. It also lets you choose between IPv4 and IPv6 address versions.

        - For IPv4, fill in the fields for the From and To with four sets of four characters.

        - For IPv6, fill in the fields for the From and To with eight sets of four hexadecimal characters. The default separator between each set of IPv6 hexadecimal characters is a colon.

        - For a hybrid address, select IPv6. Fill in the first four fields for the From and To with four characters of the IPv6 address, then change the punctuation to a . and add the four IPv4 characters in the remaining three fields.

      - LDAP Filter Condition lets you make the policy depend on whether the user's entry can be found using the LDAP search filter you specify in the directory configured for the policy service, which by default is the identity repository. See Configuration > Global > Policy Configuration > Realm Attributes > Primary LDAP Server.

        Alternatively you can set this for the realm under Access Control > `Realm Name` > Services > Policy Configuration.

      - Resource/Environment/IP Address lets you make the policy apply using a complex condition such as whether the user is making a request from the localhost and has authenticated with the LDAP authentication module. This address also works with IPv4, IPv6, or a hybrid of the two.

      - Time (day, date, time, and timezone) lets you make the policy depend on when the policy is evaluated.

   2. Based on the Condition Type you choose, configure the condition, and then click Finish.

5. In the Response Providers table, click New to set up a response provider that adds attributes retrieved from the user entry in the identity repository into the headers of the request at policy decision time.

   1. Name the provider.

   2. Add static attributes having the form ``attribute`=`value``.

   3. Add dynamic attributes having the form ``responseAttr`=`repoAttr``, where `responseAttr` is the attribute name to be put into the header of the request, and `repoAttr` is the attribute name used in the identity repository.

   4. Click Finish.

6. Save your work.