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.
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 as they 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.
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, 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.
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.
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. 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.
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=repoAttrresponseAttr 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.)
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, /.
You use a referral to delegate policy management, and to delegate policy decision making.
Referrals are covered in the chapter on Realms.