Sun Java System Access Manager version 7 2005Q4

Policy Samples

    1. Introduction

    This document explains how to use the policy samples in
    <BASE_DIR>/samples/policy directory. The
    <BASE_DIR> is <INSTALL_DIR>/SUNWam on Solaris; 
    it is <INSTALL_DIR>/identity on Linux.
    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 Linux. To compile the samples,
    follow these steps.
    
    1. Set these variables in the Makefile
       
       BASE - Set this to refer <BASE_DIR>
       JAVA_HOME - Set this variable to your installation of JDK.
       The JDK should be newer than JDK 1.4
       CLASSPATH - Set this variable to refer to all the jars
       
    
    2. To compile the sample program, run gmake all.
    


    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

    A service 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.           
    
    <BASE_DIR>/bin/amadmin
        --runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
	--password <password>
	--schema <BASE_DIR>/samples/policy/SampleWebService.xml
    
    Then copy the properties file SampleWebService.properties to the locale
    directory of the Access Manager installation.
    
      cp SampleWebService.properties <BASE_DIR>/locale
    
    To add your own service that uses policy, develop the service XML file in
    the lines of /etc/opt/SUNWam/config/xml/amWebAgent.xml
    (/etc/opt/sun/identity/config/xml/amWebAgent.xml on Linux)
    or SampleWebService.xml based on
    <BASE_DIR>/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 /usr/lib/mps/secv1 to the environment variable LD_LIBRARY_PATH. 
      On Linux, add /opt/sun/private/lib to the environment variable LD_LIBRARY_PATH.
      Then do the following.
      
      cd <BASE_DIR>/samples/policy
      <BASE_DIR>/bin/amadmin
          --runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>
          --password <password> 
          --schema amPolicy_mod.xml
      <BASE_DIR>/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 <BASE_DIR>/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 <BASE_DIR>/samples/policy/amPolicy.properties .
      cp <BASE_DIR>/samples/policy/amPolicy_en.properties .
      cp <BASE_DIR>/samples/policy/amPolicyConfig.properties .
      cp <BASE_DIR>/samples/policy/amPolicyConfig_en.properties .
      
    
    * Deploy the sample plugins.
      Copy SampleSubject.class, SampleCondition.class and
      SampleReferral.class from the sample directory to
      <BASE_DIR>/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 <BASE_DIR>/dtd/policy.dtd. Once the policy
    XML file is developed, you can use the following command to load the policy
    XML file.               
    
    <BASE_DIR>/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.
    
    <BASE_DIR>/bin/amadmin
        --runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
	--password <password>
	--data <BASE_DIR>/samples/policy/SamplePolicy.xml
    <BASE_DIR>/bin/amadmin
	--runasdn "uid=amAdmin,ou=People,<default_org>,<root_suffix>"
	--password <password>
	--data <BASE_DIR>/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 add /usr/lib/mps/secv1 to the environment variable LD_LIBRARY_PATH. 
      On Linux, add /opt/sun/private/lib to the environment variable LD_LIBRARY_PATH.
    
    2. To run the evaluation sample program, do gmake run.
    


    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 add /usr/lib/mps/secv1 to the environment variable LD_LIBRARY_PATH. 
      On Linux, add /opt/sun/private/lib to the environment variable LD_LIBRARY_PATH.
    
    * Create sub realm realm1, user user1, group group1
      and role role1 in your root realm , using console.
    
    * Set values of following properties in PolicyEvaluation.properties file:
      
      pe.realmname - DN of the root realm
      pe.username - userid to authenticate as
      pe.password - password to use to authenticate
    
    * Do gmake createPolicies.
    
    * Check using console checks that policies policy1 and refpolicy1 are
       added.



End of Sample

