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.
- 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
- 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 .
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:
- On Solaris set environment variable
LD_LIBRARY_PATH
to /usr/lib/mps/secv1 .
Don't need to set the variable on Windows2000.
- 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 :
|