test

Sun OpenSSO Enterprise 8.0 Administration Guide

Chapter 4 Managing Policies

The OpenSSO Enterprise Policy Service enables the top level administrator or top level policy administrator to view, create, delete, modify, and delegate policies to define access to an organization's protected resources. This chapter describes how to configure and manage policies using the OpenSSO Enterprise console. It contains the following sections.

Understanding the Authorization Process

Businesses have applications and services that they need to protect. A policy defines rules that specify who or what can access these protected resources. The rules are, in effect, permissions describing when and how a principal can perform an action on a given protected resource. (A principal can be an individual, a corporation, a role, or a group.) In general, the permissions define what a principal can do to which resource and under what conditions. Towards this end, OpenSSO Enterprise provides the Policy Configuration Service to define global and realm preferences that effect the Policy Service which is used to create and manage the policies. (For more on the Policy Configuration Service, see Policy Configuration in Sun OpenSSO Enterprise 8.0 Administration Reference.)

The Policy Service allows administrators to define, modify, grant, revoke and delete the policies that protect resources within the OpenSSO Enterprise deployment. Typically, a policy service includes a repository to store policies, interfaces that allow for the creation, administration and evaluation of policies, and a policy agent to enforce the policies. By default, OpenSSO Enterprise uses the configuration data store for policy storage, and the OpenSSO Enterprise console for policy management. Policy agents specifically developed for OpenSSO Enterprise act as the policy enforcement point (PEP). (OpenSSO Enterprise also provides Java and C interfaces for policy creation, policy evaluation, policy agent development, and Policy Service customization. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide and the Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers for more information.)

The policy agent is installed remotely from OpenSSO Enterprise and serves as an authorization step (following user authentication) when a user requests access to a protected resource. For example, a Human Resources server that is protected by a remote instance of OpenSSO Enterprise has an agent installed on it to act as a PEP. This agent would prevent personnel without the proper permission from viewing confidential salary information or other sensitive data. (More information on installing and administrating the policy agents can be found in the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents and the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents. Most policy agents can be downloaded from the Sun Microsystems Download Center.)

The authorization process begins when a web browser requests a URL that resides on a server protected by the policy agent. The policy agent installed on the server intercepts the request and checks for an existing OpenSSO Enterprise session token (SSOToken) for authentication credentials. If the session token is valid, the user is allowed or denied access based on the applicable configured policy. If the token is invalid or there is no existing session token, the user is redirected to the Authentication Service and the following occurs.

  1. The policy agent redirects the user to the Authentication Service login page.

  2. The user submits credentials for authentication.

  3. Assuming successful authentication, the agent issues a request to the OpenSSO Enterprise Naming Service.

  4. The Naming Service returns locators for the Policy Service, the Session Service, and the Logging Service.

  5. The policy agent sends a request to the Policy Service for the policy applicable to the requesting user and resource.

  6. Based on the returned policy, a decision is reached and the user is allowed or denied access.

    The policy agent may redirect the request back to the Authentication Service if the policy decision indicates a different authentication level or authentication mechanism is needed.

Note –

In addition, the Resource Comparator attribute in the Policy Configuration Service would also need to be changed from its default configuration to:

serviceType=Name_of_LDAPService |class=com.sun.identity.policy.plugins.SuffixResourceName|wildcard=*

|delimiter=,|caseSensitive=false

Alternately, providing an implementation such as LDAPResourceName to implement com.sun.identity.policy.interfaces.ResourceName and configuring the Resource Comparator appropriately would also work.

Defining a Policy and a Referral

There are two configurations that can be created using the OpenSSO Enterprise Policy Service: a policy controls access to a protected resource and consists of rules, subjects, conditions, and response providers values, and a referral that delegates policy creation and evaluation to a particular entity and consists of one or more rules and one or more referrals. The following sections have more information.

Policy

In OpenSSO Enterprise, a policy (referred to as a normal policy in previous releases) consists of rules, subjects, conditions, and response providers. A policy can be defined with either binary or non-binary decisions. A binary decision is yes/no, true/false or allow/deny. A non-binary decision represents the value of an attribute. For example, a mail service might include a mailboxQuota attribute with a maximum storage value set for each user. The following sections have more information on the components of a policy.

Rules

A rule contains a service type and one or more actions with an appropriate value that, in effect, defines the intent of the policy. The service type defines the policy-enabled resource that is being protected. An action is the operation that can be performed on the resource; examples of web server actions are POST or GET. A value defines the permission for the action, for example, Allow or Deny. An example of an allowable action for a human resources service might be to change a home telephone number.

Note –

For some services, it is acceptable to define an action without resources.

By default, there are three OpenSSO Enterprise services enabled for policy protection. The following sections explain these policy-enabled service types and the actions that can be applied to each.

Tip –

When assessing policy, deny rules always take precedence over allow rules. For example, if you have two policies for a given resource, one with a rule denying access and the other with a rule allowing access the result, provided that the conditions for both policies are met, is deny. Thus, it is recommended that deny policies be used with extreme caution as they may potentially lead to conflicts. For example, if explicit deny rules are used, policies that are assigned to a given user through different subject types (such as a role or group membership) may result in denied access to a resource. This is illustrated if there is a deny policy for a resource applicable to an Employee role and an allow policy for the same resource applicable to Manager role; policy decisions for users assigned both Employee and Manager roles would be denied. Typically, the policy should use allow unless there are no policies to accomplish the deny case.

One way to resolve this issue is to design policies using Condition plug-ins. In the example, a role condition that applies the deny policy to users authenticated to the Employee role and applies the allow policy to users authenticated to the Manager role helps to differentiate subjects. Another option is to use the Authentication Level condition stipulating that subjects with the Manager role authenticate at a higher authentication level.

Discovery Service (with resource name)

Discovery Service (with resource name) allows administrators to create and manage policies corresponding to the LOOKUP and UPDATE actions that can be performed on the Discovery Service.

Liberty Personal Profile Service (with resource name)

Liberty Personal Profile Service (with resource name) allows administrators to create and manage policies corresponding to the MODIFY and QUERY actions that can be performed on the Liberty Personal Profile Service.

URL Policy Agent (with resource name)

URL Policy Agent (with resource name) allows administrators to create and manage policies for policy agents that enforce decisions on http/http(s) URLs.

Subjects

A subject defines the user or collection of users (for instance, a group or those who possess a specific role) that the policy affects. The general rule for subjects is that the policy would apply only if the user is a member of at least one subject in the policy. The default subjects are:

Authenticated Users

This subject type implies that any user with a valid SSOToken is a member. Thus, all authenticated users are member of this Subject even if they have authenticated to a realm that is different from the one in which the policy is defined. This is useful if the resource owner would like to offer access to resources managed for users from other organizations. To restrict access to protected resources belonging to a specific organization, use the Organization subject.

OpenSSO Identity Subject

This subject type implies that the identities defined under the Subjects tab of a particular realm can be added as a member.

Web Services Clients

This subject type implies that a web services client (WSC) identified by a valid SSOToken is a member IF the Distinguished Name (DN) of any principal contained in the SSOToken matches any value of this subject. Valid values are the DNs of trusted certificates in a local Java keystore that correspond to the certificates of trusted WSCs. This subject type has dependency on the Liberty Alliance Project Web Services Framework and should be used to authorize WSCs only by service providers that implement it. Also, be sure to create the keystore before you add this Subject to a policy.

The following additional subjects are available by selecting them in the Policy Configuration Service of the realm. If you enable any of them, you should also change the values of the LDAP Bind DN and LDAP Bind Password attributes in the Policy Configuration Service of the realm to reflect valid credentials for the LDAP directory. Please note that cn=amldapuser,ou=DSAME Users and the top level suffix is not created in the default configuration directory.

LDAP Groups

This subject type implies that any member of an LDAP group is member of this subject.

LDAP Roles

This subject type implies that any member of an LDAP role is a member of this subject. An LDAP Role is any role definition that uses the Directory Server role capability. These roles have object classes mandated by Directory Server role definition. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.

Note –

Nested roles can be evaluated correctly as LDAP Roles in the subject of a policy definition.

LDAP Users

This subject type implies that any LDAP user is a member of this subject.

OpenSSO Roles (Legacy Mode)

This subject type implies that any member of an OpenSSO Enterprise role is a member of this subject. An OpenSSO Enterprise role is created using OpenSSO Enterprise running in legacy mode with the AMSDK datastore and has object classes mandated by OpenSSO Enterprise. OpenSSO Roles can only be accessed through the hosting OpenSSO Enterprise Policy Service.

Organization

This subject type implies that any member of a realm is a member of this subject

Note –

All OpenSSO Roles can be used as Directory Server roles. However, all LDAP roles are not necessarily OpenSSO Enterprise roles. LDAP roles can be leveraged from an existing directory by configuring the Policy Configuration Service. OpenSSO Enterprise roles can only be accessed through the hosting OpenSSO Enterprise Policy Service. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.

Conditions

A condition allows you to define constraints on the policy. For example, if you want to limit access to a paycheck application, you can define a condition specifying the hours; or, you may wish to define a condition that only grants access if the request originates from a given set of IP addresses or from a company intranet. For example, to configure http://org.example.com/hr/*.jsp so that it can only be accessed by users from org.example.com between 9 a.m. to 5 p.m., use an IP Condition along with a Time Condition. By specifying the rule resource as http://org.example.com/hr/*.jsp, the policy would apply to all the JSPs under http://org.example.com/hr including those in the sub directories. The default conditions are:

Active Session Time

Sets the condition based on user session data.

Max Session Time

Specifies the maximum duration to which the policy is applicable starting from when the session was initiated.

Terminate Session

If selected, the user session will be terminated if the session time exceeds the maximum allowed as defined in the Max Session Time field.

Authentication by Module Chain

The policy applies if the user has successfully authenticated to the authentication chain in the specified realm. If no realm is specified, authentication to any realm at the authentication chain will satisfy the condition.

Authentication by Module Instance

The policy applies if the user has successfully authenticated to the instantiated authentication module in the specified realm. If no realm is specified, authentication to any realm at the authentication module will satisfy the condition.

Authentication Level (greater than or equal to)

The policy applies if the user’s authentication level is greater than or equal to the Authentication Level set in the condition. This attribute indicates the level of trust for authentication within the specified realm.

Authentication Level (less than or equal to)

The policy applies if the user’s authentication level is less than or equal to the Authentication Level set in the condition. This attribute indicates the level of trust for authentication within the specified realm.

Current Session Properties

Decides whether a policy is applicable to the request based on values set in the user's OpenSSO Enterprise session. During policy evaluation, the condition returns true only if the user's session has every property value defined in the condition. For properties defined in the condition with multiple values, it is sufficient if the token has at least one value for the property.

Note –

Session properties set by OpenSSO are prefixed with am.protected to ensure that they cannot be edited by the Client SDK.

Identity Membership

Checks if the invocator uuid specified in the environment is a member of at least one AMIdentity object specified in the Condition. The uuid invocator is specified as the key value of Condition. INVOCATOR_PRINCIPAL_UUID in the environment parameter of the evaluation request. This is primarily used to apply authorization rules for WSC (Web Service Client). The identity of the WSC is passed as the value of uuid invocator.

IP Address/DNS Name

Sets the condition based on a range of IP Addresses. The fields you can define are:

IP Address From/To

Specifies the range of the IP address.

DNS Name

Specifies the DNS name. This field can be a fully qualified hostname or a string in one of the following formats:

domainname

*.domainname

LDAP Filter Condition

The policy is applicable when the defined LDAP filter locates the user entry in the LDAP directory that was specified in the Policy Configuration service. This is only applicable within the realm that the policy is defined.

Time (day, date, time, and timezone)

Sets the condition based on time constraints. The fields are:

Date From/To

Specifies the range of the date.

Time

Specifies the range of time within a day.

Day

Specifies a range of days.

Timezone

Specifies a timezone, either standard or custom. Custom timezones can only be a timezone ID recognized by Java (for example, PST). If no value is specified, the default value is the Timezone set in the OpenSSO Enterprise JVM.

If a request for access is negated as determined by the condition, an advice message can be produced to indicate why. Advice messages are propagated in the policy decision and sent to the policy agent which retrieves the advice and takes appropriate action — for example, redirecting the user to the Authentication Service to authenticate to a higher level. If, in this example, the user successfully authenticates to a higher level the policy might then become applicable. See com.sun.identity.policy in the Sun OpenSSO Enterprise 8.0 Java API Reference for more information.

Tip –

Custom conditions can also produce advices. However, the policy agents respond only for Auth Level Advice and Auth Scheme Advice. Custom agents can be written to respond to more advices and existing OpenSSO Enterprise policy agents can be extended to do the same. See the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents for more information.

Response Providers

Response providers are plug-ins that provide values, in the final policy decision, for particular attributes in the authorized user's profile. The attributes are sent with the policy decision to the policy agent which, in turn, passes them in headers to an application. The application typically uses these attributes for customizing pages such as a portal page. OpenSSO Enterprise includes one implementation of the com.sun.identity.policy.interfaces.ResponseProvider interface, the IDResponseProvider. Custom response providers can be implemented.

Referral

A referral (referred to as a referral policy in previous releases) controls the delegation of both policy creation and evaluation. It consists of one or more rules and one or more referrals. Using a referral policy allows an administrator to delegate the administration of a realm's policy definitions and decisions to a sub or peer realm. Alternatively, policy decisions for a resource can be delegated to other policy products.

Note –

The Policy Configuration service contains a global attribute called Realm Alias Referrals. This attribute allows you to create policies in sub-realms without having to create referral policies from the top-level or parent realm. You can only create policies to protect HTTP or HTTPS resources whose fully qualified hostname matches the realm/DNS Alias of the realm. By default, this attribute is defined as No.

The following sections have more information on the components of a referral.

Rules

A referral rule defines the resource whose policy definition and evaluation is being referred. By default, there are three OpenSSO Enterprise services enabled for policy referral.

Referrals

The referral defines the realm to which policy definition and evaluation is being referred. The referral can delegate to a peer realm (on the same level) or a sub realm (on a subordinate level). The realm to which policy definition or evaluation is referred can define and evaluate access only for those protected resources (or sub-resources) that have been referred to it. (This restriction does not apply to the top-level realm.) For more information, see To Create a Referral Using the OpenSSO Enterprise Console.

Creating Policies and Referrals

Policies are generally configured by creating an XML file and importing the data to OpenSSO Enterprise using the ssoadm command line utility but, they can also be created using the OpenSSO Enterprise console. (You can also create, modify and delete policies using the Policy API. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.) The following sections contain procedures for creating policies or referrals using the ssoadm command line utility and the OpenSSO Enterprise console. In general, policy is created at the realm (or sub realm) level for use throughout the particular realm’s tree.

Tip –

Wildcards are supported in policy definitions. For information see Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

ProcedureTo Add Multiple Policies Using the ssoadm Command Line Utility

Before You Begin

Before adding policies to OpenSSO Enterprise using ssoadm ensure that:

  1. Create an XML file with policy definitions.

    To add multiple policies simultaneously, place all policy definitions in one XML file (as opposed to having one policy per XML file). This will help to avoid issues with the policy index. Following is an example of an XML file with policy definitions.

    <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Policies
PUBLIC "-//Sun Java System Access Manager 7.1 2006Q3 Admin CLI DTD//EN"
"jar://com/sun/identity/policy/policyAdmin.dtd">

<Policies>
<Policy name="bigpolicy" referralPolicy="false" active="true" >
<Rule name="rule1">
<ServiceName name="iPlanetAMWebAgentService" />
<ResourceName name="http://thehost.thedomain.com:80/*.html" />
<AttributeValuePair>
<Attribute name="POST" />
<Value>allow</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="GET" />
<Value>allow</Value>
</AttributeValuePair>
</Rule>
<Subjects name="subjects" description="desccription">
<Subject name="webservicescleint" type="WebServicesClients" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/><Value>CN=sun-unix, 
OU=SUN  OpenSSO Enterprise, O=Sun, C=US</Value>
</AttributeValuePair>
</Subject>
<Subject name="au" type="AuthenticatedUsers" includeType="inclusive">
</Subject>
<Subject name="ldaporganization" type="Organization" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
<Value>dc=red,dc=iplanet,dc=com</Value>
</AttributeValuePair>
</Subject>
<Subject name="ldapuser" type="LDAPUsers" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
<Value>uid=amAdmin,ou=People,dc=red,dc=iplanet,dc=com</Value>
</AttributeValuePair>
</Subject>
<Subject name="ldaprole" type="LDAPRoles" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
<Value>cn=Organization Admin Role,o=realm1,dc=red,dc=iplanet,dc=com</Value>
</AttributeValuePair>
</Subject>
<Subject name="ldapgroup" type="LDAPGroups" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
<Value>cn=g1,ou=Groups,dc=red,dc=iplanet,dc=com</Value>
</AttributeValuePair>
</Subject>
<Subject name="amidentitysubject" type="AMIdentitySubject" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
<Value>id=amAdmin,ou=user,dc=red,dc=iplanet,dc=com</Value>
</AttributeValuePair>
</Subject>
</Subjects>
<Conditions name="conditions" description="description">
<Condition name="ldapfilter" type="LDAPFilterCondition">
<AttributeValuePair><Attribute name="ldapFilter"/>
<Value>dept=finance</Value>
</AttributeValuePair>
</Condition>
<Condition name="authlevelge-nonrealmqualified" type="AuthLevelCondition">
<AttributeValuePair><Attribute name="AuthLevel"/>
<Value>1</Value>
</AttributeValuePair>
</Condition>
<Condition name="authlevelle-realmqaulfied" type="LEAuthLevelCondition">
<AttributeValuePair><Attribute name="AuthLevel"/>
<Value>/:2</Value>
</AttributeValuePair>
</Condition>
<Condition name="sessionproperties" type="SessionPropertyCondition">
<AttributeValuePair><Attribute name="valueCaseInsensitive"/>
<Value>true</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="a"/><Value>10</Value>
<Value>20</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="b"/><Value>15</Value>
<Value>25</Value>
</AttributeValuePair>
</Condition>
<Condition name="activesessiontime" type="SessionCondition">
<AttributeValuePair><Attribute name="TerminateSession"/>
<Value>session_condition_false_value</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="MaxSessionTime"/>
<Value>30</Value>
</AttributeValuePair>
</Condition>
<Condition name="authelevelle-nonrealmqualfied" 
           type="LEAuthLevelCondition">
<AttributeValuePair><Attribute name="AuthLevel"/>
<Value>2</Value>
</AttributeValuePair>
</Condition>
<Condition name="ipcondition" type="IPCondition">
<AttributeValuePair><Attribute name="DnsName"/>
<Value>*.iplanet.com</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="EndIp"/>
<Value>145.15.15.15</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="StartIp"/>
<Value>120.10.10.10</Value>
</AttributeValuePair>
</Condition>
<Condition name="authchain-realmqualfied"
          type="AuthenticateToServiceCondition">
<AttributeValuePair><Attribute name="AuthenticateToService"/>
<Value>/:ldapService</Value>
</AttributeValuePair>
</Condition>
<Condition name="auth to realm" 
      type="AuthenticateToRealmCondition">
<AttributeValuePair><Attribute name="AuthenticateToRealm"/>
<Value>/</Value>
</AttributeValuePair>
</Condition>
<Condition name="authlevelge-realmqualified"
      type="AuthLevelCondition">
<AttributeValuePair><Attribute name="AuthLevel"/>
<Value>/:2</Value>
</AttributeValuePair>
</Condition>
<Condition name="authchain-nonrealmqualfied" 
     type="AuthenticateToServiceCondition">
<AttributeValuePair><Attribute name="AuthenticateToService"/>
<Value>ldapService</Value>
</AttributeValuePair>
</Condition>
<Condition name="timecondition" type="SimpleTimeCondition">
<AttributeValuePair><Attribute name="EndTime"/>
<Value>17:00</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="StartTime"/>
<Value>08:00</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="EndDate"/>
<Value>2006:07:28</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="EnforcementTimeZone"/>
<Value>America/Los_Angeles</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="StartDay"/>
<Value>mon</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="StartDate"/>
<Value>2006:01:02</Value>
</AttributeValuePair>
<AttributeValuePair><Attribute name="EndDay"/>
<Value>fri</Value>
</AttributeValuePair>
</Condition>
</Conditions>
<ResponseProviders name="responseproviders"
       description="description">
<ResponseProvider name="idresponseprovidere" 
     type="IDRepoResponseProvider">
<AttributeValuePair>
<Attribute name="DynamicAttribute"/>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="StaticAttribute"/>
<Value>m=10</Value>
<Value>n=30</Value>
</AttributeValuePair>
</ResponseProvider>
</ResponseProviders>
</Policy>
</Policies>
    Note –

    The Value element of the following subject attributes takes the full DN:

    • SubrealmReferral

    • PeerRealmReferral

    • Realm

    • IdentityServerRoles

    • LDAPGroups

    • LDAPRoles

    • LDAPUsers

  2. Add the defined policies to OpenSSO Enterprise using ssoadm with the XML file as input.


    ssoadm create-policies --realm realm-name --xmlfile 
policy-xml-filename --adminid administrator-id 
--password-file password-filename

    For more information, see Chapter 1, ssoadm Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference.

ProcedureTo Create a Policy Using the OpenSSO Enterprise Console

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator.

  1. Under the Access Control tab, click the name of the realm for which you are creating policy.

  2. Click the Policies tab.

  3. Click New Policy.

  4. Enter a name for the policy.

  5. (Optional) Enter a description of the policy.

  6. (Optional) Select Yes to activate the policy.

    It is not necessary to define all of the policy's fields at this time. You may choose to add Rules, Subjects, Conditions, and Response Providers later. See Modifying Policies and Referrals for information on these component's attributes.

  7. Click OK.

ProcedureTo Create a Referral Using the OpenSSO Enterprise Console

In order to create policies for peer realms or sub realms, you must first create a referral in the parent (or peer) realm pointing to the appropriate peer or sub realm. The Rule definition in the referral must contain the location of the resource(s) that will be managed. Once the referral is created, policies can be created for the appropriate peer or sub realm.

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator.

  1. Under the Access Control tab, click the name of the realm in which you are creating the referral.

    This might be the / Top Level Realm or a sub realm.

  2. Click the Policies tab.

  3. Click New Referral.

  4. Enter a name for the referral.

  5. (Optional) Enter a description of the referral.

  6. (Optional) Select Yes to activate the referral.

  7. Click New under Rules.

  8. Select the appropriate Service Type and click Next.

    This value can not be changed once the Rule has been created. The options are:

    • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

    • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

    • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case.

    You may see a larger list if more services are enabled for the policy. (See Enabling Policy in a Service.) For more information, see Rules.

  9. Add a Name for the Rule.

  10. Add a URL as the value for Resource Name and click Finish.

    In this procedure, o=example.com is the sub realm that manages access to http://www.example.com and its sub-resources.

  11. Click New under Referral.

  12. (Optional) Select the Referral Type and click Next.

    The choices are Peer Realm or Sub Realm. This page is displayed only when the realm in which you are creating the referral has both peer and sub realms. It will not be displayed, for example, when creating a referral in the / Top Level Realm because all realms are sub to the / Top Level Realm.

  13. Enter a name for the referral.

  14. Select the realm to which you are referring policy management from the drop down list and click Finish.

  15. Click Save to update.

  16. Navigate to the sub realm to create policy.

    Now that policy management for the resource is referred to the peer or sub realm, policies can be created to control access for http://www.example.com or any resource starting with http://www.example.com. See To Add Multiple Policies Using the ssoadm Command Line Utility or To Create a Policy Using the OpenSSO Enterprise Console.

Modifying Policies and Referrals

Once a policy or referral is created, you can modify its components using the OpenSSO Enterprise console. Policies cannot be modified directly with ssoadm; you must first delete the policy before adding a modified version of it back. The following sections contain procedures on how to modify policies or referrals.

Modifying Policies

You can modify a policy that has already been created. To Modify a Policy describes the procedure to change or delete a policy.

ProcedureTo Modify a Policy

Before You Begin

This procedure assumes:

  1. Under the Access Control tab, click the name of the realm in which the policy you are modifying was created.

  2. Click the Policies tab.

  3. Click the name of the policy you are modifying.

    The policy's component page is displayed.

  4. Under the Rules menu, click New.

    You can click the name of a Rule that has already been defined. The Rules attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Rule and delete it.

  5. Select a Service Type for the rule.

    This value can not be changed once the Rule has been created. The options are:

    • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

    • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

    • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case of OpenSSO Enterprise policies.

    You may see a larger list if more services are enabled for the policy. (See Enabling Policy in a Service.) For more information, see Rules.

  6. Click Next to display the New Rule page and modify the following components.

    1. Enter a Name for the Rule.

    2. Enter a Resource Name for the rule.

      Currently, policy agents only support http:// and https:// resources thus the value should be a URL. IP addresses are not supported. Wildcards are supported for protocol, host, port and resource name. For example:


      http*://*:*/*.html

      For the URL Policy Agent service type, the default port number is 80 for http:// and 443 for https:// if no port number is defined.

    3. Select the appropriate value for each Action.

      Actions displayed are dependent on the chosen Service Type. See Rules for an explanation of each Action.

    4. Click Finish to return to the policy's components page.

  7. Under the Subjects menu, click New.

    You can also click the name of a Subject that has already been defined. The Subject attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Subject and delete it.

  8. Select a Subject Type and click Next.

    This value can not be changed once Subjects has been created. The options are:

    • Authenticated Users implies that any user with a valid SSOToken is a member.

    • OpenSSO Identity Subject implies that the identities defined under the Subjects tab of a particular realm can be added as a member.

    • Web Services Clients implies that a WSC identified by a valid SSOToken is a member IF the Distinguished Name (DN) of any principal contained in the SSOToken matches any value of this subject.

    For more information, see Subjects.

  9. Enter a Name for the Subject.

  10. Select whether the Subject is Exclusive.

    If this field is not selected (default), the policy applies to the identity that is a member of the subject. If the field is selected, the policy applies to the identity that is not a member of the subject. If multiple subjects exist in the policy, the policy applies to the identity when at least one of the subjects implies that the policy applies to the identity.

  11. If applicable to the selected Subject Type, choose entries to add for the subject.

    1. Perform a search to display qualified entries.

      The default (*) search pattern will display all qualified entries. Select the individual identities you wish to add for the subject, or click Add All to add all of the identities at once. Click Add to move the identities to the Selected list.

    2. Select an individual entry and click Add to move it to the Selected list.

      Alternately, click Add All to add all of the entries at once.

  12. Click Finish to return to the policy's components page.

  13. Under the Conditions menu, click New.

    You can also click the name of a Condition that has already been defined. The Conditions attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Condition and delete it.

  14. Select a Condition Type and click Next.

  15. Enter values for the Condition Type's listed attributes.

    For more information, see Conditions.

  16. Click Finish to return to the policy's components page.

  17. Under the Response Provider menu, click New.

    You can also click the name of a Response Provider that has already been defined. The Response Provider attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Response Provider and delete it.

  18. Enter a Name for the Response Provider.

  19. Define the following values:

    Static Attribute

    These are static attributes defined in an instance of IDResponseProvider stored in the policy. The value takes the format attribute=value.

    Dynamic Attribute

    The response attributes chosen here need to first be defined in the Selected Dynamic Response Attributes field of the Policy Configuration Service for the corresponding realm. The attribute names defined should be a subset of those existing in the identity repository. To select specific or multiple attributes, hold the Control key and click the left mouse button. For details, see Policy Configuration in Sun OpenSSO Enterprise 8.0 Administration Reference.

  20. Click Finish.

  21. Click Save to update the policy.

Modifying Referrals

You can modify the components of a referral that has already been created. To Modify a Referral describes the procedure to change or delete a referral.

ProcedureTo Modify a Referral

Before You Begin

This procedure assumes:

  1. Under the Access Control tab, click the name of the realm in which the policy you are modifying was created.

  2. Click the Policies tab.

  3. Click the name of the referral you are modifying.

    The referral's component page is displayed.

  4. Under the Rules menu, click New to display the New Rule page and modify as follows.

    You can click the name of a Rule that has already been defined. The Rules attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Rule and delete it.

    1. Select the appropriate Service Type and click Next.

      This value can not be changed once the Rule has been created. The options are:

      • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

      • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

      • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case.

      You may see a larger list if more services are enabled for policy. (See Enabling Policy in a Service.) For more information, see Rules.

    2. Add a Name for the Rule.

    3. Add a URL as the value for Resource Name and click Finish to return to the referral's components page.

      Currently, policy agents only support http:// and https:// resources thus the value should be a URL. IP addresses are not supported. Wildcards are supported for protocol, host, port and resource name. For example:


      http*://*:*/*.html

      For the URL Policy Agent service type, the default port number is 80 for http:// and 443 for https:// if no port number is defined. In this example, o=example.com is the sub realm that manages access to http://www.example.com and its sub-resources.

  5. Under the Referrals menu, click New.

    You can click the name of a Referral that has already been defined. The Referrals attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Referral and delete it.

  6. Enter a Name for the Referral.

  7. Specify a filter and click Search.

    This action defines the realm names that will be displayed in the Value field. By default, it will display all realm names.

  8. Select the realm to which you are referring policy administration from the drop down list.

  9. Click Finish to return to the referral's components page.

  10. Click Save to update the referral.

Using Wild Cards in Policies

The Policy Service supports policy definitions using an asterisk (*) as the wild card. Only * is supported as a wild card and it can not be escaped as in \*. A * must:

The following wild card matching rules assume the wildcard character is * and the delimiter character is /.

Applying Policy Logic

All of the following should be satisfied for a policy to be applicable to a request.

Sometimes policies collide. When this happens, the following rules take effect.

Enabling Policy in a Service

You can protect services using the OpenSSO Enterprise Policy Service only if the service schema configures to the sms.dtd and contains values for the <Policy> schema and sub elements. If you want to create a custom policy agent or require more fine-grained enforcement than the OpenSSO Enterprise Policy Service offers, you can add the <Policy> schema to an OpenSSO Enterprise formatted service file, enabling it for interaction with your policy agent and the Policy Service. (For more information, see Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers.) Once enabled, the service will be displayed as a Service Type when creating policies and referrals. (See Rules.)

Tip –

By default, OpenSSO Enterprise policy agents protect only URL resources in tandem with the URL Policy Agent Service (for which a policy evaluator is created and used to get policy decisions). The most common scenario is to use the policy agents developed specifically for OpenSSO Enterprise and the URL Policy Agent Service. For more information, see Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents or Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

To Add a New Policy Enabled Service contains more information.

ProcedureTo Add a New Policy Enabled Service

  1. Develop the new service in an XML file based on the sms.dtd.

    amWebAgent.xml is the XML service file for the URL Policy Agent service and can be used as a template to create a policy-enabled service file. It is located in the templates directory of the exploded opensso.zip. Here is another sample template.

    <?xml version="1.0" encoding="ISO-8859-1"?>

<!--
Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved
Use is subject to license terms.
-->




<!DOCTYPE ServicesConfiguration
  PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
  "jar://com/sun/identity/sm/sms.dtd">

<ServicesConfiguration>
  <Service name="SampleWebService" version="1.0">
     <Schema 
        i18nFileName="SampleWebService" 
        i18nKey="SampleWebService">

  <Policy>
	<AttributeSchema name="GET"
          type="single"
          syntax="boolean"
          uitype="radio"
          i18nKey="get">
            <IsResourceNameAllowed/>
               <BooleanValues>
                 <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                 <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
               </BooleanValues>
	</AttributeSchema>

	<AttributeSchema name="POST"
	      type="single"
        syntax="boolean"
        uitype="radio"
		    i18nKey="post">
		      <IsResourceNameAllowed/>
             <BooleanValues>
                <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
             </BooleanValues>
	</AttributeSchema>

	<AttributeSchema name="PUT"
		    type="single"
        syntax="boolean"
        uitype="radio"
		    i18nKey="put">
		      <IsResourceNameAllowed/>
             <BooleanValues>
                <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
             </BooleanValues>
	</AttributeSchema>

	<AttributeSchema name="DELETE"
		    type="single"
        syntax="boolean"
        uitype="radio"
		    i18nKey="delete">
		      <IsResourceNameAllowed/>
             <BooleanValues>
                <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
             </BooleanValues>
	</AttributeSchema>

    </Policy>
    </Schema>
  </Service>
</ServicesConfiguration>

  2. Save the XML file to the /config/xml/ directory of the exploded opensso.zip.

    For example, /config/xml/newServiceWithPolicy.xml

  3. Load /config/xml/newServiceWithPolicy.xml using the ssoadm command line utility.

    See Chapter 1, ssoadm Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

  4. Define policy to protect the resource as documented in Creating Policies and Referrals.

Authenticating Based on Resource

In a typical authentication scenario, if a user attempts access to a web resource without authentication credentials, the policy agent redirects the user to the default OpenSSO Enterprise authentication module login page even if the resource is protected by a different authentication module. Thus, the user must authenticate to both modules. The Gateway servlet provides resource authentication which allows the user to bypass the default authentication module and authenticate against the module protecting the resource only.

The Gateway servlet has the following limitations:

To use resource authentication, you must make ensure certain configurations on the web container installed on the resource server machine as well as make configurations to OpenSSO Enterprise and the policy agent.

ProcedureTo Configure Resource Authentication

Once both OpenSSO Enterprise and a policy agent have been installed and profile has been created for the policy agent, resource-based authentication can be configured. To do this, it is necessary to point OpenSSO Enterprise to the Gateway servlet.

Before You Begin

Ensure the following configurations on the web container installed on the resource's server machine. Check your container's documentation for more information.

  1. Log in to the OpenSSO Enterprise console as administrator; by default, amadmin.

  2. Under the Configuration tab, click Authentication.

  3. Click the Certificate Service Name.

  4. Enable Match Certificate in LDAP by checking the box.

  5. Select Subject UID as the value for Certificate Field Used to Access User Profile.

  6. Enter 54430 as a value for SSL Port Number.

    This port number must match the port number used for the web container's SSL client authentication listener port.

  7. Type 2 as the value for the Authentication Level attribute.

    The value used must be greater that the level defined for LDAP authentication.

  8. Click Save.

  9. Click Back to Service Configuration.

  10. Under the Access Control tab, click the name of the realm to which the policy agent belongs.

  11. Click the Policies tab and add policies as follows.

    • Policy 1 has a condition of LDAP authentication only for http://agent-machine.domain/banner.html.

    • Policy 2 has a condition of Certificate authentication only for http://agent-machine.domain/banner2.html

    • Policy 3 has a condition of LDAP authentication and a level of Certificate authentication for http://agent-machine.domain/banner3.html.

  12. Click the Agents tab.

  13. Click on the Web or J2EE tab depending on the agent being used.

  14. Click on the Agent Profile name of the policy agent.

  15. Under OpenSSO Services, enter the following URL as the value of the OpenSSO Login URL attribute:

    http://OpenSSO Enterprise_host.domain:port/opensso/gateway

  16. Add the following line to the file:

    com.sun.am.policy.am.loginURL = http://OpenSSO Enterprise_host.domain:port/opensso/gateway

    Note –

    The gateway servlet is developed using the Policy Evaluation APIs and can be used to write a custom mechanism to accomplish resource-based authentication. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide.