Sun Java System Access Manager version 6 2005Q1
Sample
 

Main Page

Policy Samples


1. Introduction

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 Access Manager;
  • Develop and add custom developed Subjects, Referrals, Conditions to Access Manager;
  • Create policies using amadmin command;
  • Develop and run Policy Evaluation programs; and
  • 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.


2. Steps

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, Access Manager 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 Access Manager. The samples provide a new service that has policy schema, SampleWebService to add to Access Manager. 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 Access Manager 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 Access Manager 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 Administration Console or through amadmin command. However policies canmot 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. If you don't want to set these enviromnent parameters, just leave their values as blank. The property pe.authlevel is used to evaluate AuthLevel Condition. It takes a non-negative integer. The property pe.authscheme is used to evaluate AuthScheme Condition. It takes a set of ':' separated AuthScheme names. The property pe.requestip is used to evaluate IP Condition. It takes an IP address string. The property pe.dnsname is used to evaluate IP Condition as well. It takes a set of ':' separated DNS names. The property pe.time is used to evaluate Simple Time Condition. It specifies the request time in milliseconds. If its value is set to currenttime, then it takes the current time in milliseconds.

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 Access Manager.

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.


End of Sample