Authorization is determining whether to grant or deny a user access to a resource. Policies define how to determine whether to grant or deny access. This chapter describes how to configure authorization policies managed by OpenAM.

Authorization Policy Applications rely on OpenAM for access management, which breaks down into authentication, or determining who is trying to access a resource, and authorization, or determining whether to grant or deny access. This is because whether access is granted generally depends on what the rules about access are, who is trying to gain access, and perhaps some other conditions, such as whether the access itself needs to happen over a secure channel or what time of day it is. To return to the international airport example, the rule may be that passengers with valid passports and visa presenting valid plane tickets are allowed through to the gate where the plane is waiting to take off, but only under the condition that the plane is going to leave soon. (You cannot expect to get to the gate today with a scheduled departure for three months from now.) To allow OpenAM to determine whether to grant access, you define authorization policies. A policy includes rules that match what resources a user aims to access in what way and whether to grant or deny that access, subjects to whom the policy applies, and potentially conditions under which the policy applies. When queried about whether to let a user through to a protected resource, OpenAM decides to authorize access or not based on the applicable policy. OpenAM then communicates its decision to the application using OpenAM for access management, or in the common case to the policy agent installed in the server where the application runs. The application or the agent then enforces the authorization decision from OpenAM. For example, consider the case where OpenAM protects a web site page that users access to update their profiles. An OpenAM policy agent installed in the web server intercepts client requests to enforce policy. The policy says that authenticated users can access the page to update their profiles as long come in over HTTPS, rather than HTTP. When a user browses to the page to update her profile, the OpenAM policy agent intercepts the request. The policy agent notices that the request is to access a protected resource, but the request is coming from a user who has not yet logged in and has no authorization to visit the page. The agent therefore redirects the user to OpenAM. OpenAM receives the redirected user, serving a login page that collects her email and password. With the email and password credentials, OpenAM authenticates the user, and gives her a session. OpenAM then redirects the user to the policy agent, which gets the policy decision from OpenAM for the page she wants to access, and grants access to the page. OpenAM and the policy agent use cookies set in the user's browser to reference her session. While the user has a valid session with OpenAM, she can go away to another page in her browser, come back to the update profile page, and gain access without having to enter her email and password again. Notice how OpenAM and the policy agent handle the access in the example. The web site developer can offer a profile page, but the web site developer never has to manage login, nor has to handle who can access a page. As OpenAM administrator, you can change authentication and authorization independently of updates to the web site. You might need to agree with web site developers on how OpenAM identifies users so web developers can find their particular profiles, or identify the user by her own name when she logs in. Yet your organization is now spared from new web site development projects when you want to add external access to your Intranet for roaming users, open certain of your sites to partners, only let managers access certain pages of your HR web site, or allow users already logged in to their desktops to visit protected web sites without having to type their user names and passwords again. When OpenAM denies a request due to a condition that could be corrected by further authentication, OpenAM can send advice to the policy agent, and the policy agent can then take remedial action. For instance, suppose a user comes to a web site having authenticated with an email address and password, which is configured as authentication level 0. Had the user authenticated over the VPN which relies on one-time password authentication, she would have had authentication level 1 in her session. Yet, because she has authentication level 0, she currently cannot access the page she wants, which requires authentication level 1. OpenAM can send advice in this case, prompting the agent or application to redirect her to authenticate again with a one-time password, gaining authentication level 1, and thus having OpenAM grant her access to the protected page. Policies can include response providers. Response providers extend HTTP headers with additional information beyond an "allow" or "deny" decision. For example, a response provider can return a message about why access was denied.

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. In the OpenAM console, select Access Control > Realm Name > Policies, then click New Policy... Provide at minimum a name for the policy. Authorization Configuring Policy Configuring 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. In the OpenAM console, select Access Control > Realm Name > Policies > Policy Name to display the policy to edit. In the Rules table, click New... to create a rule, identifying a URL to protect. Select URL Policy Agent (with resource name), and click Next. 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. The URL can include asterisks as wildcards (*). Wildcard matches for rules work as follows. A * matches zero or more characters including /, but A * at the end of the Resource Name immediately following / matches one or more characters including /. Multiple forward slashes do not match a single forward slash, so mult/*/dirs matches mult/iple/dirs, yet mult/*/dirs does not match mult/dirs. Trailing forward slashes are not recognized as part of a Resource Name. Therefore http://www.example.com/images// and http://www.example.com/images are equivalent. Click Finish. The new rule is not yet saved until you click the Save button in the Edit Policy screen. In the Subjects table, click New... to define a subject, identifying the users to whom the policy applies. 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. Name the subject. If you want to apply the policy to everyone but the subjects you identified, then select Exclusive. For example 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. Click Finish. In the Conditions table, click New... to create a condition, constraining the circumstances under which the policy applies. 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. 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. 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. Time (day, date, time, and timezone) lets you make the policy depend on when the policy is evaluated. Based on the Condition Type you choose, configure the condition, and then click Finish. 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. Name the provider. Add static attributes having the form attribute=value. 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. Click Finish. Save your work.

OpenAM has to match policies to resources to take policy decisions. For a policy to match, the resource has to match a resources identified in a rule. The user making the request has to match a subject. Furthermore, at least one condition for each condition type has to be satisfied. If more than one policy matches, OpenAM has to reconcile differences. When multiple policies match, the order in which OpenAM uses them to make a policy decision is not deterministic. However, a deny decision overrides an allow decision, and so by default once OpenAM reaches a deny decision its stops checking further policies. (If you want OpenAM to continue checking despite the deny, see Configuration > Global > Policy Configuration > Continue Evaluation on Deny Decision.)

Authorization Configuring Policy Configuring When you first create policies, the OpenAM console helps you to get started quickly. Yet, when you have many policies to manage you might find it easier to script operations, starting from policies originally created in the console, then exported to XML. You can export policies created in the console to an XML Policies document. Use the ssoadm list-policies command. $ ssoadm list-policies --realm "/" --adminid amadmin --password-file /tmp/pwd.txt Policy definitions were returned under realm, /. <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Policies PUBLIC "-//OpenSSO Policy Administration DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd"> <!-- extracted from realm, / --> <Policies> <Policy name="URL Policy" createdby="id=amadmin,ou=user,o=openam" lastmodifiedby="id=amadmin,ou=user,o=openam" creationdate="1312553988059" lastmodifieddate="1315403023466" referralPolicy="false" active="true" > <Rule name="Allow GET with parameters"> <ServiceName name="iPlanetAMWebAgentService" /> <ResourceName name="http://www.example.com/ching/*?*" /> <AttributeValuePair> <Attribute name="GET" /> <Value>allow</Value> </AttributeValuePair> </Rule> <Rule name="Allow GET and POST"> <ServiceName name="iPlanetAMWebAgentService" /> <ResourceName name="http://www.example.com/ching/*" /> <AttributeValuePair> <Attribute name="POST" /> <Value>allow</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="GET" /> <Value>allow</Value> </AttributeValuePair> </Rule> <Subjects name="Subjects:1312553593870WmIuFvI=" description=""> <Subject name="All Authenticated Users" type="AuthenticatedUsers" includeType="inclusive"> </Subject> </Subjects> </Policy> </Policies> In a production environment where you manage operations using scripts rather than the console, use exported, file-based policies edited for your needs, and then import the policies using ssoadm. Create your XML policy file. $ cat policy.xml <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Policies PUBLIC "-//OpenSSO Policy Administration DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd"> <!-- New policy, same as the old policy --> <Policies> <Policy name="New Policy" referralPolicy="false" active="true" > <Rule name="Allow GET with parameters"> <ServiceName name="iPlanetAMWebAgentService" /> <ResourceName name="http://www.example.com/ching/*?*" /> <AttributeValuePair> <Attribute name="GET" /> <Value>allow</Value> </AttributeValuePair> </Rule> <Rule name="Allow GET and POST"> <ServiceName name="iPlanetAMWebAgentService" /> <ResourceName name="http://www.example.com/ching/*" /> <AttributeValuePair> <Attribute name="POST" /> <Value>allow</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="GET" /> <Value>allow</Value> </AttributeValuePair> </Rule> <Subjects name="Subjects" description="Everybody authenticated"> <Subject name="All Authenticated Users" type="AuthenticatedUsers" includeType="inclusive"> </Subject> </Subjects> </Policy> </Policies> Use the ssoadm create-policies command. $ ssoadm create-policies --realm "/" --adminid amadmin --password-file /tmp/pwd.txt --xmlfile policy.xml Policies were created under realm, /.

Authorization Delegating Policy Delegating You use a referral to delegate policy management, and to delegate policy decision making. Referrals are covered in the chapter on Realms.