Policy Managers Guide

Importing and Exporting Policy Data

This section covers the following topics:

Introduction

The AquaLogic Enterprise Security Administration Server includes two tools to assist you in managing the contents of the policy store: an import tool and an export tool. Using these tools you can perform the following tasks:

Define your policy data in text files that are external to the Administration Server and import those files to a policy store on any Administration Server.
Export policy data from an existing policy store on an Administration Server and import that policy data to a policy store on any Administration Server.
Export policy data from an existing policy store on an Administration Server, install a newer version of the server software, and re-import the policy data into the upgraded server.

Creating Policy Data Files for Importing

In addition writing policy using the Administration Console or the Business Logic Manager, you may also write policy by creating and importing policy data files. To use policy data files to import policy, you must enter the policy data in a text file. When you view policy data in Administration Console, you are viewing its external representation. However, internally, policy data names are represented with certain prefixes or suffixes. You must use this internal representation when you create policy data files.

This following topics describe how to create policy data files:

Policy Element Naming

The policy language uses standard naming conventions called qualifiers to refer to privileges, applications, resources, roles, and identity elements (directories, users and groups). These conventions ensure that each component has a unique name, even if you use the same name in other locations. The Administration Console hides these qualifiers from you during most operations. See Fully Qualified Names for additional information on naming conventions.

The following rules apply to policy element names:

Most names are case sensitive. Declarations and attribute names are the exception; they are case insensitive. Internally, when a declaration name or attribute name is saved, it is saved in all lowercase. For example, the user names //user/ales/system/ and //user/ales/System/ reflect the same user.
A qualified name is a name with qualifier prefix prepended to the non-qualified name. Some names, like user and group names, have an ending suffix also. See Table 4-1 for examples. Declaration names do not have a qualified form.
The characters used for the names and the length of the names are restricted (see Size Restriction on Policy Data).

Table 4-1 Examples of Qualified Names

Policy Element	Example
resource	`//app/policy/banking/transfer`
directory	`//dir/extranet`
privilege	`//priv/place_order`
privilege group	`//grp/trading_privileges`
user	`//user/extranet/JohnDoe/`
group	`//sgrp/extranet/trader/`
role	`//role/roleName`
logical name	`//ln/ShortHandForResource`

For more information on policy element naming, see the following topics:

Fully Qualified Names

A fully qualified name references the full name for a policy element. This name consists of a series of simple names separated by forward slashes (/). Fully qualified names have the following parts, in order:

A starting double forward slash: //
A qualifier followed by a forward slash
For users and groups, a directory name followed by a slash mark, and a final slash after the name
A name:

For example, in //user/Accounting/JJBob/

user is the qualifier

Accounting is the directory

JJBob is the user name

For resources, the qualified name either starts with //app/policy/. Additional names may appear, each separated by a single slash. This naming convention defines the resource tree. Each resource name is represented as a node on the tree, but the entire string represents the fully qualified name of the final resource. For example:

//app/policy/trading_system/PersonalTrades/BondOrder/Order

Policy Element Qualifiers

Qualifiers are built in. You cannot create your own qualifier or change the existing ones. They represent one of the basic policy elements and always begin with a double slash (//) followed by a single slash (/). Table 4-2 lists the built-in qualifiers.

Table 4-2 Policy Element Qualifiers

Qualifier	Policy Element
//p`riv`	privilege
//g`rp`	privilege group
//u`ser`	user
//sgrp	group
//a`pp`	resource
//d`ir`	directory
//bind	engine
//role	role
//ln	logical name

There is no qualifier for a declaration. Declarations are identified by a different method. For a discussion of Declarations, see Declaration Names.

Size Restriction on Policy Data

There are some limits on the size of names, attribute values, and rules, restricted by the type of database that you use. The restriction by the database is determined by the VARCHAR column size and the key size allowed by the database. Table 4-3 summarizes the limit for different policy data and different databases.

Table 4-3 Database Restrictions on Policy Data

Policy Data	Oracle	Sybase 12.5 2K¹	Sybase 12.5 4K	Sybase 12.5 8K	Sybase 12.5 16K
Qualified privilege name Qualified privilege group name Qualified role name Qualified resource name Qualified user name Qualified subject group name Qualified logical name Qualified security provider name	2000	580	1200	2500	5000
All privileges in the privilege field of a rule All roles in the privilege field of a rule All resources in the object field of a rule All user and group in subject field of a rule All roles in subject field of a rule	2000	580	1200	2500	5000
Rule conditions	4000	1160	2400	5000	10000
Rule text-combined text of all fields in a rule (privilege, object, subject, delegator, and conditions, plus the syntax delimiters)	N/A²	1962	4010	8106	16298
Declaration name Attribute name The individual declaration name inside a type declaration	2000	580	1200	2500	4000
Declaration text-the combined text of declaration name, kind, and value, plus the syntax delimiters	4000	1160	2400	5000	10000
A single attribute value	2000	580	1200	2500	4000
A quoted literal string in the declaration value	4000	1160	2400	4000	4000
A quoted literal string in a constraint for a rule	4000	1160	2400	4000	4000
A qualified name in the declaration value	2000	580	1200	2500	4000
A qualified name in a constraint for a rule	2000	580	1200	2500	4000
Integer value of a constant declaration	9 digits*³	9 digits*	9 digits*	9 digits*	9 digits*
All attribute values combined for a user, group or resource attribute	40000	40000	40000	40000	40000

1. Sybase 12.5 has a dependency on the logical page size that you choose when you set up the database server. The supported logical page size varies from 2K, 4K, 8K, and 16K.

2. N/A means that there is no limit.

3. An asterisk (*) indicates that the limit is imposed.

Character Restrictions in Policy Data

There are several restrictions on the character set that you can use to define policy data. The following common rules apply and Table 4-4 describes the extended character set restrictions.

Because AquaLogic Enterprise Security does not support internationalization, the character set used in policy data is ISO 8859-1 (Latin-1), Western European eight-bit character set.
All names without qualifier or called non-qualified names allow alphanumeric characters (a-z, A-Z, and 0-9) and the underscore (_). These names include privilege name, privilege group name, role name, resource name, user name, subject group name, directory name, logical name, security provider name, declaration, and attribute name.
All names, except user and subject group name, must start with an alpha character or underscore. Numeric characters are not allowed.

Table 4-4 Policy Data Character Restrictions

Policy data	Extra characters allowed
Resource name	Pound sign (#), apostrophe (\Q), dash (-), period (.), colon (:), at (@), tilda (~), ampersand (&).
User name or Subject group name	The name can include any other printable characters, such as space, period, and dollar sign, etc. A forward slash (/) in the name must be escaped by a backward slash (\), because a forward slash (/) is used as field separator.
String typed attribute value	All printable characters are allowed.
Literal string in the value of a constant declaration	All printable characters are allowed except the double quote (") and a backslash (\). When used, these characters may cause parsing problems.
Literal string in a condition for a rule	All printable characters are allowed except the double quote (").

The following topics provide more information:

Data Normalization

When using the ASI Authorization or ASI Role Mapping providers, there are certain data transformations that you must consider. The policy database limits what characters are allowed in certain policy elements. This set is more restrictive than the set allowed by the Security Framework.

The ASI Authorization and ASI Role Mapping providers perform normalization of input data to ensure that they abide by the restrictions imposed by the authorization management system. The management system does not currently perform any automatic normalization, so it is important to understand the normalization mechanism because it must be preformed manually when writing policy. Unless otherwise stated, the substitutions listed Table 4-5 apply to the following elements: resource, attribute, privilege, role, and directory names.

Additionally, any non printable character is translated into the numeric hexadecimal equivalent; for example, the ASCII character code 1 (a smiley face) is represented as __0x1_. Table 4-5 shows the characters that are normalized and the character substitution applied at runtime. When writing policy, you must substitute these characters.

Table 4-5 Character Substitution

Character	Character Substitution
\n	(carriage return) __CR_ also applies to user and group names
0	__0_ 1st character only
1	__1_ 1st character only
2	__2_ 1st character only
3	__3_ 1st character only
4	__4_ 1st character only
5	__5_ 1st character only
6	__6_ 1st character only
7	__7_ 1st character only
8	__8_ 1st character only
9	__9_ 1st character only
\t	(tab) __TAB_
` `	(space) __SP_
!	__EXPL_
"	__DQUOT_
#	__HASH_ 1st character of resource, or any character in attr, priv, role, dir
.	__PRD_ 1st character of resource, or any character in attr, priv, role, dir
%	__PRCT_
(	__OPRN_
)	__CPRN_
*	__ASTR_
+	__PLUS_
,	__COMMA_
/	__FSLSH_
;	__SCLN_
<	__LT_
=	__EQ_
>	__GT_
?	__QTM_
[	__OSQB_
\	__BSLSH_
]	__CSQB_
`	__CSQUOT_
{	__OCRL_
\|	__PIPE_
}	__CCRL_
&	__AMP_ Applies only to attr, priv, role, dir
-	__DASH_ Applies only to attr, priv, role, dir
:	__CLN_ Applies only to attr, priv, role, dir
@	__AT_ Applies only to attr, priv, role, dir
~	__TLD_ Applies only to attr, priv, role, dir

Directory Names

A directory further separates qualifiers. You define directories to store and scope users and groups. For example, if you had an application called Bankers, the directory that stores users and groups might look like this:

//dir/Bankers

Once declared, the directory is used with the user and group qualifier to fully qualify subjects. For example, //sgrp/Bankers/loans/ is a group called loans that belongs to the Bankers group and //user/Bankers/BSilva/ is a user named BSilva that belongs to the Bankers application.

Note: A directory name must start with a letter and can contain any number of alphanumeric or underscore characters. Directory names are case sensitive.

A directory name does not necessarily need to represent a resource. For example, a directory name might represent users in a particular location (as in //dir/NewYork) or a department (as in //dir/Accounting). Essentially, you can use them any way you want to delineate groups of users and groups.

A privilege group is not part of the policy language but is provided for administrative convenience. Each privilege in a group is defined as an individual privilege in the actual policy.

Logical Name

A logical name is a shorthand method used to represent a resource. Once you map a logical name to a fully qualified name, your developers can use the logical name when coding your application.

//ln/name

Declaration Names

A declaration name is not qualified. In fact, that is exactly how they are identified. Any policy element without a fully qualified name and not in quotation marks (indicating a string), is assumed to be a declaration. When defined, declarations are preceded by one of the following identifiers:

const - Constant Declaration

type - Type Declaration

cred - Credential (or Attribute) Declaration

eval - Evaluation Function Declaration

Special Names and Abbreviations

There are several special names, referred to as keywords, that are shortcuts for denoting groups of objects. The keywords keep you from having multiple rules or multiple rule queries in certain reoccurring situations. By using these keywords, you can define very powerful, yet generic rules. The keywords are as follows:

any—Signifies any privilege. When specifying any in a rule, it means you do not care what privilege a user invokes when applying the rule.
ALL—Signifies a privilege group containing all privileges. You must use the grp qualifier with the keyword ALL (//grp/ALL). The keyword ALL is mainly used for grouping purpose in the console and, by default, every privilege defined belongs to the privilege group ALL.
allusers—For each user directory, there is an implied group called allusers. This group refers to all users in a directory. For example:

//group/Acct/allusers
This example refers to allusers for the Acct directory and eliminates the need to individually address each user or to create a named group for all of the users.

Note: The keyword allusers is only a limited pseudo group. It does not have many of the qualities of a regular group; you cannot map it to anything, you cannot add or remove members, and it cannot be a member of group hierarchy. You can delegate to allusers groups.

Table 4-6 describes the rules for using keywords.

Table 4-6 Rules for Using Keywords

Characteristic	any	ALL	allusers
Policy Element	Built-in privilege	Built-in privilege group	Built-in local group
Represents	any privilege	All privileges including built-in and user-defined	All users in one local directory
Used in rules	Yes	No	Yes
Needs qualifier	No	Yes `//grp/ALL`	Yes `//sgrp/ [directory name]/allusers`
Used in policy queries	Yes Only finds rules with the literal any. That is, it does not return all rules (rules with any privilege).	No	Yes Finds rules that specifically entitle the group allusers
Controlled by delegation	No Must be in a group that is delegated	Yes Controls access to all privileges regardless of privilege group	Yes You must be specifically delegated access to this group
Case-sensitive	Yes	Yes	Yes

Sample Policy Files

This section provides examples of each policy file. A policy file is a text file that lists the relevant policy elements using their fully qualified names. Sample files for each policy element are provided with the product and are installed in the following directory:

BEA_HOME\ales21-admin\examples\policy

For a description of each of these files, see the following topics. The policy data filenames are shown in brackets ("[]").

Application Bindings [binding]

This file contains an example of the Authorization provider and Service Control Manager bindings. The resources that can be bound are the resources that are created as binding nodes.

Each line contains a name of an Authorization provider or Service Control Manager, followed by a binding node name. A Security Provider can only bind policy resources and the Service Control Manager can only bind configuration resources.

Examples:

//bind/myAuthorizationProvider  //app/policy/myApplication/myBinding

//bind/mySCM //app/config/myConfiguration/configBind

Attribute [attr]

This file lists the subject attribute for users and subject group. The attribute value property must comply with user attribute schema defined for //dir/dirName. If the property is "L", the attribute value must be enclosed in brackets ([]), with items separated by commas. In general, the attribute value for all users must be set according to the specification defined in user attribute schema. However, if an attribute is not set when this file is created, its record may be left out in this file.

Note: Both user and credential declarations must exist in the policy database before it can be loaded successfully. Further, the user attribute schema must be defined before the user attribute can be assigned in Attribute Value file.

Examples:

Given the user attribute schema shown in Listing 4-1, the user attribute values and subject attribute value are defined as shown in Listing 4-2 and Listing 4-3.

Listing 4-1 User Attribute Schema

//dir/CA_Office my_host_ip S

//dir/CA_Office my_favorite_color L [blue,green]

//dir/NY_Office email_address S "user@crosslogix.com"

//dir/NY_Office my_birthday   S

//dir/NY_Office my_favorite_color L [red]

Listing 4-2 Sample User Attributes

//user/CA_Office/user_a@mycom.com/ my_host_ip 121.1.100.25
//user/CA_Office/user_b@mycom.com/ my_host_ip 121.1.100.26
//user/CA_Office/user_c@mycom.com/ my_host_ip 121.1.100.50
//user/CA_Office/user_d@mycom.com/ my_host_ip 121.1.100.225
//user/CA_Office/user_e@mycom.com/ my_host_ip 132.99.25.77

//user/CA_Office/user_a@mycom.com/ my_favorite_color [red]
//user/CA_Office/user_b@mycom.com/ my_favorite_color [white,green]
//user/CA_Office/user_c@mycom.com/ my_favorite_color [red,blue]

//user/NY_Office/user_1/ email_address "user1@crosslogix.com"
//user/NY_Office/user_1/ my_birthday 1/1/1960
//user/NY_Office/user_1/ my_favorite_color [blue]

Listing 4-3 Sample Subject Group Attribute

//sgrp/NY_Office/role1/ my_favorite_color [green]

Declarations [dec]

BEA AquaLogic Enterprise Security supports four kinds of declarations that are used in rules, user attributes, and resource attributes. You must create the declaration before you use it in a rule. The kinds of declarations are: enumerated types (ENUM), constants (CONST), attributes (CRED), and evaluation functions (EVAL). You can use this file to declare each one. Each line contains the declaration text, starting with declaration type. Declaration names are case-insensitive and are always saved in lower case. The four kinds of declaration text must conform with the following syntax.

ENUM enum_name = (enum1, enum2, , enumn);

CONST constant_name_1 = constValue;

CONST constant_name_2 = [value1, value2, , valuen];CRED cred_name : datatype;

EVAL eval_name;

Examples:

ENUM color_type = (red, blue, green, white);

CONST my_favorite_color = green;

CONST my_birth_date = 07/04/1980;

CONST favorite_colors_for_tom = [blue, white];

CONST colors_of_my_choice = [my_favorite_color, red];

CONST a_few_cities = ["New York", "Boston", "San Francisco"];

CONST a_magic_number = 28;

CRED string_cred_1 : string;

CRED color_cred : color_type;

CRED date_cred : date;

CRED weight_in_pound : integer;

EVAL is_good_number;

Directories [dir]

Multiple directories can be used to separate users and groups that come from different user stores. A directory is also associated with a schema and the types of attributes the users in that directory contains.

This file lists the name of some sample directories. The directory name must start with the prefix:

//dir/

Examples:

//dir/CompanyA

//dir/CompanyB

Directory Attribute Schemas [schema]

A directory defines all users and user groups. Before a user or a user group can be assigned an attribute, you must declare the directory to accept their attributes. You can use this file to declare the attributes that a directory can have.

Each line in the file contains a directory name, an attribute name (the attribute declaration as in file "decl"), a value type (single- or multi-value), and an optional template value matching the data type of the attribute. The single-value type is denoted by S and multi-value type by L (from list-value).

You must enter a multi-value (list) attribute with all values enclosed in square brackets [] and separated by commas, and enclose each value for a string data typed attribute with double quotes ("). You cannot use another double quote (") and backslash (\) in the template value.

Examples:

//dir/CompanyA my_host_ip S 111.111.111.111

//dir/CompanyA my_favorite_color S

//dir/CompanyA email_address L ["user@bea.com", "xyz@yahoo.com"]

//dir/CompanyB my_birthday   S

//dir/CompanyB my_favorite_color L [blue,green]

list of exclusive sgrp pair.

Mutually Exclusive Subject Groups [excl]

This file lists the subject groups that are mutually exclusive from one another. An exclusive subject groups record has the following format:

//sgrp/dirName/aSubjectGroupName/ //sgrp/dirName/anotherSubjectGroupName

For subject groups to be mutually exclusive, they must comply with the following requirements:

Both subject groups must be in the same directory.
The subject groups must not share a common sgrp member or user member.
Both subject groups in a pair must exist in the policy database before the pair can be defined and loaded successfully.

Example:

//sgrp/CA_Office/trader/ //sgrp/CA_Office/salesPerson/

Resources [object]

In general, resources are constructed as a tree below two tree roots: the policy resources tree and the configuration tree. The policy tree has a resource name that starts with the prefix //app/policy/ (for resource configuration) and configuration tree that starts with the prefix //app/config/ (for provider configuration). However, you do not see the provider configuration in the tree. This file lists all the resource names in order, from the root to the child nodes, together with the resource type and the logical name for the resource.

There is a special resource type, denoted by A, indicating that the resource node is bound by an ASI Authorization Provider or a Service Control Manager. This special resource node is called a binding node. All other resources are denoted by O and are called non-binding nodes.

A logical name or alias is a short name for a resource and can be optionally associated with a resource. Only binding nodes derived from the resource can have an alias. A logical name used as an alias must start with prefix:

//ln/

and must be unique to the entire resource tree. Each line contains a resource name, an optional resource type, and an optional alias. If the resource type is missing, it defaults to O. If there is an alias, the resource type must be specified.

Examples:

//app/policy/myApplication

//app/policy/myApplication/myBinding A

//app/policy/myApplication/myBinding/myresource.one O //ln/myres1

//app/policy/myApplication/myBinding/myresource.two O

//app/policy/myApplication/myBinding/myresource.three

//app/config/myConfiguration O

//app/config/myConfiguration/configBind A //ln/configBind

Resource Attributes [object]

Because a resource is also referred to as object, a resource attribute is also referred to as an object attribute. Each line contains a resource name (as in file "object"), an attribute name (the declaration as in file "decl"), a value type (single- or multi-value), and values matching the data type of the attribute. The single-value type is denoted by S and multi-value type is by L (from list-value). You can enter a multi-value attribute either in multiple lines, with the same resource name, attribute name and value type (L); or, you can enter it using one line, with all the values enclosed in square brackets [] and separated by commas. You must enclose each value for a string attribute with double quotes ("). You cannot use another double quote and backslash (\) in the attribute value.

Examples:

//app/policy/myApplication/myBinding  string_attr_1 S  "A value to be decided"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "1st Value"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "2nd Value"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "3rd Value"

//app/policy/myApplication/myBinding/myresource.two string_attr_1  L ["ABC", "DEF", "XYZ"]

//app/policy/myApplication/myBinding/myresource.three color_attr_1 L [red, blue]

//app/policy/myApplication/myBinding/myresource.three integer_attr_1 S  1001

//app/policy/myApplication/myBinding/myresource.three date_attr_1 L  [01/01/2003, 01/01/2004]

Policy Distribution [distribution]

This file provides the parameters used for policy distribution issued by the Policy Import tool when the distribution is enabled in a configuration. The policy distributor takes a list of user directories and distribution point combinations. Therefore, each line contains a directory and a distribution point separated by white spaces.

The distribution point is a resource node on or above a binding resource node. The directory can be either a specific directory or //dir/* to include all user directories.

Note: You cannot use applications pending deletion as distribution points. Select a node higher in the tree as the distribution point.

Examples:

//dir/* //app/policy/myApplication

//dir/CompanyA //app/policy/myApplication/myBinding

Policy Inquiry [piquery]

AquaLogic Enterprise Security stores the contents of a policy inquiry in the policy database. This file contains examples of policy inquiries to import and store in the policy database. Each query can span multiple lines, can have multiple lines of each type, but must have a minimum of one line. The first line of each query must specify the privilege, the effect (grant or deny), the query owner and the query title.

Each line has the following syntax:

P/O/S oneQualifiedName grant/deny queryOwner queryTitleMayhaveSpace

where P/O/S stands for privilege, object (resource), and subject.

Listing 4-4 shows policy inquiry examples.

Listing 4-4 Policy Inquiry Examples

# Sample query 1:

P //priv/delete     grant //user/ales/system/ Saved Policy Inquiry #1
O //app/policy/myApplication/myBinding  grant //user/ales/system/
      Saved Policy Inquiry #1
S //ales/ales/userid/ grant //user/ales/system/ Saved Policy Inquiry #1

# Sample query 2 (same content as query 1):

P //priv/delete     grant //user/ales/system/ Policy Inquiry #2
O //app/policy/myApplication/myBinding 
S //ales/ales/userid/

# Sample query 3:

P //priv/delete   grant //user/ales/system/ Policy Inquiry #3

# Sample query 4:

P //priv/delete               deny //user/ales/system/ PIQuery4
P //priv/create 
O //app/policy/myApplication

Policy Verification [pvquery]

AquaLogic Enterprise Security stores the contents of a policy verification in the policy database. This file defines policy verification queries to import and store in the database. Each query spans multiple lines. The first line of each query must have the owner and title, in the following syntax:

LP/RO/RP/RO oneQualifiedName queryOwner queryname

A query name may contain spaces.

Listing 4-5 shows policy verification examples:

Listing 4-5 Policy Verification Examples

# Sample query 1:

LP //priv/delete //user/ales/system/ Policy Verification #1
LO //app/policy/myApp/firstResource //user/ales/system/ Policy Verification #1
RP //priv/create //user/ales/system/ Policy Verification #1
RO //app/policy/myApp/secondResource //user/ales/system/ Policy Verification #1

# Sample query 2 (query content is the same as query 1):

LP //priv/delete //user/ales/system/ Policy Verification #2
LO //app/policy/myApp/firstResource
RP //priv/create
RO //app/policy/myApp/secondResource

# Sample query 3:

LP * //user/ales/system/ Policy Verification #3
LO //app/policy/myApp/firstResource //user/ales/system/ Policy Verification #3
RP //priv/delete //user/ales/system/ Policy Verification #3
RO //app/policy/myApp/secondResource //user/ales/system/ Policy Verification #3

# Sample query 4:

LP * //user/ales/system/  PolicyVerification#4
LO //app/policy/myApp/firstResource //user/ales/system/  PolicyVerification#4
RP * //user/ales/system/  PolicyVerification#4
RO //app/policy/myApp/secondResource //user/ales/system/  PolicyVerification#4

Privileges [priv]

This file contains a sample list of privilege names. Each privilege name must start with the prefix:

//priv/

Examples:

//priv/read

//priv/Read

//priv/search_file

//priv/search_text

Privilege Bindings [privbinding]

This file contains examples of how privileges are bound to privilege groups. Each line contains a privilege group followed by a privilege.

Examples:

//grp/myPrivGroup //priv/read
//grp/myPrivGroup //priv/search_file
//grp/myPrivGroup //priv/search_text
//grp/DevelopmentGroup //priv/read
//grp/DevelopmentGroup //priv/Read

Privilege Groups [privgrp]

This file contains examples of privilege group names. Each privilege group name must start with the prefix:

//grp/

Examples:

//grp/myPrivGroup
//grp/DevelopmentGroup

Role [role]

This file defines a list of role names. Roles are used to construct policies. Each line contains a role name. Each role name is prefixed with:

//role/

Examples:

//role/manager
//role/QA
//role/trading_Manager
//role/salesEngineer
//role/junior_trader
//role/salesPerson
//role/trader

Rule [rule]

Rules are used by the Authorization and Role Mapping Engine (ARME) to make authorization and role mapping decisions. This file lists rules with their rule text conforming to rule syntax. Each line contains one rule, a grant, deny, or delegate rule. Sample entries assume all of the referenced roles, privileges, resources, users, groups and declarations exist in the policy database.

Examples:

grant(//role/Administrators, //app/policy/myApplication, //user/ales/system/);
grant(//priv/read, //app/policy/myApplication, //sgrp/ales/allusers/);
deny([//priv/read, //priv/search_text],
//app/policy/myApplication/myBinding/confidentialDocument.one, //role/public);
delegate(//role/Administrators, //app/policy/myApplication, //user/ales/John Doe/, //user/ales/system/) if dayofweek in weekend;

Distribution Targets

There are two types of distribution targets in BEA AquaLogic Enterprise Security:

The Authorization and Role Mapping providers that enforce policy
The Service Control Manager that manages configuration changes

Both of these targets retrieve their policy data from the policy distributor. The security providers receive only policy related changes and the Service Control Manager retrieves only configuration related changes. The file called engine lists the names of the security providers and the Service Control Manager and respective type.

The name is qualified by the prefix:

//bind/

The names are referred to by the application binding file (binding) and must be imported before the application binding file.

Examples:

//bind/myAuthorizationProvider ARME

//bind/mySCM SCM

Subject Group Membership [member]

This file lists subject group membership. Each record has one of the following formats:

//sgrp/dirName/aSubjectGroupName/ //sgrp/dirName/aSubjectGroupMemberName/

//sgrp/dirName/aSubjectGroupName/ //user/dirName/aUserMemberName/

When you define subject group memberships, the subject group and members must comply with the following requirements:

The subject group and the member must be in the same directory.
One user may belong to many subject groups.
One subject group may be a member of many subject groups.
Two subject groups that have common members cannot become mutually exclusive.
Both subject groups and their members must exist in the policy database before the membership can be loaded successfully.

For an example of a Member policy file, see Listing 4-6.

Listing 4-6 Sample Member Policy File

//sgrp/CA_Office/junior_trader/   //sgrp/CA_Office/trader/
//sgrp/CA_Office/trader/          //sgrp/CA_Office/senior trader/
//sgrp/CA_Office/senior trader/   //sgrp/CA_Office/trading_Manager/
//sgrp/CA_Office/salesEngineer/   //sgrp/CA_Office/salesManager/
//sgrp/CA_Office/salesPerson/     //sgrp/CA_Office/salesManager/

//sgrp/CA_Office/junior_trader/   //user/CA_Office/user_a@mycom.com/
//sgrp/CA_Office/senior trader/   //user/CA_Office/user_b@mycom.com/
//sgrp/CA_Office/trading_Manager/ //user/CA_Office/user_c@mycom.com/
//sgrp/CA_Office/salesPerson/     //user/CA_Office/user_d@mycom.com/
//sgrp/CA_Office/customer/        //user/CA_Office/user_e@mycom.com/

Subjects [subject]

This file contains a list of users and subject groups. Each record must have one of the following formats:

//user/dirName/aUserName/ //sgrp/dirName/aSubjectGroupName/

The directory name must be formatted as //dir/dirName and it must exist in the policy database before its subjects can be loaded successfully.

For an example of a Subjects policy file, see Listing 4-7.

Listing 4-7 Sample Subjects Policy File

//user/CA_Office/user_a@mycom.com/
//user/CA_Office/user_b@mycom.com/
//user/CA_Office/user_c@mycom.com/
//user/CA_Office/user_d@mycom.com/
//user/CA_Office/user_e@mycom.com/
//sgrp/CA_Office/junior_trader/
//sgrp/CA_Office/trader/
//sgrp/CA_Office/senior trader/
//sgrp/CA_Office/salesEngineer/
//sgrp/CA_Office/salesPerson/
//sgrp/CA_Office/salesManager/
//sgrp/CA_Office/trading_Manager/
//sgrp/CA_Office/customer/

//user/NY_Office/user_1/
//sgrp/NY_Office/sgrp1/

Resource Discovery

When developing policy for use with a Security Service Module, you can use the Discovery mode to help build your policy. Understanding how to write a policy requires that you understand the application you want to protect, the policy representations, and the mapping between the two.

Note: You should never use Discovery mode in a production environment. Discovery mode is used in the development environment to create the bootstrap security policy.

A typical policy consists of the following elements:

Resources
Privileges
Roles
Attributes (user, group and resource)
Attributes, privileges, and resource associations
Rules to grant privileges on resources through roles
Rules to grant roles to users

The ASI Authorization and ASI Role Mapping providers support a Discovery mode that helps make this task easier. Typically, these providers answer questions about security, but when in Discovery mode, the providers record information about those questions to build your policy (for example, what privileges and resources must be granted to view a particular web page).

To use Discovery mode, you must modify the command line that starts your Security Service Module by adding the following system properties:

com.bea.security.providers.authorization.asi.AuthorizationProviderImpl.discoverymode=true

com.bea.security.providers.authorization.asi.RoleProviderImpl.discoverymode=true

You set the system properties using the -D command-line switch in the appropriate file, depending on which Security Service Module (SSM) you are targeting. Table 4-7 lists the files and their default locations for each type of SSM.

Table 4-7 Setting System Properties for Discovery Mode

Security Service Module Type	File Name	File Default Location
Apache	`set-env.sh` (UNIX only)	`BEA_HOME\ales21-ssm\apache-ssm\ instance\ <instancename>\bin`
IIS Web Server	`set-env.bat` (Windows only)	`BEA_HOME\ales21-ssm\iis-ssm\instance\ <instancename>\bin`
Java	`set-env.bat (.sh` for UNIX)	`BEA_HOME\ales21-ssm\java-ssm\instance\<instancename>\bin`
Web Services	`wlesws.wrapper.conf`	`BEA_HOME\ales21-ssm\webservice-ssm\ instance\<instancename>\config`
WebLogic Server 8.1	`set-wls-env.bat` (`.sh` for UNIX)	`BEA_HOME\ales21-ssm\wls-ssm\instance\ <instancename>\bin`

Note: The policy files are stored in the domain directory from which the startWeblogic.bat or startWeblogic.sh script is started and configured to run in Discovery mode.

A sample policy is recorded by the providers as you traverse an application. This is a learning process for the providers and they can only learn about the parts of the application that you use. If a portion of the application is not used, no information or policy about it is recorded. The generated policy is output to a set of files that you can import later, by using the Policy Import tool described in Importing Policy Data.

Among other things, the ASI Authorization and ASI Role Mapping providers transform their requests into a proprietary format. A request consists of the following four elements:

Subject
Resource
Action
Attributes

The ARME providers build this information based on data contained in the request to the provider. Each of these elements has different restrictions on the allowable character set. The providers automatically normalize any invalid characters to produce a valid entry. See Character Restrictions in Policy Data for further details.

The following sections describe how each element is represented and transformed.

Subject Transformation

A subject representation uses the standard javax.security.auth.Subject class that contains a set of java.security.Principal objects.

A subject consists of a directory name, a user name, and a set of group names. The user and groups must exist within the directory specified for the provider. The directory name is part of the provider configuration and can be modified using the Administration Console.

The providers iterate the principals, selecting those that implement the weblogic.security.spi.WLSUser and weblogic.security.spi.WLSGroup interfaces. The first WLSUser principal is used to retrieve the user name. All of the WLSGroup principals are used to build of the group names.

Resource Transformation

A resource representation varies based on the resource type. Each WebLogic J2EE resource has a special representation based on a common resource base class. The Java API uses a standard resource representation (see Java API and Programming Security for Java Applications).

To effectively handle each of these resource representations the ASI Authorization and Role Mapping providers support a plug-in mechanism for registering code to handle the transformation to the native resource format. See Resource Converter for details on how to use the resource converter plug-in.

The ARME represents a resource as a node within a tree and the node is referenced using a path-like expression. The nodes are delimited by the forward slash (/) character and are rooted at a node named //app/policy. Typically, an application is not located directly below the root node, but is nested, based on an organizational structure. The application root node is referred to as the Application Deployment Parent and is a configuration property for the ASI Authorization and ASI Role Mapping providers. The plug-in defines the part of the path expression below the Application Deployment Parent.

A typical resource path may look like:

//app/policy/MyWebServer/HelloWorldApp/url/helloworld/HelloWorld.jsp

In this case, the Application Deployment Parent is:

//app/policy/MyWebServer

AquaLogic Enterprise Security provides resource converter plug-ins for the standard WebLogic J2EE resource types. The same transformation scheme is used for each resource and consists of the following elements:

Name of the application with which the resource is associated
Resources type
Resource hierarchy that identifies the parents of the resource
Resources name

These elements are used to define the resource path expression. The hierarchy is typically divided into a number of individual units.

Resources that have no associated application are considered to be shared and exist under a configurable shared node. Typically, this shared node is called "shared" and exists just below the Application Deployment Parent.

The following example shows a URL resource, describing its component parts. A typical URL resource looks like this:

http://localhost/helloworld/HelloWorld.jsp

It may also contain the following data elements:

Application - HelloWorldApp
Context Path Argument - /helloworld
URI - HelloWorld.jsp

The URL Resource Converter performs the following transformation:

The application maps to an application

The resource type is: url.

The resource hierarchy is built from the context path and the URI.

The resource name is the last element of the URI.

The context path and URI are hierarchal components and are parsed based on the URL delimiter ( /) and reassembled into the ARME resource.

The resulting ARME resource is represented as: HelloWorldApp/url/helloworld/HelloWorld.jsp
with an Application Deployment Parent of: //app/policy/MyWebServer
a fully qualified ARME resource is thus named: //app/policy/MyWebServer/HelloWorldApp/url/helloworld/HelloWorld.jsp

WebLogic Resource Transformation

The same basic pattern is used for all other WebLogic resources. Table 4-8 describes the elements of each resource class that are used to construct each resource name. An understanding of the WebLogic Server resource representation may help you have a better understanding the data included in the resource. For detailed descriptions of each resource class, see the Javadocs for the weblogic.security.service package in the WebLogic Server 8.1 Javadocs located at: http://edocs.bea.co m/wls/docs81/javadocs/index.html.

Table 4-8 Standard WebLogic Server Resources

Resource Class	Application	Type	Hierarchy	Name
ApplicationResource	Application	"app"	N/A	N/A
URLResource	Application	"url"	contextPath	URI
AdminResource	shared	"adm"	Category	realm
COMResource	Absolute parent's application name	"com"		Class name
EJBResource	Application	"ejb"	Module name	EJB name
JDBCResource	Application typically Shared	"jdbc"	Module name + resource type	Resource name
JNDIResource	Application typically Shared	"jndi"	JNDI Path
ServerResource	Application typically Shared	"svr"		Server name
EISResource	Application	"eis"	Module name	EIS name
JMSResource	Application typically Shared	"jms"	Destination type	Resource Name
WebResource	Application name	"Web"	URI of the web resource	Resource name
WebServiceResource	application	"webservices"	Context path	Web service name
wlp	Enterprise application name	"wlp"	Web application name	Resource name

Java API Resource Transformation

The BEA AquaLogic Enterprise Security for Java 2.1 API Reference provides a more abstracted resource interface. Resources of all types are represented as a ResourceActionBundle. This class provides methods for extracting deep enumerations describing each resource. The conversion for the ResourceActionBundle resource type is simple. The first non-null, non-empty element in the enumeration is considered to be the application, and the last non-null, non-empty element is considered to be the name. Basically the elements are joined in order using the ARME forwardslash ( /) delimiter.

Action Transformation

The ASI Authorization and ASI Role Mapping providers represent an action as a simple string identifier. The Security Framework encodes the action as part of the resource object. The resource converter extracts an action similar to how it extracts the resource path. Some resources do not have the notion of an action, in which case the default action access is used. Table 4-9 lists the WebLogic resources and associated action transformations.

Table 4-9 WebLogic Resource Action Transformations

Resource	Attribute
URLResource	http method name
AdminResource	Admin action name
COMResource	"access"
EJBResource	EJB method name
JDBCResource	JDBC action name
JNDIResource	JNDI action name
ServerResource	Server action name
EISResource	"access"
JMSResource	JMS action name
WebServiceResource	WebService method name

With the Java API resource transformation, actions are represented as a deep enumeration. If the enumeration contains more then a single item, they are joined together using an underscore ( _ ) delimiter. The ASI Authorization and ASI Role Mapping providers treat these as an atomic unit.

Attribute Transformations

The ASI Authorization and ASI Role Mapping providers attempt to make as much contextual information available as possible for use in making authorization decisions. This includes both data from the ContextHandler as well as data embedded in the resource object.

The data from the ContextHandler is directly available by name; that is, if the ContextHandler contains an element named balance, it can be directly referenced from the authorization policy. The data supplied in the ContextHandler is application specific.

The resource object used in the authorization query can contain more data than was used in constructing the ARME resource and action. This data is provided to the ARME as attributes. The specific attributes available depend on the resource type (see Table 4-10). Again, the resource converter retrieves resource specific data whenever requested.

Table 4-10 Attributes and Resources Class

Resource Class	Attributes
URLResource	application, contextpath, uri, httpmethod, transporttype, authtype, pathInfo, pathtranslated, querystring, remoteuser, requestedsessionid, requesturi, requesturl, servletpath, characterencoding, contenttype, locale, protocol, remoteaddr, remotehost, scheme, servername, serverport, issecure Note: Additionally, servlet parameters, attributes, headers, and cookies are all available by name. These items are specific to the request and thus cannot be enumerated here.
AdminResource	category, realm, action
COMResource	application, class
EJBResource	application, module, ejb, method, methodinterface, signature
JDBCResource	application, module, category, resource, action
JNDIResource	application, path, action
ServerResource	application, server, action
EISResource	application, module, eis
JMSResource	application, destinationtype, resource, action
WebServiceResource	application, contextpath, webservice, method, signature
ResourceActionBundle	All elements in the resource and action enumerations are available by name. These names are application specific.

What's Next?

After you create the policy data files, you can import those files into the policy store using the Policy Import tool.

Importing Policy Data

This section provides instructions and information on how to import policy data to the policy store. It covers the following topics:

Policy Import Tool

The Policy Import tool is a Java utility that provides an alternate method of entering policy data (rather than through the Administration Console). The main purpose of using this tool is to reduce the amount of manual data entry required. The Policy Import tool lets you load policy data into the database, distribute that policy, and remove policy data from the database. The Policy Import tool reads and imports policy data that is stored as text using non-XML, easy to read format. Each policy element is stored in a separate file, referred to as a policy file. For information on the specific format of these policy elements, see Creating Policy Data Files for Importing.

The Policy Import tool has the following features:

Multi-threaded architecture-Allows for more efficient policy loading.
Separation of policy elements-Loads multiple files with each file corresponding to one policy element.
Optimized-Fast import of large policies during initial import.
Policy Distribution-After importing, use the Policy Import tool to distribute the policy.

Note: Before you can use the Policy Import tool to distribute policy, you must configure the distribution file and enable the policy distribution feature in the distribution configuration file of the policy loader.

Removing Policy-You can also use the Policy Import tool to remove policy elements from the database.

Note: When running the Policy Import tool on a large policy, the number of records processed may not be synchronized. If multiple threads are used to import the data, when one thread completes before the other cannot be determined. If the threads are set too high, a message may appear indicating that the number of records processed is not synchronized. This is normal and is not a problem for the Policy Import tool.

For a description of the content of Policy files, see Sample Policy Files.

Note: If you want to store users, groups, and their attributes in an external store, you can use the Metadata Directory tool, as described in Configuring Metadirectories in Integrating ALES with Application Environments.

When exporting the policy, the configuration resources are saved to the following files: object_config and objattr_config. These two files are not loaded by the policy loader by default. If you want to load the configuration resources, you need to create a directory and copy object_config, objattr_config, and binding into that directory. Rename object_config to object and objattr_config to objattr. Then you can configure the policy loader to load these files into this new directory.

Configuring the Policy Import Tool

The Policy Import tool relies on the configuration file for information on how to load the policy files. You only need to modify the configuration file if you the change the location of the policy files or you want to change some configuration options. The Domain parameter is required for successful import. The Policy Import tool uses default values for the other parameters, which are all optional.

This section covers the following topics:

Setting Configuration Parameters

Each configuration parameter has the following format:

<Parameter> <Value>

The file paths in the configuration file depend on the directory from which you run the Policy Import tool. You may use the full path filename to avoid directory dependency. Spaces are allowed between parameters and between new lines. Parameter names are case insensitive. Table 4-11 lists the parameters you need to configure for the Policy Import tool.

To create the configuration file (see Listing 4-8 for a complete sample), you need a text editor such as Notepad. Create the file by entering the necessary parameters and parameter values. The following sections describe the contents of a sample configuration file, with a detailed explanation of each parameter and its default value.

Enter the following parts of the configuration file in the format described. These are only sample entries. Your entries depend on the names you create and where your files are stored. An italics font is used here to represent variables that you replace with your own parameter names. You do not need to list the parameters in the configuration file in this order.

There is a sample of a Policy Import configuration file named policy_loader_sample.conf located in the .../examples/policy directory. You can modify this file for your own use. BEA recommends that you use this file as a template and customize it for your particular needs.

Note: The configuration parameters are listed in alphabetical order in Table 4-11. This is not the order in which they are listed in the policy_loader_sample.conf file.

Table 4-11 Configuration Parameters

Parameter	Description
`Action`	Indicates the Action that the Policy Import tool will perform. Supported values are `LOAD` and `REMOVE (case insensitive).` `REMOVE` = Unloads the specific policy from the database. `ADD` = Loads the specific policy data into the database.
ApplicationNode	Specifies the application node that holds the administration policy. If this parameter is commented out, the default value of `admin` is used.
`BLMContext Retries`	Specifies the number of times retries should take place. If the ALES Administration Console server is still starting up, then you need to retry the BLM API Authentication. In most cases the ALES Administration Console server is always running. Default: 100.
`BLMContext Interval_ms`	Specifies the amount of time (in milliseconds) to wait between context retries. DEFAULT: 100ms.
`BulkSize`	Specifies the number of records to send at one time in a thread. Default: 200. Note: When there are multiple threads importing policy data, each processing a number of records, the number of records processed may result in an "out-of-sync" message. However, it does not harm the data when importing the policy. The policy import tool switches to single thread when importing some policy elements, such as resources and declarations, as the later records have dependency on earlier records.
`ConsoleDisplay`	Specifies whether to hide console interaction or not (yes/no). If you want to run the policy loader in the background as a batch process, set to `no`. Default: `yes` `no =` Error messages are not displayed on the console and the user is requested to enter their `Username` and `Password` if they are missing in the configuration file. `yes` = Error messages are displayed on the console. This parameter must be enabled if you want to type in your password on the command prompt, rather then use the one specified in the `password.xml` or in the configuration file.
`Debug`	Specifies whether you want to log debug information. Default: 0 `0` = Does not log debug information. `1` = Sends debug information to the file defined by: `ErrorLogFile.`
`Domain`	Specifies the Enterprise domain name, as assigned during the installation of the Administration Application. Default: `asidomain`. This parameter is required.
`ErrorLogFile`	Specifies the name of error log file. This file is produced if the Importing Tools fails while attempting to load a set of policy files. It contains error messages that describe the failures to assist you in correcting the errors. Default: `error.log`.
Mode	Specifies the mode of operation the Policy Import tool. Values are `INITIAL` or `RECOVER` (case insensitive). Use INITIAL mode the first time you run the Import Policy Tool to load a set of policy files. If you encounter errors in the initial load attempt, check the `ErrorLogFile` for a description of the error, correct the errors in the generated error file(s) (an error file is produced for each policy file that fails), and rerun the Import Policy Tool again, but this time in the RECOVER mode. This way the tool only attempts to load the generated error files. If the tool fails again, fix the errors, and run it again in RECOVER mode. Repeat until no errors are encountered. Note: This parameter can also be passed in as a command-line parameter `-recover` or `-initial`. Values for this parameter on the command line override values specified in the configuration file.
`PasswordFile`	Specifies an encrypted password file. To set up a password file, use the `asipasswd` utility. This utility prompts you for the alias (username) and the password of the user trying to import the policy and then saves the encrypted password in the `password.xml` file. Default: `../ssl/password.xml`.
`PasswordKey File`	Specifies a private key used to decrypt the password stored and encrypted in the `password.xml` file. To set up a password file, use the `asipasswd` utility. Default: `../ssl/password.ke`y.
`Policy DirectoryPath`	Specifies the directory path from which to import policy files. For example: ../examples/policy. The path may be relative. Default: "`.`" (for relative)
`Policy Distribution`	Specifies whether the Policy Import tool will distribute policy. If the distribution file is in policy distribution path and PolicyDistribution parameter is set to yes, the policy will be distributed. Supports `YES` or `NO` setting. Default: `YES`. `YES` = The Policy Import tool distributes policy data. `NO` = The Policy Import tool does not distribute data. It only imports it into the database. The Administration Console can then be used to distribute data.
`requestTimeout`	Specifies the time (in milliseconds) to wait for the server to respond. Should be longer for loading large files. May set to infinite `(ASI.INFINITE`) for very large files. Default: 600000
`RunningThread`	Number of threads running concurrently to process the policy import. The value depends on the capacity of the database server. Commonly the optimal value is 2 - 4 or be larger for a high capacity database server. Default: 2.
`Username`	Specifies the username for the administrator (optional). The `username` is case sensitive. If the `username` is not specified in the configuration file and the `ConsoleDisplay` parameter is enabled, then you are prompted to enter one. Default: `system`. Note: This user must have the privilege to import policy.

For more information on the configuration parameters, refer to the following topics:

Username and Password

Including the password in the configuration file is optional and is not recommended because it could be viewed by others who are not authorized to import policy. The password can be encrypted and stored in the password.xml file. You should set the PasswordFile and PasswordKeyFile for the policy to automatically retrieve the password using the alias as the username specified in the configuration file. If you do not include these parameters and the console display is enabled (the default setting), you are prompted to enter their values when you run the Policy Import tool. If one of the two parameters is not included in the configuration file and the console display is disabled, the Policy Import tool logs an error and terminates. When entered, the password is not displayed for security reasons.

Policy Import Parameters

This section of the configuration file specifies parameters that the Policy Import tool uses to import policy data. There are three policy import parameters: PolicyDirectoryPath, RunningThread and BulkSize.

The PolicyDirectoryPath parameter specifies the directory path for the policy files. When you start the Policy Import tool, it looks in the directory pointed by PolicyDirectoryPath for valid files. The directory path is either a relative or full path. If the value is left empty or the value is a period (.), the current directory of the Policy Import tool is assumed. For example:

PolicyDirectoryPath ../examples/policy

The RunningThread parameter specifies the number of running threads and depends on the hardware configuration of the database server. The default number is 3. For most database servers, you want to use a value from 2 to 4. For a high-capacity database server, where a high CPU speed and large memory size are allocated, increase this number to improve import performance. If you set this value too high, it may hinder the performance of the Policy Import tool. If this is the case, you can observe database busy warning messages in the server log file.

The BulkSize parameter denotes the size of each bulk load data block per thread in the Policy Import tool; that is, the number of entries imported in a single load using a single connection between server and the database. Increase the parameter value to lessen the time to initiate a connection. If you enter too high a value, the import process slows, which in turn requires higher RequestTimeout and ConnectionTimeout values. The optimal value is between 50 and 300.

Sample Configuration File

Use the sample file shown in Listing 4-8 to guide you through the process of creating your configuration file. Each parameter description includes comments, indicated by the # symbol. The sample configuration file assumes that all of your policy files are located in the directory specified by BEA_HOME/ales21-admin/examples/policy.

Note: Be sure to use forward slashes (/) when specifying the policy file directory path.

The sample configuration file also assumes that no policy distribution is performed.

Listing 4-8 Sample Configuration File

# Required

## In addition to this file, asi.properties is read in from the ALES_HOME/config
## directory.  Any parameters set here will override values defined there.

#### policy domain name, as set in policy database during database installation
Domain asidomain

# Optional

#### A ALES administrator user id and password.
#### If either Username or password is not provided, they can be
#### entered at prompt (case sensitive).
#### They should be same as stored in database.
#Username system

#### Encrypted password file
#### To set up a password file, use asipasswd utility tool
PasswordFile ../ssl/password.xml

#### Password key file
PasswordKeyFile ../ssl/password.key

#### This is the application node that holds the administration policy.
#### If commented out it assumes the dafult value of "admin".
ApplicationNode admin

#### Number of Threads Running concurrently
#### The value depends on the capacity of the database server
#### commonly the optimal value is 2 - 4, or could be larger for high capacity 
#### DB server
RunningThread 2

#### If ALES Admin console server is still coming up then you need to retry 
#### the BLM API Authentication. In most cases the ALES Admin console server will 
#### always be running.
#### Configure the number of times retries should take place (DEFAULT 100)
BLMContextRetries 2

#### Configure the the amount of time in milli seconds to wait between context 
#### retries (DEFAULT 100ms)
BLMContextInterval_ms 100

#### Size for each bulk load. I.e. number of entries loaded in a
#### single load(200 here)
BulkSize 200

#### Loading directory value for loading policy files, value is the
#### directory from which the files will be loaded.
#### Directory path may be a relative path
PolicyDirectoryPath .

#### To indicate whether to distribute policy in same operation.
#### If distribution file is in policyDistribution path and
#### PolicyDistribution parameter is not set to no the policy WILL be 
#### distributed.
#### Parameter takes either yes or no (case insensitive). Default = YES
PolicyDistribution yes

#### File where all error messages are logged.
ErrorLogFile policyImporter.log

#### To indicate the Action that the Policy Import tool will perform. 
#### Values are LOAD or REMOVE (case insensitive). Default = LOAD
#Action REMOVE

#### To indicate the Mode the Policy Import tool will be in 
#### Values are INITIAL or RECOVER (case insensitive). Default = INITIAL
#### This parameter can also be passed in as a commandline parameter -recover or 
#### -initial. 
#### Values on the command line will override values specified in the 
#### configuration file.
#Mode RECOVER

#### uncomment if you want to see debug information, Default = 0 (no debug)
#Debug 1

#### uncomment if you want to hide console interaction (yes/no), default = yes
#### If you want to run loader in background/in batch process, set this to no
ConsoleDisplay yes

Running the Policy Import Tool

After you complete the configuration file, you can run the Policy Import tool and import your policy files.

To run the Policy Import tool:

Prepare your policy data files.

You can create your own policy data files as described in Creating Policy Data Files for Importing or you can use files that you have exported from your policy database as described in Exporting Policy Data.

Create a configuration file to define your policy load.

You can use the ../examples/policy/policy_loader_sample.conf file as a template for your configuration file. Additionally, for a sample configuration file, see Sample Configuration File.

Run the Policy Import tool.

On a Microsoft Windows platform, run policyloader.bat
On a UNIX platforms, run: policyloader.sh

Check for errors in log file.

Note: If an error occurs, the Policy Loader terminates; you must restart the Policy Import tool. The name of the error file is defined in the your Policy Import tool configuration file by the ErrorLogFile parameter. In addition, to distribute policy you need distribution privileges granted to you.

Also, because the Policy Import tool is multi-threaded and each thread writes out to the log when it is complete, you cannot guarantee the order in which each load completes.

The Policy Import tool processes policy files according to a predefined order, and if the policy file is not found, it tries to load the next policy file in the proper order. Records imported successfully are committed to the database. After the import process begins, you cannot go back within the same process and edit changes you have made. If you want to change what you have done, you have to start a new import process. After the import process is complete, you may run the removal operation to reverse the import process.

Understanding How the Policy Loader Works

When an Object Exists Error occurs—indicating that you created a duplicate policy entry—the import process does not stop. When the Policy Import tool encounters an error other than the Object Exists Error, it generates a file named <filename>.<version> (for example, object.1 , object.2) and the error message is logged in the configured error file.

Once the policy loader has finished, you need to check to see if there are any versioned files. If there are such files, this indicates that there were errors in certain files and only the problematic lines from those files have been placed in the versioned files. You can now correct the mistakes in the versioned files and re-run the policy loader in the recover mode. You can do this in two ways. By either updating the mode in the configuration file to RECOVER or adding an extra command line argument (-recover) when running the policy loader again. Now the loader will only try to load the highest version files that has not already been previously loaded. If you corrected priv.1 and there are still problems, then the loader will now generate priv.2 with just the lines that filed. You now have to make the fix in priv.2 and rerun the policy loader in the recover mode. You need to keep doing this until the policy loader does not generate any new version files and the error log file does not have any errors listed in it for the last run.

Policy unloading works similar to policy loading except the order in which the files are read is reversed, and the policy is removed from the database instead of being added.

Exporting Policy Data

This section provides instructions and information on how to export policy data from the policy store. It covers the following topics:

Policy Exporter Tool

Policy exporting allows you to output data from the policy database to text files called policy files. These policy files can be imported back to the same or another policy database using the Policy Import tool, as described in Importing Policy Data. This tool allows you to transfer your policy data easily to a production environment.

To perform policy exporting, you need access to the policy database. In general, you can access the policy database when you are the policy owner or the database administrator.

All the files that are exported by the Policy Export tool are supported by the Policy Import tool. All the files are created even though some files may not contain any records. There are two other files exported: object_config, and objattr_config, that contain the data for SSM configuration. These files also get loaded and are similar to object and objattr respectively in format. These files are split so as to differentiate policy elements from configuration elements. However, the object_config and objattr_config files can be merged into object and objattr respectively, if needed.

Before You Begin

Before you begin, perform the following tasks:

Locate or create a target directory in which to store the policy files.

Ensure that the directory is not write-protected. The free space that the export requires depends on the size of your existing policy. If your export fails because of insufficient disk space, add more space before attempting the export again. In addition, ensure that the full directory path contains no white space.

Ensure that the database client is installed and configured, and that you have access to the database.

Depending on the database system, you need to have either the Oracle or Sybase client installed and configured to connect to the policy database. Make sure all the environment settings are correct as discussed in Database Setup in the Administration Application Installation Guide.
Make sure you can access the policy database using the isql (Sybase) or sqlplus (Oracle) command. You must be the policy owner or database administrator to run the export tool. When exporting, you are asked to provide the information for policy owner, your database login id and password.

Ensure that you can run the tools from the /bin subdirectory for the product installation.

You must run the exporting scripts in this directory because the scripts need to locate some files relative to this directory.
On a Microsoft Windows platform, you can open a DOS command prompt window and change to this directory.

Exporting Policy Data on Windows Platforms

This procedure exports your policy from the database into formatted text files. You perform this export using the export tool included as part of the Administration Application.

Before you begin, make sure you have the information listed in Table 4-12:

To export the policy data on a Windows platform, perform the following steps:

Open a command window and change to the \bin directory in the product installation. By default, this directory location is C:\bea\ales21-admin\bin.

Ensure that the current path (.) is included your PATH. Also, ensure that the Sybase or Oracle client environment is set up as discussed in Database Setup in the Installing the Administration Sever.

At the command prompt, do one of the following:

For Oracle, type the following command, and then press <Enter>: export_policy_oracle.bat server policyowner login password directory
For Sybase, type the following command, and then press <Enter>: export_policy_sybase.bat server databasename policyowner login password directory
where server, databasename, policyowner, login, and directory are as defined in Table 4-12. Table 4-12 Information Required to Export Policy Data Information Description server Name of your database server (Sybase) or the service name of the database server instance (Oracle). databasename Name of your database (Sybase only). policyowner Name of the owner of the policy database. This is usually the same as the username used to access your Sybase or Oracle database. Do not confused this with the database owner for Sybase. login Username used to access your Sybase or Oracle database. password Password used to access your Sybase or Oracle database. directory The target directory for the exported policy files. Be sure to include the full path of the directory. This directory cannot contain white space.

Information	Description
`server`	Name of your database server (Sybase) or the service name of the database server instance (Oracle).
`databasename`	Name of your database (Sybase only).
`policyowner`	Name of the owner of the policy database. This is usually the same as the username used to access your Sybase or Oracle database. Do not confused this with the database owner for Sybase.
`login`	Username used to access your Sybase or Oracle database.
`password`	Password used to access your Sybase or Oracle database.
`directory`	The target directory for the exported policy files. Be sure to include the full path of the directory. This directory cannot contain white space.

When exporting the policy, the configuration resources are saved to the following files: object_config and objattr_config. The Policy Import tool does not import these two files by default. If you want to import the configuration resources, you need to create a directory, and copy object_config, objattr_config, and binding into that directory. Rename object_config to object and objattr_config to objattr. Then you can configure the Policy Import tool to import these to file in this new directory.

Exporting Policy Data on UNIX Platforms

This procedure exports your policy from the database into formatted text files. You perform this export using the Policy Export tool included as part of the Administration Server.

Running the Policy Export tool on Sun Solaris requires the use of a shell script. If you do not normally use this shell or have difficulty running the tool, check with your UNIX system administrator to determine if it is available in your environment. For Linux, you can run this script from a Borne shell.

Before you begin, make sure you have the information listed in Table 4-12.

To export the policy data on a UNIX platform, perform the following steps:

Open a command window and change to BEA_HOME/ales21-admin/bin directory.

Ensure that all the *_oracle.sh (for Oracle) or *_sybase.sh files (for Sybase) have execution permission and that the current path (.) is included in the PATH environment variable. Also, ensure that the Oracle or Sybase client is set up as described in Database Setup in the Administration Application Installation Guide.

From the command line, enter the following command:

For Oracle: export_policy_oracle.sh<Enter>
For Sybase: export_policy_sybase.sh<Enter>

When the script prompts you to continue, type Y, and then press <Enter>.

When the script prompts you for the directory in which to save the policy files, type the full path directory name, and then press <Enter>.

When the script prompts you for your database server, type the name of your database server (Service Name in Oracle), and then press <Enter>.

With Sybase, the script may prompt you for your database name, type the name of your database, and then press <Enter>.

When the script prompts you for the policyowner, type the name of the database user who owns the policy schema, and then press <Enter>.

The policy owner is the owner of the policy database, (for example, the database schema owner). Do not confuse the database owner (dbo) with the policy owner in Sybase.

When the script prompts you for your Oracle or Sybase login ID, type your database username, and then press <Enter>.

When the script prompts you for your login password, type your database password, and then press <Enter>.

When the script completes, a successful message appears.

What's Next

Once you have exported the policy data, you can import the exported policy into policy database using the Policy Import tool. The exported policy files are in the format required by the Policy Import tool; however, you need to configure the tool to point to the exported file directory. You also need to create a policy distribution file distribution if you want the policy to be automatically distributed after the import completes. For additional information, see Importing Policy Data.

Upgrading an Administration Server to AquaLogic Enterprise Security 2.1

If you are upgrading your Administration Server from WebLogic Enterprise Security 4.2 to AquaLogic Enterprise Security 2.1 and you want to save any changes you may have made to the policies and security configuration provided with the product, you must export the policies, modify the policy file as instructed in this procedure, upgrade the Administration Server to ALES 2.1, and import the policies into the newly installed server.

The following changes were made to the default policy provided with the ALES 2.1 product:

The names of the following resources were changed:

//app/policy/WLES changed to //app/policy/ASI.
//app/policy/WLESRecovery changed to //app/policy/ASIRecovery.

The name of the default identity directory was changed from wles to asi. This is the directory where the user system resides.

To save your changes, perform the following steps:

Use the Export tool to export you policy data from the Administration Server. For instructions, see Exporting Policy Data.

Open the exported data files and make the following changes:

Change all occurrences of
//app/policy/WLES to
//app/policy/ASI.

Change all occurrences of
//app/policy/WLESRecovery to
//app/policy/ASIRecovery.

Change all occurrences of
//dir/wles to //dir/asi.

Change all occurrences of
//user/wles to //user/asi.

Change all occurrences of
//sgrp/wles to //sgrp/asi.

Change all occurrences of
//bind/wlesadmin to
//bind/asiadmin.

Change all occurrences of
//app/config/ssm/wlesadmin to
//app/config/ssm/asiadmin.

Change config__identity_scope S wles to
config__identity_scope S to asi.

Change config__name S wlesadmin to
config__name S asiadmin.

If it is necessary to save the Policy Queries Migration file (piquery), merge any multiple items into one line. Listing 4-9 shows an example.

Listing 4-9 Example of Merging Lines in the piquery File

change:

O 
//app/policy/MgrtOrg/MgrtBindingApp/MgrtBindingAppRes deny
//user/wles/system/

QueryAllUser

to:

O //app/policy/MgrtOrg/MgrtBindingApp/MgrtBindingAppRes deny 
//user/wles/system/QueryAllUser

Install the AquaLogic Enterprise Security 2.1 Administration Server.

Import the policy data into the newly installed Administration Server. For instructions, see Importing Policy Data.

Check to see if there are any versioned files (*.1) in the policy data directory. If so, open the *.1 files and check whether any of the data is related to the asi admin configuration data and whether it is different from the current configuration defined in the latest installation.