Skip Headers
Oracle® Fusion Middleware Application Security Guide
11g Release 1 (11.1.1)

Part Number E10043-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Managing the Policy Store

The following sections explain how an administrator can manage policies using either Fusion Middleware Control, OPSS scripts, or Oracle Entitlements Server:

This chapter also includes the following sections:

9.1 Managing the Policy Store

Only a user with the appropriate permissions, such as the domain administrator, can access data in the policy store.

The following sections explain how an administrator can manage policies using either Fusion Middleware Control, OPSS scripts, or Oracle Entitlements Server. Typical operations include:

To avoid unexpected authorization failures and to manage policies effectively, note the following important points:

Important Point 1:

Before deleting a user, revoke all permissions, application roles, and enterprise groups that have been granted to the user. If you fail to remove all security artifacts referencing a user to be deleted, they are left dangling and, potentially, be inadvertently inherited if another user with the same name or uid is created at a later time.

Similar considerations apply to when a user name or uid is changed: all policies (grants, permissions, groups) referring to old data must be updated so that it works as expected with the changed data.

See Section L.11, "User Gets Unexpected Permissions."

Important Point 2:

Policies use case sensitivity in names when they are applied. The best way to avoid possible authorization errors due to case in user or group names is to use the spelling of those names exactly as specified in the identity store.

It is therefore recommended that:

  • When provisioning a policy, the administrator spell the names of users and groups used in the policy exactly as they are in the identity repository. This guarantees that queries into the policy store (involving a user or group name) work as expected.

  • When entering a user name at run-time, the end-user enter a name that matches exactly the case of a name supplied in the identity repository. This guarantees that the user is authorized as expected.

See Section L.4, "Failure to Grant or Revoke Permissions - Case Mismatch."

Important Point 3:

The name of a resource type, a resource, or an entitlement can contain printable charactes only and it cannot start or end with a white space.

For other considerations regarding the use of characters in policies, in particular in role names, see Section L.16, "Characters in Policies."

Important Point 4:

Authorization failures are not visible, by default, in the console. To have authorization failures sent to the console you must set the system variable jps.auth.debug as follows: -Djps.auth.debug=true

In particular, to have JpsAuth.checkPermission failures sent to the console, you must set the variable as above.

9.2 Managing Policies with Fusion Middleware Control

Fusion Middleware Control allows managing system and application policies in a WebLogic domain, regardless of the type of policy store provider used in the domain, as explained in the following sections:

9.2.1 Managing Application Policies

This section explains how to use Fusion Middleware Control to manage application policies.

Note:

If multiple applications are to share a permission and to prevent permission check failures, the corresponding permission class must be specified in the system class path.

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Application Policies (if the application is deployed on Oracle WebLogic Server), or to Cell > Security > Application Policies (if it is deployed on WebSphere Application Server), to display the Application Policies page, partially illustrated in the following graphic:

    Surrounding text describes emapppols.gif.

    The area Policy Store Provider is read-only; when expanded, it displays the policy store provider currently in use in the domain or cell.

  2. To display policies in an application matching a given principal or permission, expand the Search area, select the application stripe to search, enter a string to match (a principal name, principal group, or application role), and click the blue button. The results of the search are displayed in the table at the bottom of the page.

  3. To create an application policy for the selected application stripe, click Create to display the Create Application Grant page where you add principals and permissions for the grant being created.

    1. To add permissions, click Add in the Permissions area to display the Add Permission dialog.

      In the Search area of that dialog, first select Permissions or Resource Types; if Permissions was selected, then identify permissions matching a class or resource name, and determine the Permission Class and Resource Name; if Resource Types was selected, then identify the resource types matching a type name, and determine a type; then click OK to return to the Create Application Grant page. The permission you selected is displayed in the table in the Permissions area.

    2. To add principals, click the button Add in the Grantee area to display the dialog Add Principal.

      In the Search area of that dialog, select a Type, enter strings to match principal names and display names, and click the blue button; the result of the query is displayed in the Searched Principals table; then select one or more rows from that table, and click OK to return to the Create Application Grant page. The principals you selected are displayed in the table in the Grantee area

    3. At any point you can remove an item from the table in the Grantee area by selecting it and clicking the Delete button; similarly, you can modify an item from that table by selecting it and clicking the Edit button.

    4. When finished, click OK to return to the Application Policies page. The principal and permissions of the policy created are displayed in the table at the bottom of the page.

  4. To create an application policy based on an existing one:

    1. Select an existing policy from the table.

    2. Click Create Like, to display the Create Application Grant Like page. Notice that in this page the table of permissions is automatically filled in with the data extracted from the policy you selected.

    3. Modify those values, as appropriate, as explained in the substeps of step 3 above, and then click OK.

9.2.2 Managing Application Roles

This section explains how to use Fusion Middleware Control to manage application roles.

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Application Roles (if the application is deployed on Oracle WebLogic Server), or to Cell > Security > Application Roles (if it is deployed on WebSphere Application Server), to display the Application Roles page partially illustrated in the following graphic:

    Surrounding text describes emapproles.gif.

    The area Policy Store Provider is read-only; when expanded, it displays the policy store provider currently in use in the domain or cell.

  2. To display roles in an application, expand the Search area, choose an application stripe to search, enter the data to match role names, and click the blue button. The results of the search are displayed in the table at the bottom of the page.

  3. To create an application role, click Create to display the Create Application Role page. Note that you need not enter data in all areas at once; for example, you could create a role by entering the role name and display name, save your data, and later on specify the members in it; similarly, you could enter data for role mapping at a later time.

    In the area General, specify the following attributes of the role being created:

    1. The name of the role, in the text box Role Name.

    2. Optionally, the name to display for the role, in the text box Display Name.

    3. Optionally, a description of the role, the text box Description.

    In the area Members, specify the users, groups, or other application roles, if any, into which the role being created is mapped.

    To add application roles to the application role being created:

    1. Click Add , to display the Add Principal dialog.

    2. In this dialog, select a Type (application role, group, or user), enter a string to match principal names, and click the blue button; the result of the search is displayed in the Searched Principals table; select one or more principals from that table.

    3. When finished, click OK to return to the Create Application Role page. The selected application roles are displayed in the table Members.

  4. At any point you can remove an item from the Members table by selecting it and clicking the Delete button; similarly, you can modify an item from the table by selecting it and clicking the Edit button.

  5. Click OK to effect the role creation (or updating) and to return to the Application Roles page. The role just created is displayed in the table at the bottom of that page.

  6. To create an application role based on an existing one:

    1. Select an existing role from the table.

    2. Click Create Like, to display the Create Application Role Like page. Notice that in this page some data is automatically filled in with the data extracted from the role you selected.

    3. Modify the list of roles and users, as appropriate, and then click OK.

To understand how permissions are inherited in a role hierarchy, see Section 2.2.1, "Permission Inheritance and the Role Hierarchy."

9.2.3 Managing System Policies

This section explains how to use Fusion Middleware Control to manage system policies for an Oracle WebLogic Server domain or for a WebSphere Application Server cell.

The procedure below enables creating two types of system policies: principal policies and codebase policies. A principal policy grants permissions to a list of users or groups. A codebase policy grants permissions to a piece of code, typically a URL or a JAR file; for example, an application using the Credential Store Framework requires an appropriate codebase policy. Wildcards and patterns are not supported in codebase URLs.

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > System Policies or to Cell > Security > System Policies, as appropriate, to display the System Policies page partially illustrated in the following graphic:

    Surrounding text describes emsyspols.gif.

    The area Policy Store Provider is read-only; when expanded, it displays the policy store provider currently in use in the domain or cell.

  2. To display system policies matching a given type, name, and permission, expand the Search area, enter the data to match, and click the blue button. The results of the search are displayed in the table at the bottom of the page; to display all current system policies, select the type All and leave the name and permission boxes blank.

  3. At any point, you can edit the characteristics of a selected policy by clicking the Edit button, or remove it from the list by clicking the Delete button.

To create a system policy:

  1. Click Create to display the Create System Grant page.

  2. Select type of policy to create: Principal or Codebase. The UI differs slightly depending on the type chosen; the steps below assume the selection Principal.

  3. To add permissions, click the button Add in the Permissions area to display the Add Permission dialog and choose a permission to add to the policy being created.

    1. Use the Search area to query permissions matching a type, principal name, or permission name. The result of the search is display in the table in the Search area.

    2. To choose the permission to add, select a permission from the table; note that, when a permission is selected, its details are rendered in the read-only Customize area.

    3. Click OK to return to the Create System Grant page. The selected permission is added to the table Permissions.

  4. At any point, you can select a permission from the Permissions table and use the button Edit to change the characteristics of the permission, or the button Delete to remove it.

  5. Click OK to return to the System Policies page.

  6. The table in the area Permissions for Codebase is read-only and it shows the resource name, actions, and permission class associated with a codebase system policy.

9.3 Managing Application Policies with OPSS Scripts

An OPSS script is either a WLST script, in the context of the Oracle WebLogic Server, or a WASAdmin script, in the context of the WebSphere Application Server. The scripts listed in this section apply to both platforms: WebLogic Application Server and WebSphere Application Server.

An online script is a script that requires a connection to a running server. Unless otherwise stated, scripts listed in this section are online scripts and operate on a policy store, regardless of whether it is file-, LDAP-, or DB-based. There are a few scripts that are offline, that is, they do not require a server to be running to operate.

Read-only scripts can be performed only by users in the following WebLogic groups: Monitor, Operator, Configurator, or Admin. Read-write scripts can be performed only by users in the following WebLogic groups: Admin or Configurator. All WLST scripts are available out-of-the-box with the installation of the Oracle WebLogic Server.

WLST scripts can be run in interactive mode or in script mode. In interactive mode, you enter the script at a command-line prompt and view the response immediately after. In script mode, you write scripts in a text file (with a py file name extension) and run it without requiring input, much like the directives in a shell script.

WASAdmin scripts can be run in interactive mode only.

Important Note

Before invoking an OPSS script you must run (according to the platform you use) one of the scripts below to ensure that the required JARs are added to the class path.

On WebLogic:

>sh $ORACLE_HOME/common/bin/wlst.sh

To run an online script, you must connect to a WebLogic server as follows:

>java weblogic.WLST
>connect('servername', 'password', 'localhost:portnum')

For details about running OPSS scripts on WebSphere, see Oracle Fusion Middleware Third-Party Application Server Guide.

OPSS provides the following scripts on all supported platforms to administer application policies (all scripts are online, unless otherwise stated):

All class names specified in the above scripts must be fully qualified path names. The argument appStripe refers to the application stripe (typically, identical to the application name) and identifies the subset of policies pertaining to a particular application.

For important information about the authenticated and the anonymous roles and WLST scripts, see Section 9.5, "Granting Policies to Anonymous and Authenticated Roles with WLST Scripts."

For the correct usage of the application stripe in versioned applications, see Section 9.6, "Application Stripe for Versioned Applications in WLST Scripts."

9.3.1 listAppStripes

The script listAppStripes lists application stripes. This script can be run in offline or online mode. When run in offline mode, a configuration file must be passed, and it lists the application stripes in the policy store referred to by the configuration in the default context of the passed configuration file. When run in online mode, a configuration file must not be passed, and it lists stripes in the policy store of the domain to which you connect. In any mode, if a regular expression is passed, it lists the application stripes with names that match the regular expression; otherwise, it lists all application stripes.

If this command is used in offline mode after reassociating to a DB-based, the configuration file produced by the reassociation must be manually edited as described in Running an Offline Script after Reassociating to a DB-Based Store.

Script Mode Syntax

listAppStripes.py [-configFile configFileName]
                  [-regularExpression aRegExp]

Interactive Mode Syntax

listAppStripes([configFile="configFileName"] [, regularExpression="aRegExp"])

The meanings of the arguments are as follows:

  • configFile specifies the path to the OPSS configuration file. Optional. If specified, the script runs offline; the default context in the specified configuration file must not have a service instance reference to an identity store. If unspecified, the script runs online and it lists application stripes in the policy store.

  • regularExpression specifies the regular expression that stripe names returned should match. Optional. If unspecified, it matches all names. To match substrings, use the character *.

Examples of Use

The following (online) invocation returns the list of application stripes in the policy store:

listAppStripes.py

The following (offline) invocation returns the list of application stripes in the policy store referenced in the default context of the specified configuration file:

listAppStripes.py -configFile /home/myFiles/jps-config.xml

The following (online) invocation returns the list of application stripes that contain the prefix App:

listAppStripes.py -regularExpression App*

9.3.2 createAppRole

The script createAppRole creates an application role in the policy store with given application stripe and role name.

Script Mode Syntax

createAppRole.py -appStripe appName 
              -appRoleName roleName

Interactive Mode Syntax

createAppRole(appStripe="appName", appRoleName="roleName")

The meanings of the arguments (all required) are as follows:

  • appStripe specifies an application stripe.

  • appRoleName specifies a role name.

Example of Use

The following invocation creates an application role with application stripe myApp and role name myRole:

createAppRole.py -appStripe myApp -appRoleName myRole

9.3.3 deleteAppRole

The script deleteAppRole removes an application role from the passed stripe. Specifically, this script applies a cascading deletion by removing:

  • All grants where the role is present

  • The role from any other role of which it is a member

  • All roles that are member of the role

Script Mode Syntax

deleteAppRole.py -appStripe appName -appRoleName roleName

Interactive Mode Syntax

deleteAppRole(appStripe="appName", appRoleName="roleName")

The meanings of the arguments (all required) are as follows:

  • appStripe specifies an application stripe.

  • appRoleName specifies a role name.

Example of Use

The following invocation removes the role with application stripe myApp and name myRole:

deleteAppRole.py -appStripe myApp -appRoleName myRole

9.3.4 grantAppRole

The script grantAppRole adds a principal (class and name) to a role with a given application stripe and name, and it can be used to build or modify an application role hierarchy.

Script Mode Syntax

grantAppRole.py -appStripe appName
             -appRoleName roleName
             -principalClass className
             -principalName prName

Interactive Mode Syntax

grantAppRole(appStripe="appName", appRoleName="roleName", principalClass="className", principalName="prName")

The meanings of the arguments (all required) are as follows:

  • appStripe specifies an application stripe.

  • appRoleName specifies a role name.

  • principalClass specifies the fully qualified name of a class; this class must be included in the class path so that it is available at runtime. Typically, if the principal is a user, the class is weblogic.security.principal.WLSUserImpl, and if the principal is a group, the class is weblogic.security.principal.WLSGroupImpl.

  • principalName specifies the principal name.

Example of Use

The following invocation adds the principal myPrincipal, defined by the default principal implementation class WLSGroupImpl, to the role myRole in the application stripe myApp:

grantAppRole.py -appStripe myApp 
             -appRoleName myRole 
             -principalClass weblogic.security.principal.WLSGroupImpl
             -principalName myPrincipal

9.3.5 revokeAppRole

The script revokeAppRole removes a principal (class and name) from a role with a given application stripe and name, and it can be used to modify an application role hierarchy.

Script Mode Syntax

revokeAppRole.py -appStripe appName 
              -appRoleName roleName 
              -principalClass className 
              -principalName prName

Interactive Mode Syntax

revokeAppRole(appStripe="appName", appRoleName="roleName", principalClass="className", principalName="prName")

The meanings of the arguments (all required) are as follows:

  • appStripe specifies an application stripe.

  • appRoleName specifies a role name.

  • principalClass specifies the fully qualified name of the principal class.

  • principalName specifies the principal name.

Example of Use

The following invocation removes the principal myPrincipal, defined by the default principal implementation class WLSGroupImpl, from the role myRole in the application stripe myApp:

revokeAppRole.py -appStripe myApp 
              -appRoleName myRole 
              -principalClass weblogic.security.principal.WLSGroupImpl
              -principalName myPrincipal

9.3.6 listAppRoles

The script listAppRoles lists all roles with a given application stripe.

Script Mode Syntax

listAppRoles.py -appStripe appName

Interactive Mode Syntax

listAppRoles(appStripe="appName")

The meaning of the argument (required) is as follows:

  • appStripe specifies an application stripe.

Example of Use

The following invocation returns all the roles with application stripe myApp:

listAppRoles.py -appStripe myApp

9.3.7 listAppRolesMembers

The script listAppRoleMembers lists all members in a role with a given application stripe and role name.

Script Mode Syntax

listAppRoleMembers.py -appStripe appName 
                   -appRoleName roleName

Interactive Mode Syntax

listAppRoleMembers(appStripe="appName", appRoleName="roleName")

The meanings of the arguments (all required) are as follows:

  • appStripe specifies an application stripe.

  • appRoleName specifies a role name.

Example of Use

The following invocation returns all the members in a role with application stripe myApp and name myRole:

listAppRoleMembers.py -appStripe myApp
                   -appRoleName myRole

9.3.8 grantPermission

The script grantPermission creates a permission granted to a codebase or URL or principal, in either an application policy or the global policy section.

Script Mode Syntax

grantPermission [-appStripe appName] 
                        [-codeBaseURL url] 
                [-principalClass prClassName] 
                [-principalName prName] 
                -permClass permissionClassName
                [-permTarget permName]
                [-permActions comma_separated_list_of_actions]

Interactive Mode Syntax

grantPermission([appStripe="appName",] [codeBaseURL="url",] [principalClass="prClassName",] [principalName="prName",] permClass="permissionClassName", [permTarget="permName",]
[permActions="comma_separated_list_of_actions"])

The meanings of the arguments (optional arguments are enclosed in between square brackets) are as follows:

  • appStripe specifies an application stripe. If not specified, then the script works on system policies.

  • codeBaseURL specifies the URL of the code granted the permission.

  • principalClass specifies the fully qualified name of a class (grantee).

  • principalName specifies the name of the grantee principal.

  • permClass specifies the fully qualified name of the permission class.

  • permTarget specifies, when available, the name of the permission target. Some permissions may not include this attribute.

  • permActions specifies the list of actions granted. Some permissions may not include this attribute and the actions available depend on the permission class.

Examples of Use

The following invocation creates an application permission (for the application with application stripe myApp) with the specified data:

grantPermission.py -appStripe myApp
                                -principalClass my.custom.Principal
                -principalName manager
                -permClass java.security.AllPermission

The following invocation creates a system permission with the specified data:

grantPermission.py -principalClass my.custom.Principal
                -principalName manager
                -permClass java.io.FilePermission
                -permTarget /tmp/fileName.ext
                -permActions read,write

9.3.9 revokePermission

The script revokePermission removes a permission from a principal or codebase defined in an application or the global policy section.

Script Mode Syntax

revokePermission [-appStripe appName] 
                         [-codeBaseURL url] 
                 [-principalClass prClassName] 
                 [-principalName prName] 
                 -permClass permissionClassName
                 [-permTarget permName]
                 [-permActions comma_separated_list_of_actions]

Interactive Mode Syntax

revokePermission([appStripe="appName",][codeBaseURL="url",]
[principalClass="prClassName",] [principalName="prName",] 
permClass="permissionClassName", [permTarget="permName",] [permActions="comma_separated_list_of_actions"])

The meanings of the arguments (optional arguments are enclosed in between square brackets) are as follows:

  • appStripe specifies an application stripe. If not specified, then the script works on system policies.

  • codeBaseURL specifies the URL of the code granted the permission.

  • principalClass specifies the fully qualified name of a class (grantee).

  • principalName specifies the name of the grantee principal.

  • permClass specifies the fully qualified name of the permission class.

  • permTarget specifies, when available, the name of the permission target. (Note that some permissions may not include this attribute.)

  • permActions specifies the list of actions removed. Note that some permissions may not include this attribute and the actions available depend on the permission class.

Examples of Use

The following invocation removes the application permission (for the application with application stripe myApp) with the specified data:

revokePermission.py -appStripe myApp
                                 -principalClass my.custom.Principal
                 -principalName manager
                 -permClass java.security.AllPermission

The following invocation removes the system permission with the specified data:

revokePermission.py -principalClass my.custom.Principal
                 -principalName manager
                 -permClass java.io.FilePermission
                 -permTarget /tmp/fileName.ext
                 -permActions read,write

9.3.10 listPermissions

The script listPermissions lists all permissions granted to a given principal.

Script Mode Syntax

listPermissions [-appStripe appName] 
                -principalClass className 
                -principalName prName

Interactive Mode Syntax

listPermissions([appStripe="appName",] principalClass="className", principalName="prName") 

The meanings of the arguments (optional arguments are enclosed in between square brackets) are as follows:

  • appStripe specifies an application stripe. If not specified, then the script works on system policies.

  • principalClass specifies the fully qualified name of a class (grantee).

  • principalName specifies the name of the grantee principal.

Examples of Use

The following invocation lists all permissions granted to a principal by the policies of application myApp:

listPermissions.py -appStripe myApp
                -principalClass my.custom.Principal 
                -principalName manager

The following invocation lists all permissions granted to a principal by system policies:

listPermissions.py -principalClass my.custom.Principal
                -principalName manager

9.3.11 deleteAppPolicies

The script deleteAppPolicies removes all policies with a given application stripe.

Script Mode Syntax

deleteAppPolicies -appStripe appName 

Interactive Mode Syntax

deleteAppPolicies(appStripe="appName") 

The meaning of the argument (required) is as follows:

  • appStripe specifies an application stripe. If not specified, then the script works on just system policies.

Example of Use

deleteAppPolicies -appStripe myApp

9.3.12 createResourceType

The script createResourceType inserts a new <resource-type> entry in the policy store within a given application stripe and with specified name, display name, description, and actions. Optional arguments are enclosed in between square brackets; all other arguments are required.

Script Mode Syntax

createResourceType -appStripe appStripeName 
                   -resourceTypeName resTypeName
                   -displayName displName
                   -description descripString
                           [-provider resTypeProvider]
                           [-matcher resTypeClass]
                           -actions resTypeActions
                           [-delimiter delimChar]

Interactive Mode Syntax

createResourceType(appStripe="appStripeName", resourceTypeName="resTypeName", displayName="displName", description="descripString" 
[, provider="resTypeProvider", matcher="resTypeClass"], actions="resTypeActions"[, delimiter="delimChar"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where to insert the resource type.

  • resourceTypeName specifies the name of the resource type to insert.

  • displayName specifies the name for the resource type used in UI gadgets.

  • description specifies a brief description of the resource type.

  • provider specifies the provider for the resource type.

  • matcher specifies the class of the resource type. If unspecified, it defaults to oracle.security.jps.ResourcePermission.

  • actions specifies the actions allowed on instances of the resource type.

  • delimiter specifies the character used to delimit the list of actions. If unspecified, it defaults to comma ','.

Example of Use

The following invocation creates a resource type in the stripe myApplication with actions BWPrint and ColorPrint delimited by a semicolon:

createResourceType -appStripe myApplication
                   -resourceTypeName Printer
                   -displayName PRINTER
                   -description A resource type representing a Printer
                   -provider Printer
                   -matcher com.printer.Printer
                   -allowedActions BWPrint;ColorPrint
                   -delimiter ;

9.3.13 getResourceType

The script getResourceType returns the relevant parameters of a <resource-type> entry in the policy store within a given application stripe and with specified name.

Script Mode Syntax

getResourceType -appStripe appStripeName 
                -resourceTypeName resTypeName

Interactive Mode Syntax

getResourceType(appStripe="stripeName", resourceTypeName="resTypeName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe from where to fetch the resource type.

  • resourceTypeName specifies the name of the resource type to fetch.

Example of Use

The following invocation fetches the resource type myResType from the stripe myApplication:

getResourceType -appStripe myApplication
                -resourceTypeName myResType

9.3.14 deleteResourceType

The script deleteResourceType removes a resource type with a given name from the passed application stripe. This script applies a cascading deletion by removing all resource instances of the resource type from entitlements and all grants that use resource instances of the resource type.

Important:

A resource type cannot be modified after it has been created. If you need to modify a resource type in any way (such as adding, renaming, or deleting an action in it), you must delete the resource type and create a new one with the appropriate values. Specifically, you must:

  • Create a new resource type.

  • Create the required new resource instances.

  • Create the required grants.

Script Mode Syntax

deleteResourceType -appStripe appStripeName 
                   -resourceTypeName resTypeName

Interactive Mode Syntax

deleteResourceType(appStripe="stripeName", resourceTypeName="resTypeName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe from where to remove the resource type.

  • resourceTypeName specifies the name of the resource type to remove.

Example of Use

The following invocation removes the resource type myResType from the stripe myApplication:

deleteResourceType -appStripe myApplication
                   -resourceTypeName myResType

9.3.15 createResource

The script createResource creates a new resource of a specified type in a specified application stripe. The passed resource type must exist in the passed application stripe.

Script Mode Syntax

createResource -appStripe appStripeName 
               -name resName
               -type resTypeName
               [-displayName dispName]
               [-description descript]

Interactive Mode Syntax

createResource(appStripe="appStripeName", name="resName", type="resTypeName" [,-displayName="dispName"] [,-description="descript"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the resource is created.

  • name specifies the name of the resource created.

  • type specifies the type of resource created. The passed resource type must be present in the application stripe at the time this script is invoked.

  • diplayName specifies the display name of the resource created. Optional.

  • description specifies the description of the resource created. Optional.

Example of Use

The following invocation creates the resource myResource in the stripe myApplication:

createResource -appStripe myApplication 
               -name myResource 
               -type myResType
               -displayName myNewResource

9.3.16 deleteResource

The script deleteResource deletes a resource and all its references from entitlements in an application stripe. The script performs a cascading deletion: if the entitlement refers to one resource only, it removes the entitlement; otherwise, it removes from the entitlement the resource actions for the passed type.

Script Mode Syntax

deleteResource -appStripe appStripeName 
               -name resName
               -type resTypeName

Interactive Mode Syntax

deleteResource(appStripe="appStripeName", name="resName", type="resTypeName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the resource is deleted.

  • name specifies the name of the resource deleted.

  • type specifies the type of resource deleted. The passed resource type must be present in the application stripe at the time this script is invoked.

Example of Use

The following invocation deletes the resource myResource in the stripe myApplication:

deleteResource -appStripe myApplication 
               -name myResource 
               -type myResType

9.3.17 listResources

The script listResources lists resources in a specified application stripe. If a resource type is specified, it lists all the resources of the specified resource type; otherwise, it lists all the resources of all types.

Script Mode Syntax

listResources -appStripe appStripeName 
             [-type resTypeName]

Interactive Mode Syntax

listResources(appStripe="appStripeName" [,type="resTypeName"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the resources are listed.

  • type specifies the type of resources listed. The passed resource type must be present in the application stripe at the time this script is invoked.

Examples of Use

The following invocation lists all resources of type myResType in the stripe myApplication:

listResources -appStripe myApplication 
              -type myResType

The following invocation lists all resources in the stripe myApplication:

listResources -appStripe myApplication 

9.3.18 listResourceActions

The script listResourceActions lists the resources and actions in an entitlement within an application stripe.

Script Mode Syntax

listResourceActions -appStripe appStripeName 
                    -permSetName entitlementName

Interactive Mode Syntax

listResourceActions(appStripe="appStripeName", permSetName="entitlementName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement resides.

  • permSetName specifies the name of the entitlement whose resources and actions to list.

Example of Use

The following invocation lists the resources and actions of the entitlement myEntitlement in the stripe myApplication:

listResourceActions -appStripe myApplication 
                    -permSetName myEntitlement

9.3.19 createEntitlement

The script createEntitlement creates a new entitlement with just one resource and a list of actions in a specified application stripe. Use addResourceToEntitlement to add additional resources to an existing entitlement; use revokeResourceFromEntitlement to delete resources from an existing entitlement.

Script Mode Syntax

createEntitlement -appStripe appStripeName 
                  -name entitlementName
                  -resourceName resName
                  -actions actionList
                  [-displayName dispName]
                  [-description descript]

Interactive Mode Syntax

createEntitlement(appStripe="appStripeName", name="entitlementName", resourceName="resName", actions="actionList" [,-displayName="dispName"] [,-description="descript"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is created.

  • name specifies the name of the entitlement created.

  • resourceName specifies the name of the one resource member of the entitlement created.

  • actions specifies a comma-separated the list of actions for the resource resourceName.

  • diplayName specifies the display name of the resource created. Optional.

  • description specifies the description of the entitlement created. Optional.

Example of Use

The following invocation creates the entitlement myEntitlement with just the resource myResource in the stripe myApplication:

createEntitlement -appStripe myApplication 
                  -name myEntitlement
                  -resourceName myResource
                  -actions read,write

9.3.20 getEntitlement

The script getEntitlement returns the name, display name, and all the resources (with their actions) of an entitlement in an application stripe.

Script Mode Syntax

getEntitlement -appStripe appStripeName 
               -name entName

Interactive Mode Syntax

getEntitlement(appStripe="appStripeName", name="entName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is located.

  • name specifies the name of the entitlement to access.

Example of Use

The following invocation returns the information of the entitlement myEntitlement in the stripe myApplication:

getEntitlement -appStripe myApplication 
               -name myEntitlement

9.3.21 deleteEntitlement

The script deleteEntitlement deletes an entitlement in a specified application stripe. The script performs a cascading deletion by removing all references to the specified entitlement in the application stripe.

Script Mode Syntax

deleteEntitlement -appStripe appStripeName 
                  -name entName

Interactive Mode Syntax

deleteEntitlement(appStripe="appStripeName", name="entName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is deleted.

  • name specifies the name of the entitlement to delete.

Example of Use

The following invocation deletes the entitlement myEntitlement in the stripe myApplication:

deleteEntitlement -appStripe myApplication 
                  -name myEntitlement

9.3.22 addResourceToEntitlement

The script addResourceToEntitlement adds a resource with specified actions to an entitlement in a specified application stripe. The passed resource type must exist in the passed application stripe.

Script Mode Syntax

addResourceToEntitlement -appStripe appStripeName 
                         -name entName
                         -resourceName resName
                         -resourceType resType
                         -actions actionList

Interactive Mode Syntax

addResourceToEntitlement(appStripe="appStripeName", name="entName", resourceName="resName",actions="actionList")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is located.

  • name specifies the name of the entitlement to modify.

  • resourceName specifies the resource to add.

  • resourceType specifies the type of the resource to add. The passed resource type must be present in the application stripe at the time this script is invoked.

  • actions specifies the comma-separated list of actions for the added resource.

Example of Use

The following invocation adds the resource myResource to the entitlement myEntitlement in the application stripe myApplication:

addResourceToEntitlement -appStripe myApplication 
                         -name myEntitlement 
                         -resourceName myResource
                         -resourceType myResType
                         -actions view,edit

9.3.23 revokeResourceFromEntitlement

The script revokeResourceFromEntitlement removes a resource from an entitlement in a specified application stripe.

Script Mode Syntax

revokeResourceFromEntitlement -appStripe appStripeName 
                              -name entName
                              -resourceName resName                                
                              -resourceType resTypeName
                              -actions actionList

Interactive Mode Syntax

revokeResourceFromEntitlement(appStripe="appStripeName", name="entName", resourceName="resName" ,-resourceType="resTypeName", actions="actionList")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is located.

  • name specifies the name of the entitlement to modify.

  • resourceName specifies the type of resource to remove.

  • resourceType specifies the type of the resource to remove.

  • actions specifies the comma-separated list of actions to remove.

Example of Use

The following invocation removes the resource myResource from the entitlement myEntitlement in the stripe myApplication:

revokeResourceFromEntitlement -appStripe myApplication 
                              -name myEntitlement 
                              -resourceName myResource
                              -resourceType myResType
                              -actions view,edit

9.3.24 listEntitlements

The script listEntitlements lists all the entitlements in an application stripe. If a resource name and a resource type are specified, it lists the entitlements that have a resource of the specified type matching the specified resource name; otherwise, it lists all the entitlements in the application stripe.

Script Mode Syntax

listEntitlements -appStripe appStripeName 
                 [-resourceTypeName resTypeName]
                 [-resourceName resName]

Interactive Mode Syntax

listEntitlements(appStripe="appStripeName" [,resourceTypeName="resTypeName", resourceName="resName"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe from where to list entitlements.

  • resourceTypeName specifies the name of the type of the resources to list. Optional.

  • resourceName specifies the name of resource to match. Optional.

Examples of Use

The following invocation lists all the entitlements in the stripe myApplication:

listEntitlements -appStripe myApplication 

The following invocation lists all the entitlements in the stripe myApplication that contain a resource type myResType and a resource whose name match the resource name myResName:

listEntitlements -appStripe myApplication 
                 -resourceTypeName myResType
                 -resourceName myResName

9.3.25 grantEntitlement

The script grantEntitlement creates a new entitlement with a specified principal in a specified application stripe.

Script Mode Syntax

grantEntitlement -appStripe appStripeName 
                 -principalClass principalClass
                 -principalName principalName
                 -permSetName entName

Interactive Mode Syntax

grantEntitlement(appStripe="appStripeName", principalClass="principalClass", principalName="principalName" ,-permSetName="entName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is created.

  • principalClass specifies the class associated with the principal.

  • principalName specifies the name of the principal to which the entitlement is granted.

  • permSetName specifies the name of the entitlement created.

Example of Use

The following invocation creates the entitlement myEntitlement in the stripe myApplication:

grantEntitlement -appStripe myApplication 
                 -principalClass oracle.security.jps.service.policystore.ApplicationRole
                 -principalName myPrincipalName
                 -permSetName myEntitlement

9.3.26 revokeEntitlement

The script revokeEntitlement deletes an entitlement and revokes the entitlement from the principal in a specified application stripe.

Script Mode Syntax

revokeEntitlement -appStripe appStripeName 
                  -principalClass principalClass
                  -principalName principalName
                  -permSetName entName

Interactive Mode Syntax

revokeEntitlement(appStripe="appStripeName", principalClass="principalClass", principalName="principalName" ,-permSetName="entName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is deleted.

  • principalClass specifies the class associated with the principal.

  • principalName specifies the name of the principal to which the entitlement is revoked.

  • permSetName specifies the name of the entitlement deleted.

Example of Use

The following invocation deletes the entitlement myEntitlement in the stripe myApplication:

revokeEntitlement -appStripe myApplication 
                  -principalClass oracle.security.jps.service.policystore.ApplicationRole
                  -principalName myPrincipalName
                  -permSetName myEntitlement

9.3.27 listEntitlement

The script listEntitlement lists an entitlement in a specified application stripe. If a principal name and a class are specified, it lists the entitlements that match the specified principal; otherwise, it lists all the entitlements.

Script Mode Syntax

listEntitlement -appStripe appStripeName 
                [-principalName principalName
                -principalClass principalClass]

Interactive Mode Syntax

listEntitlement(appStripe="appStripeName" [, principalName="principalName", principalClass="principalClass"])

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the entitlement is located.

  • principalName specifies the name of the principal to match. Optional.

  • principalClass specifies the class of the principal to match. Optional.

Example of Use

The following invocation lists all entitlements in the stripe myApplication:

listEntitlement -appStripe myApplication 

9.3.28 listResourceTypes

The script listResourceTypes lists all the resource types in a specified application stripe.

Script Mode Syntax

listResourceTypes -appStripe appStripeName 

Interactive Mode Syntax

listResourceTypes(appStripe="appStripeName")

The meaning of the arguments is as follows:

  • appStripe specifies the application stripe where the resource types are located.

Example of Use

The following invocation lists all resource types in the stripe myApplication:

listResourceTypes -appStripe myApplication 

9.3.29 reassociateSecurityStore

The script reassociateSecurityStore migrates the OPSS security store from a source to a target LDAP- or DB-based store, and it resets the default policy and credential services to the target repository. It also allows specifying that the OPSS security store be shared with that in a different domain (see optional argument join below). The OPSS binaries and the target policy store must have compatible versions; for details, see Section L.21, "Incompatible Versions of Binaries and Policy Store."

The source can be a file-, LDAP-, or DB-based store; the only type of LDAP target supported is Oracle Internet Directory; the only type of DB target supported is DB_ORACLE. This script uses and modifies the domain configuration file jps-config.xml, and it is supported in only the interactive mode.

For recommendations involving reassociation, see Important Points. After reassociating to a DB-based store and before using any OPSS script in offline mode, some manual editing is necessary; for details, see Running an Offline Script after Reassociating to a DB-Based Store.

Interactive Mode Syntax

The script syntax varies slightly according to the type of the target store.

When the target is an LDAP-based store, use the following syntax:

reassociateSecurityStore(domain="domainName", servertype="OID",  ldapurl="hostAndPort", jpsroot="cnSpecification", admin="cnSpecification", password="passWord" [,join="trueOrfalse"][,keyFilePath="dirLoc", keyFilePassword="password") 

When the target is a DB-based store, use the following syntax:

reeassociateSecurityStore(domain="domainName", servertype="DB_ORACLE", datasourcename="datasourceName", jpsroot="jpsRoot"[,admin="adminAccnt"] [,password="passWord"][join="trueOrfalse"][)

The meaning of the arguments (all required) is as follows:

  • domain: on WebLogic, specifies the domain name where the reassociating takes place; on WebSphere, specifies the WebSphere cell name.

  • admin specifies, in case of an LDAP target, the administrator's user name on the target server, and the format is cn=usrName.
    In case of a DB target, it is required only when the DB has a protected data source (protected with user/password); in this case, it specifies the user name set to protect the data source when the data source was created; that user and password must be present in the bootstrap credential store.

  • password specifies the password associated with the user specified for the argument admin. It is required in case of an LDAP target.

    In case of a DB target, it is required only when the DB has a protected data source; in this case, it specifies the password associated with the user specified for the argument admin.

  • ldapurl specifies the URI of the LDAP server. The format is ldap//:host:port, if you are using the default port, or ldaps://host:port, if you are using an anonymous SSL or one-way SSL transmission. The secure port must be configured to handle the desired SSL connection mode, and must be distinct from the default (non-secure) port.

  • servertype specifies the kind of the target LDAP server or DB server. The only valid types are OID and DB_ORACLE.

  • jpsroot specifies the root node in the target LDAP repository under which all data is migrated. The format is cn=nodeName.

  • join specifies whether the domain is to share an OPSS security store in another domain. Optional. Set to true to share an existing store in another domain; set to false otherwise. If unspecified, it defaults to false. The use of this argument allows multiple WebLogic domains to point to the same logical OPSS security store.

    Important:

    When an OPSS security store is reassociated with join=true, the bootstrap wallet from the first domain must be manually copied to the second domain. The reason for this requirement is that the first domain generates a local key that is used to encrypt the keystore data and the second domain needs to have the same key in its bootstrap wallet in order to decrypt that data.

  • datasourcename specifies the JNDI name of the JDBC data source; this should be identical to the value of the JNDI name data source entered when the data source was created; see Section 8.3.1.3, "Creating a Data Source Instance."

  • keyFilePath specifies the directory where the file ewallet.p12 is created; the content of this file is encrypted and secured by the value passed to keyFilePassword. Optional. Use in conjucntion with argument keyFilePassword.

  • keyFilePassword specifies the password to secure the file ewallet.p12. Optional. Use in conjucntion with argument keyFilePath.

Examples of Use

reassociateSecurityStore(domain="myDomain", admin="cn=adminName", password="myPass", ldapurl="ldaps://myhost.example.com:3060", servertype="OID", jpsroot="cn=testNode")

Suppose that you want some other domain (distinct from myDomain, say otherDomain) to share the policy store in myDomain. Then you would invoke the script as follows:

reassociateSecurityStore(domain="otherDomain", admin="cn=adminName", password="myPass", ldapurl="ldaps://myhost.example.com:3060", servertype="OID", jpsroot="cn=testNode", join="true")

9.3.30 Running an Offline Script after Reassociating to a DB-Based Store

The jps configuration file produced by the reassociation to a DB-based stored cannot be passed, as is, to any offline OPSS script. Before running an OPSS script in offline mode after having reassociated to a DB-based store, the configuration file must be edited manually as described below.

The following examples illustrate fragments of jps configuration files before and after reassociating to a DB-based OPSS security store, and the changes required on the configuration file produced by the reassociation.

Before Reassociation

The following fragment illustrates the configuration of a file-based policy store before being reassociated to a DB-based store:

<serviceInstance name="policystore.xml" provider="policystore.xml.provider" location="./system-jazn-data.xml">
  <description>File Based Policy Store Service Instance</description>
</serviceInstance>
 

After Reassociation

The following fragment illustrates the property set props.db.1 in the file generated by the reassociation of the above store to a DB-based store:

<propertySet name="props.db.1">
  <property value="cn=soa_domain" name="oracle.security.jps.farm.name"/>
  <property value="cn=jpsroot" name="oracle.security.jps.ldap.root.name"/>
  <property value="jdbc/opss" name="datasource.jndi.name"/>
</propertySet>
 
<serviceInstance provider="policystore.provider" name="policystore.db">
  <property value="DB_ORACLE" name="policystore.type"/>
  <propertySetRef ref="props.db.1"/>
</serviceInstance>
 

Required Editing

The property set above must be replaced with the following:

<propertySet name="props.db.1">
    <property value="cn=myDomain" name="oracle.security.jps.farm.name"/>
    <property value="DB_ORACLE" name="server.type"/>
    <property value="cn=myRoot" name="oracle.security.jps.ldap.root.name"/>
    <property name="jdbc.url" value="jdbc:oracle:thin:@myhost.com:1521/srv_name"/>
    <property name="jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="bootstrap.security.principal.key" value="myKeyName" />
    <property name="bootstrap.security.principal.map" value="myMapName" />
</propertySet> 

The value of the property jdbc.url must match the name of the JDBC data source entered when the data source was created; the values of the bootstrap credentials (map and key) must match those passed to the OPSS script addBootStrapCredential when the bootstrap was created.

The edited file can then be passed to the offline script.

9.4 Caching and Refreshing the Cache

OPSS optimizes the authorization process by caching security artifacts.

When an application policy (or some other security artifact) is modified, the change becomes effective depending on where the application and the tool used to modified the artifact are running:

9.4.1 An Example

The following use case illustrates the authorization behavior in four scenarios when (from a different domain or host) Oracle Entitlements Server is used to modify security artifacts, and the property oracle.security.jps.policystore.refresh.interval is set to 10 minutes.

The use case assumes that:

  • A user is member of an enterprise role.

  • That enterprise role is included as a member of an application role.

  • The application role is granted a permission that governs some application functionality.

Under the above assumptions, we now examine the authorization result in the following four scenarios.

Scenario A

  1. The user logs in to the application.

  2. The user accesses the functionality secured by the application role.

  3. From another host (or domain), Oracle Entitlements Server is used to remove the enterprise role from the application role.

  4. The user logs out from the application, and immediately logs back in.

  5. The user is still able to access the functionality secured by the application role.

The reason for this outcome is that the policy cache has not yet been refreshed with the change introduced in step 3 above.

Scenario B

  1. The user logs in to the application.

  2. The user accesses the functionality secured by the application role.

  3. From another host (or domain), Oracle Entitlements Server is used to remove the enterprise role from the application role.

  4. The user logs out from the application, and logs back in after 10 minutes.

  5. The user is not able to access the functionality secured by the application role.

The reason for this outcome is that the policy cache has been refreshed with the change introduced in step 3 above.

Scenario C

  1. The user logs in to the application.

  2. The user accesses the functionality secured by the application role.

  3. From another host (or domain), Oracle Entitlements Server is used to remove the enterprise role from the application role.

  4. The user does not log out and remains able to access the functionality secured by the application role within 10 minutes.

The reason for this outcome is that the policy cache has not yet been refreshed with the change introduced in step 3 above.

Scenario D

  1. The user logs in to the application.

  2. The user accesses the functionality secured by the application role.

  3. From another host (or domain), Oracle Entitlements Server is used to remove the enterprise role from the application role.

  4. The user does not log out, waits more than 10 minutes, and then attempts to access the functionality secured by the application role: the access is denied.

The reason for this outcome is that the policy cache has been refreshed with the change introduced in step 3 above.

9.5 Granting Policies to Anonymous and Authenticated Roles with WLST Scripts

Several WLST scripts require the specification of the principal name and the principal class for a role involved in the operation.

For example, the following invocation adds a principal to the role with application stripe myApp and name myAppRole:

grantAppRole.py -appStripe myApp -appRoleName myAppRole 
                -principalClass myPrincipalClass -principalName myPrincipal

When in such scripts the principal refers to the authenticated role or the anonymous role, the principal names and principal classes are fixed and must be one of the following pairs:

The list of WLST scripts that required the above principal name and class specification are the following:

9.6 Application Stripe for Versioned Applications in WLST Scripts

Several WLST scripts require the specification of an application stripe. If the application is not versioned, the application stripe defaults to the application name. Otherwise, if the application is versioned, the application name and the application stripe are not identical.

For example, the name of a versioned application with name myApp and version 1 is displayed myApp(v1.0) in Fusion Middleware Control pages, but the application stripe of this application is myApp#v1.0.

In general, an application with display name appName(vers) has application stripe appName#vers. It is this last string that should be passed as the application stripe in WLST scripts, as illustrated in the following invocation:

>listAppRoles myApp#v1.0

The list of WLST scripts that can use stripe specification are the following:

9.7 Managing Application Policies with Oracle Entitlements Server

Oracle Entitlements Server allows managing and searching application policies and other security artifacts in a WebLogic domain that uses an Oracle Internet Directory LDAP policy store.

For details, see the following topics in Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server:

9.8 Guidelines to Configure the Policy Store

For details about OPSS properties tune up, see section Oracle Platform Security Services Tuning in Oracle Fusion Middleware Performance and Tuning Guide.