Home / Middleware / Oracle Platform Security Services

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

• 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

10.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, 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 J.4.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 J.4.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 J.9.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.

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

• Managing Application Policies

• Managing Application Roles

• Managing System Policies

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

10.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 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.

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.

10.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 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 used in the domain.

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."

10.2.3 Managing System Policies

This section explains how to use Fusion Middleware Control to manage system policies for an Oracle WebLogic Server domain.

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 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 used in the domain.

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.

10.3 Managing Application Policies with WLST commands

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, LDAP, 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 command 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."

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

• listPermissions

• deleteAppPolicies

• createResourceType

• getResourceType

• deleteResourceType

• createResource

• deleteResource

• listResources

• listResourceActions

• createEntitlement

• getEntitlement

• deleteEntitlement

• addResourceToEntitlement

• revokeResourceFromEntitlement

• listEntitlements

• grantEntitlement

• revokeEntitlement

• listResourceTypes

• reassociateSecurityStore

• migrateSecurityStore. see Section 9.6.2, "Migrating with the Script migrateSecurityStore"

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

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

10.3.1 reassociateSecurityStore

The command reassociateSecurityStore migrates the OPSS security store from a source to a target LDAP- or DB-based store, and it resets services in the files jps-config.xml and jps-config-jse.xml 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 OPSS security store must have compatible versions; for details, see Section J.8.1, "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 command is supported in only the interactive mode.

The command resets the bootstrap credentials with the appropriate parameters passed (see arguments admin and password below); the bootstrap credentials are the credentials used to access the target store. For an alternate way to reset bootstrap credentials, see modifyBootStrapCredential and addBootStrapCredential scripts.

For recommendations involving reassociation, see Important Points.

Interactive Mode Syntax

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

When the target is an LDAP-based store, use the following syntax (arguments are displayed in separate lines for clarity only):

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 (arguments are displayed in separate lines for clarity only):

reeassociateSecurityStore(domain="domainName", 
       servertype="DB_ORACLE", 
       datasourcename="datasourceName", 
       jpsroot="jpsRoot",
       jdbcurl="jdbcURL",
       jdbcdriver="jdbcDriverClass",
       dbUser="dbUserName",
       dbPassword="dbPassword",
       [admin="adminAccnt", password="passWord",]
       [join="trueOrfalse" 
          [,keyFilePath="<directory location>",keyFilePassword="<password>"]]
       [odbcdsn="odbcDsnSting"])

The meaning of the arguments is as follows:

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

• 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. If specified, then password must also be specified.

• 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. If specified, then admin must also be specified.

• 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 or 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.

  Note 1:

  When an OPSS security store is reassociated to another one with join=true, OPSS encryption keys must be exported from one domain and imported into the other domain, and the file keystores.xml must also be copied from one domain onto the other.

  This note explains a way to accomplished this task; for an alternate way, see note in the description of argument keyFilePath.

  Specifically, assume that Domain1 has a security store and Domain2 has reassociated to Domain1's security store using join=true; then proceed as follows:

  1. Use the WLST command exportEncryptionKey to extract the key from Domain1 into the file ewallet.p12; note that the value of the argument keyFilePassword passed must be used later when importing that key into the second domain.

  2. Use the WLST command importEncryptionKey to import the extracted ewallet.p12 into Domain2; note that the value of the argument keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.

  3. Copy the Domain1's file keystores.xml to the Domain2. If a keystore.xml is present in Domain2, overwrite it.

     Note that any keystore service changes introduced in Domain2 (apart from the out-of-the-box seetings) will be lost; this is expected since the intent is to join an already existing security store.

  4. Restart Domain2's server.

  For details about the scripts to import or export keys, see exportEncryptionKey and importEncryptionKey.

• 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.

• 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. Must be used with arguments keyFilePassword and join.

  Note 2:

  When an OPSS security store is reassociated to another one with join=true, OPSS encryption keys must be exported from one domain and imported into the other domain, and the file keystores.xml must also be copied from one domain onto the other.

  This note explains a way to accomplished this task; for an alternate way, see note in the description of argument join.

  When using the arguments keyFilePath and keyFilePassword, the export-import of keys is automatically done by the command reassociateSecurityStore; however, the file keystores.xml must be manually copied before the command is run.

  Specifically, assume that Domain1 has a security store and Domain2 is to reassociate to Domain1's security store using join=true and the keyFile arguments; then proceed as follows:

  1. Before running reassociateSecurityStore, copy the Domain1's file keystores.xml to the Domain2. If a keystore.xml is present in Domain2, overwrite it.

     Note that any keystore service changes introduced in Domain2 (apart from the out-of-the-box seetings) will be lost; this is expected since the intent is to join an already existing security store.

  2. Run the command reassociateSecurityStore with the appropriate argument values.

  3. Restart Domain2's server.

• keyFilePassword specifies the password to secure the file ewallet.p12. Optional. Must be used with arguments keyFilePath and join.

• jdbcurl specifies the jdbc URL use by a Java SE application to connect to the database. Applies only to Java SE applications. Required. Must be used with arguments jdbcdriver, dbUser, and dbPassword.

• jdbcdriver specifies the class of the jdbc driver used to connect to the database. Required. Must be used with argument jdbcurl.

• dbUser specifies the database user in the credential store to be added to the bootstrap credentials. Required. Must be used with argument jdbcurl .

• dbPassword specifies specifies the password of the user specified by dbUser. Required. Must be used with argument jdbcurl.

• odbcdsn specifies the odbc DSN name used by the C CSF API. Applies only to C programs.

Examples of Use

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

To share the OPSS security store in myDomain, you would invoke the command as in the following sample:

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

10.4 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 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.

10.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.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.

10.5 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

10.6 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

10.7 Managing Application Policies with Oracle Entitlements Server

Oracle Entitlements Server allows managing and searching application policies and other security artifacts in a WebLogic domainOracle Internet Directory.

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

• Querying Security Artifacts

• Managing Policies and Roles