9 Managing the Policy Store

This chapter explains how a security administrator can manage policies using either Fusion Middleware Control, WLST commands, or Oracle Entitlements Server.

These topics are presented in the following sections:

• Determining the Domain Security Store Characteristics

• Managing the Policy Store

• Managing Policies with Fusion Middleware Control

• Managing Application Policies with WLST Commands

• Caching and Refreshing the Cache

• Granting Policies to Anonymous and Authenticated Roles with WLST Commands

• Application Stripe for Versioned Applications in WLST Commands

• Managing Application Policies with Oracle Entitlements Server

9.1 Determining the Domain Security Store Characteristics

The offline WLST command listSecurityStore can be used by an administrator to determine the several attributes of the domain security store. For details about this command, see listSecurityStoreInfo.

9.2 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, WLST commands, or Oracle Entitlements Server. Typical operations include:

• Managing Policies with Fusion Middleware Control

• Managing Application Policies with WLST Commands

• Managing Application Policies with Oracle Entitlements Server

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 K.5.4, "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 K.5.2, "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 characters 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 K.10.5, "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.3 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:

• Managing Application Policies

• Managing Application Roles

• Managing System Policies

For procedures to manage other service providers, see Section 8.8, "Configuring Services Providers with Fusion Middleware Control."

9.3.1 Managing Application Policies

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

Note1:

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.

Note2:

A DB-based security store and the domain must be located in the same machine.

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:

   
   

   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.3.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:

   
   

   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.3.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. Wildcard 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:

   
   

   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.

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.4 Managing Application Policies with WLST Commands

A WLST command can be invoked in the context of the Oracle WebLogic Server, or as a WASAdmin script, in the context of the WebSphere Application Server. The commands listed in this section apply to both platforms: WebLogic Application Server and WebSphere Application Server.

An online command is a command that requires a connection to a running server. Unless otherwise stated, scripts listed in this section are online scripts and operate on the OPSS security store, regardless of its type( file, OID, or DB). 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 commands are available out-of-the-box with the installation of the Oracle WebLogic Server.

WLST commands can be run in interactive mode or in script mode. In interactive mode, you enter the script at a command-line prompt. 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.

Note:

Before invoking a WLST command you must run one of the scripts below to ensure that the required JARs are added to the class path.

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

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

>java weblogic.WLST
>connect('userName', 'userPassword', 'url', 'adminServerName')

In regards to configuration files and JVMs, see note in Section 5.6, "Typical Security Practices with WLST Commands."

For details about running WLST commands 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):

• listSecurityStoreInfo

• listAppStripes

• listCodeSourcePermissions

• createAppRole

• deleteAppRole

• grantAppRole

• revokeAppRole

• listAppRoles

• listAppRolesMembers

• grantPermission

• revokePermission

• listPermission

• deleteAppPolicies

• createResourceType

• getResourceType

• deleteResourceType

• createResource

• deleteResource

• listResources

• listResourceActions

• createEntitlement

• getEntitlement

• deleteEntitlement

• addResourceToEntitlement

• revokeResourceFromEntitlement

• listEntitlements

• grantEntitlement

• revokeEntitlement

• listResourceTypes

• reassociateSecurityStore

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 commands, see Section 9.6, "Granting Policies to Anonymous and Authenticated Roles with WLST Commands."

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

9.5 Caching and Refreshing the Cache

This topic applies to LDAP- and DB-based OPSS security stores only. In case of a file-based store, the cache is updated after a few seconds (file-based stores are not recommended in production systems.)

OPSS optimizes the authorization process by caching security artifacts. When an application policy (or some other security artifact) is modified, the change becomes effective at different times depending on where the application and the tool used to modified the artifact are running:

• If both the application and the tool are running on the same host and in the same domain, the change becomes effective immediately.

• Otherwise, if the application and the tool are running on different hosts or in different domains, the change becomes effective after the policy store cache is refreshed. The frequency of the cache refresh is determined by the value of the property oracle.security.jps.ldap.policystore.refresh.interval. The default value is 10 minutes.

  Within a domain, any changes effected via a WLST command or Fusion Middleware Control are first accounted on the administrator server only; those changes are pushed to all managed servers in the domain only when the server is restarted.

9.5.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.ldap.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.6 Granting Policies to Anonymous and Authenticated Roles with WLST Commands

Several WLST commands 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:

• Authenticated role

  • Name: authenticated-role

  • Class: oracle.security.jps.internal.core.principals.JpsAuthenticatedRoleImpl

• Anonymous role

  • Name: anonymous-role

  • Class: oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl

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

• grantAppRole

• revokeAppRole

• grantPermission

• revokePermission

• listPermissions

9.7 Application Stripe for Versioned Applications in WLST Commands

Several WLST commands 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 commands, as illustrated in the following invocation:

>listAppRoles myApp#v1.0

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

• createAppRole

• deleteAppRole

• grantAppRole

• revokeAppRole

• listAppRoles

• listAppRoleMembers

• grantPermission

• revokePermission

• listPermissions

• deleteAppPolicies

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

• Querying Security Artifacts

• Managing Policies and Roles