Sun Java System Identity Server 2004Q2
Sample
 

Policy Samples

This document explains how to use the policy samples in <install-dir>/SUNWam/samples/policy directory. The samples are provided to perform following tasks.
  • Add a new service which has a policy schema to the Identity Server;
  • Develop and add custom developed Subjects, Referrals, Conditions to Identity Server;
  • Create policies using amadmin command; and
  • Develop and run Policy Evaluation programs.
  • Construct policies programmatically and add them to the policy store
Several samples are provided in policy samples directory.

To run Policy Evaluation program for iPlanetAMWebAgentService service (URL policy agent service),  run step I. and V.
To run Policy Evaluation program for the sample service, SampleWebService, run step I., II., IV. and V.
To run Policy Evaluation program for iPlanetAMWebAgentService service and sample Subject, Condition and Referral implementations, run step I., III. and V.
To run Policy Evaluation program for SampleWebService; and sample Subject, Condition and Referral implementations, run step I., II., III., IV. and V.
To create policies for iPlanetAMWebAgentService using amadmin tool, run step IV.
To create policies for SampleWebService using amadmin tool, run step I. and IV.
To construct policies programmatically and add them to policystore,  run step I., and VI.

The steps to perform above tasks are explained below.

I. Compile the Samples and change the root suffix in the sample files

Samples can be run both on Solaris and Windows. To compile the samples, follow these steps.

  1. Set these variables in the "Makefile"
    • BASE - Set this to refer <install dir>/SUNWam
    • JAVA_HOME - Set this variable to your installation of JDK. The JDK should be newer than JDK 1.3.1.
    • CLASSPATH - Set this variable to refer to all the jars
  2. Compile the sample program, run gmake all on Solaris and run make on Windows.

           In the sample files, root suffix DNs are specified as "dc=example,dc=com", replace them with the correct value.

II. Add a new policy service to Identity Service

By default, IS has only one service that has a policy schema, iPlanetAMWebAgentService. This service corresponds to URL policy agent service (services are defined in an XML file, iPlanetAMWebAgent service is specified in <install-dir>/SUNWam/config/xml/amWebAgent.xml). Additional services containing policy schema can be loaded to IS. The samples provide a new service that has policy schema, SampleWebService to add to IS. Run the amadmin command to load that service.
    <install-dir>/SUNWam/bin/amadmin
--runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
--password <password>
--schema <install-dir>/SUNWam/samples/policy/SampleWebService.xml
To add your own service that uses policy, develop the service XML file in the lines of amWebAgent.xml or SampleWebService.xml based on <install-dir>/SUNWam/dtd/sms.dtd. Once the new service is added, rules can be defined for the new service in policy definitions.

 

III. Develop and add custom developed Subjects, Conditions and Referrals

The Policy JAVA API provides several interfaces. The Subject, Condition and Referral interfaces let you develop your own custom subjects, conditions and referrals. A sample implementation is provided for those three interfaces. SampleSubject.java implements the Subject interface. This subject applies to all the authenticated users, those who have valid SSOTokens. SampleCondition.java implements the Condition interface. This condition makes the policy applicable to those users whose user's name length is greater than or equal to the length specified in the condition.

SampleReferral.java implements the Referral interface.  It gets the referral policy decision from a text file SampleReferral.properties located in the samples directory.

The subject, condition and referral implementations need to be added to iPlanetAMPolicyService and iPlanetAMPolicyConfigService in order to make them available for policy definitions. These services are loaded in IS during installation. To add the sample implementations to the policy framework, we need to modify the iPlanetAMPolicy service and iPlanetAMPolicyConfig service. Follow the steps below to modify the services:

  • Back up iPlanetAMPolicy and iPlanetAMPolicyConfig services using db2ldif
cd <directory_install_root>/slapd-<hostname>
db2ldif -n userRoot -s "ou=iPlanetAMPolicyService,ou=services,<root_suffix>"
db2ldif -n userRoot -s "ou=iPlanetAMPolicyConfigService,ou=services,<root_suffix>"
  • On Solaris, add <install-dir>/SUNWam/ldaplib/ldapsdk to the environment variable LD_LIBRARY_PATH.  Don't need to set the variable on Windows2000. Then do the following.
       cd <install-dir>/SUNWam/samples/policy
       <install-dir>/SUNWam/bin/ldapmodify -D"cn=directory manager" -w <password> -a -c -f samples.ldif
       <install-dir>/SUNWam/bin/amadmin --runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>" 
              --password <password>  --data amPolicyConfig_mod.xml

  • Change the properties files of these two services
cd <install-dir>/SUNWam/locale
mv amPolicy.properties amPolicy.properties.bak
mv amPolicy_en.properties amPolicy_en.properties.bak
mv amPolicyConfig.properties amPolicyConfig.properties.bak
mv amPolicyConfig_en.properties amPolicyConfig_en.properties.bak
cp <install-dir>/SUNWam/samples/policy/amPolicy.properties .
cp <install-dir>/SUNWam/samples/policy/amPolicy_en.properties .
cp <install-dir>/SUNWam/samples/policy/amPolicyConfig.properties .
cp <install-dir>/SUNWam/samples/policy/amPolicyConfig_en.properties .
  • Deploy the sample plugins.
             Copy SampleSubject.class, SampleCondition.class and SampleReferral.class from the sample directory to       <install-dir>/SUNWam/lib.
  • Restart the IS server.
The sample subject, condition and referral implementations are now available for policy definitions through administration console or amadmin tool.

 

IV. Create policies for the service

The policies are administered through Admin Console or through amadmin command. However policies can't be modified using amadmin command. One must delete the policy and add the modified policy using amadmin. To add policies using amadmin, policy XML file must be developed following <install dir>/SUNWam/dtd/policy.dtd. Once the policy XML file is developed, you can use the following command to load the policy XML file.
<install-dir>/SUNWam/bin/amadmin
--runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
--password <password>
--data <policy.xml>
In the policy samples directory, there are two sample policy XML files. They define policies for SampleWebService service. SamplePolicy.xml defines a normal policy for SampleWebService with a SampleSubject and a SampleCondition. SamplereferralPolicy.xml defines a referral policy for SampleWebService with a SampleReferral.

You must run step II. and step III. to load policies present in these XML files.

<install-dir>/SUNWam/bin/amadmin
--runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
--password <password>
--data <install-dir>/SUNWam/samples/policy/SamplePolicy.xml

<install-dir>/SUNWam/bin/amadmin
--runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
--password <password>
--data <install-dir>/SUNWam/samples/policy/SampleReferralPolicy.xml
You can verify the newly added policies in Administration Console.

 

V. Develop and run Policy Evaluation Programs.

The Policy API provides Policy Evaluation API. This API has one java class, PolicyEvaluator. The package for this class is com.sun.identity.policy.PolicyEvaluator. The samples provide a sample policy evaluator program, PolicyEvaluation.java. This program can be used to run policy evaluations for different services. The policy evaluation is always based on a service such as iPlanetAMWebAgentService, SampleWebService, etc.

The sample policy evaluation program uses PolicyEvaluation.properties file. Specify the input for the evaluation program in this file such as service name, action names, condition environment parameters, user name, user password, etc.

Following properties can be set as input to the evaluation program in PolicyEvaluation.properties:

  • Set the value of pe.servicename to the service name (iPlanetAMWebAgentService or SampleWebService).
  • Set the pe.resoucename to the resource name that you want to evaluate the policy against.
  • Specify the action names in the pe.actionnames, separate the action names with ':'. If you want to get all the action values, you can simply leave the pe.actionnames as blank.
  • Set other required properties like pe.username, pe.password.
  • Set optional properties pe.authlevel, pe.authscheme, pe.requestip, pe.dnsname, pe.time if you use the corresponding conditions in your policy definitions.
Set up the policies before running in the policy evaluation program. To run the policy evaluation program, use the following steps:
  1. On Solaris set environment variable LD_LIBRARY_PATH to /usr/lib/mps/secv1.
    Don't need to set the variable on Windows2000.
  2. Run the evaluation sample program, do gmake run on Solaris or do make run on Windows2000.
The policy decision from the policy evaluation program is then displayed on the terminal.

 

VI. Construct policies programmatically and add them to policy store

The Policy API provides Policy Management API that lets you create, add, update and remove policies programmatically.  This sample program PolicyCreator.java, shows how to construct policies programmatically and add them to policy store.  One normal policy policy1 and one referral policy refpolicy1 are constructed and added to the policy store.  The normal policy has one subject of each subject type and one condition of each condition type shipped out of box with S1IS.

To run the sample program PolicyCreator.java:

  • Compile sample Java programs.  See step I. above
  • On Solaris set environment variable LD_LIBRARY_PATH to /usr/lib/mps/secv1.
    Don't need to set the variable on Windows2000.
  • Create sub organization org1, user user1, group group1 and role role1 in your top level organization, using console.
  • Set values of following properties in PolicyEvaluation.properties file:
  • pe.orgname - DN of the top level organazation
    pe.username - userid to authenticate as
    pe.password - password to use to authenticate
  • Do gmake createPolicies on Solaris or do make createPolicies on Windows2000.
  • Check using console checks that policies policy1 and refpolicy1 are added