Skip navigation.
Downloads | Product Documentation | Support

Policy Managers Guide

# Creating Policy Data Files

Before you begin, you must understand the basic concepts of the BEA WebLogic Enterprise Security as described in the Introduction to BEA WebLogic Enterprise Security.

There are two ways to enter policy data into the Policy Database:

- Using the Administration Console
- Using the Policy Import tool

When viewing policy data in Administration Console, you are viewing the external representation. Internally, policy data names are represented with certain prefixes or suffixes. How these names are stored in the database is transparent to console user. However, when working with policy data files, you must use the internal representation of the policy data.

This section covers the following topics:

- Policy Data Files
- Policy Element Naming
- Sample Policy Files
- Resource Discovery
- What's Next?

# Policy Data Files

The Policy Import tool reads and imports policy data that are stored as text using a proprietary format. Most policy elements are stored in a separate file, referred to as a policy file. The policy files you can import, whose names are shown in square brackets, include:

- Application Bindings [binding]
- Attribute [attr]
- Declarations [decl]
- Directories [dir]
- Directory Attribute Schemas [schema]
- Mutually Exclusive Subject Groups [excl]
- Subject Group Membership [member]
- Policy Distribution [distribution]
- Policy Inquiry [piquery]
- Policy Verification [pvquery]
- Privileges [priv]
- Privilege Groups [privgrp]
- Privilege Bindings [privbinding]
- Resources [object]
- Resource Attributes [objattr]
- Roles [role]
- Rules [rule]
- Security Providers [engine]
- Subjects [subject]

Note: If you want to store users, groups, and their attributes from an external store, you can use the Metadata Directory tool, as described in the Administration Application Installation Guide. You cannot import these policy elements using the Policy Import tool.

# 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/wles/system/` and `//user/wles/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
- Policy Element Qualifiers
- Size Restriction on Policy Data
- Character Restrictions in Policy Data
- Special Names and Abbreviations

## 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 2K1 | 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/A2 | 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 condition 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 contrarian for a rule | 2000 | 580 | 1200 | 2500 | 4000
Integer value of a constant declaration | 9 digits*3 | 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 WebLogic Enterprise Security 4.2 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
- Directory Names
- Logical Name
- Declaration Names

### 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. As previously mentioned, a policy file is a text file that lists the relevant policy elements (as listed in Policy Data Files) using their fully qualified names. Sample files for each policy element are on your installation CD and are installed in the following directory when you install the product:

>     BEA_HOME\wles42-admin\examples\policy

For a description of each of these files, see the following topics:

- Application Bindings
- Attribute [attr]
- Declarations
- Directories
- Directory Attribute Schemas
- Mutually Exclusive Subject Groups [excl]
- Resources
- Resource Attributes
- Policy Distribution
- Policy Inquiry
- Policy Verification
- Privileges
- Privilege Bindings
- Privilege Groups
- Roles
- Rules
- Security Providers
- Security Providers

## Application Bindings

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

BEA WebLogic 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

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

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

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

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

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

WebLogic 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/wles/system/ Saved Policy Inquiry #1
>     O //app/policy/myApplication/myBinding  grant //user/wles/system/
>           Saved Policy Inquiry #1
>     S //wles/wles/userid/ grant //user/wles/system/ Saved Policy Inquiry #1

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

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

>     # Sample query 3:

>     P //priv/delete   grant //user/wles/system/ Policy Inquiry #3

>     # Sample query 4:

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

## Policy Verification

WebLogic 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/wles/system/ Policy Verification #1
>     LO //app/policy/myApp/firstResource //user/wles/system/ Policy Verification #1
>     RP //priv/create //user/wles/system/ Policy Verification #1
>     RO //app/policy/myApp/secondResource //user/wles/system/ Policy Verification #1

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

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

>     # Sample query 3:

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

>     # Sample query 4:

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

## Privileges

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

This file contains examples of how privileges are mapped 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

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

>     //grp/

Examples:

>     //grp/myPrivGroup

>     //grp/DevelopmentGroup

## Roles

This file defines several role names. Roles are used to construct policy rules. Each line contains a role name. Each role name is prefixed with:

>     //role/

Examples:

>     //role/Administrators

>     //role/operators

>     //role/managers

>     //role/public

## Rules

Rules are used by ASI Authorization provider and ASI Role Mapper provider 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/wles/system/);

>     grant(//priv/read, //app/policy/myApplication, //sgrp/wles/allusers/);

>     deny([//priv/read, //priv/search_text], //app/policy/myApplication/myBinding/confidentialDocument.one, //role/public);

>     delegate(//role/Administrators, //app/policy/myApplication, //user/wles/John Doe/, //user/wles/system/) if dayofweek in weekend;

## Security Providers

There are two types of distribution targets in BEA WebLogic 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``\wles42-ssm\apache-ssm\ instance\ <``instancename``>\bin`
IIS Web Server | `set-env.bat` (Windows only) | `BEA_HOME``\wles42-ssm\iis-ssm\instance\ <``instancename``>\bin`
Java | `set-env.bat (.sh` for Unix) | `BEA_HOME``\wles42-ssm\java-ssm\instance\<``instancename``>\bin`
Web Services | `wlesws.wrapper.conf` | `BEA_HOME``\wles42-ssm\webservice-ssm\ instance\<``instancename``>\config`
WebLogic Server 8.1 | `set-wls-env.bat` (`.sh` for Unix) | `BEA_HOME``\wles42-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 (ARME) 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
- Resource Transformation
- WebLogic Resource Transformation
- Java API Resource Transformation
- Action Transformation
- Attribute Transformations

## 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

WebLogic 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:

1. The application maps to an application
2. The resource type is: `url`.
3. The resource hierarchy is built from the context path and the URI.
4. The resource name is the last element of the URI.
5. 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 theWebLogic 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 | "srvr" |  | 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 WebLogic Enterprise Security for Java 4.2 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 policy, the policy data files can be exported from database using the Policy Export tool (as described in Exporting Policy Data, and imported back to another database using the Policy Import tool (as described in Importing Policy Data). If you have a lot of policy data and want to use a more expedient method of importing it, the Policy Import tool is recommended.