7 OPSS Authorization and the Policy Store

The domain policy store is the repository of system and application-specific policies. In a given domain, there is one store that stores all policies (and credentials) that all applications deployed in the domain may use.

For an introduction to the main features of the policy store, see Policy Store Basics.

This chapter is divided into the following sections:

Configuring a Domain to Use an LDAP-Based Policy Store
Reassociating the Domain Policy Store
Migrating Policies to the Domain Policy Store
Managing the Domain Policy Store
Configuring Other Artifacts with Oracle Fusion Middleware Control
Configuring LDAP-Based Policy Stores

For further details about JavaEE and WebLogic Security, see section J2EE and WebLogic Security in Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server.

Note:

When a domain is setup to use policies based on the Policy Store, as explained in this chapter, then JACC policies and the Java Security Manager become unavailable on all managed servers in that domain.

Important:

All permission classes used in policies must be included in the class path, so the policy provider can load them when a service instance is initialized.

7.1 Configuring a Domain to Use an LDAP-Based Policy Store

An LDAP-based policy store is typically used and recommended in production environments. The LDAP server supported in this release is the Oracle Internet Directory.

The characteristics of the domain policy store and the domain credential store are tightly correlated: both must be of the same kind (file-based or LDAP-based), and in case of LDAP-based repositories, both must use the same type of LDAP server. Out-of-the-box, the policy and credential stores are file-based.

To use a domain LDAP-based policy store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or WLST commands.

For a detail list of properties that can be specified in a service instance, see Appendix F, "Generic LDAP Properties."

The information is presented in the following sections:

Multiple-Node Server Environments
Prerequisites to Using an LDAP-Based Policy Store

7.1.1 Multiple-Node Server Environments

In domains where several server instances are distributed across multiple machines, it is highly recommended that the domain policy and credential stores be LDAP-based, so that all policy and credential data is kept and maintained in one centralized store.

Typically, applications do not change policy data. When they do, however, it is crucial that these changes be correctly propagated to all managed servers and clusters in a domain and, therefore, any such changes should always be performed in the domain administration server (and not by managed servers).

In a single-node server domain, the propagation of local changes to security data is irrelevant: in this scenario, local changes are equivalent to global changes.

In a multiple-node server domain, however, the JMX framework propagates local changes to a file-based policy to each runtime environment, so that the data is refreshed based on caching policies and configuration.

To summarize, in a multiple-node server environment, it is highly recommended that:

Both the domain policy and credential stores be centralized in a LDAP-based store and configured in the administration server.
Or, if they are file-based, then local changes to policy or credential data be performed only by the domain administration server to ensure that they are correctly propagated from the administration server to all managed servers in the domain.

7.1.2 Prerequisites to Using an LDAP-Based Policy Store

In order to ensure the proper access to the Oracle Internet Directory), you must set a node in the server directory.

Fusion Middleware Control automatically provides bootstrap credentials in the file cwallet.sso when it is used to reassociate to an LDAP-based repository. To specify them manually, see section Section 14.4.7, "Specifying Bootstrap Credentials Manually."

Setting a Node in an Oracle Internet Directory Server

The following procedure is carried out by an Oracle Internet Directory administrator.

To set a node in the LDAP Oracle Internet Directory directory, proceed as follows:

Create an LDIF file (assumed jpstestnode.ldif, for illustration purpose) specifying the following DN and CN entries:
```
dn: cn=jpsroot
cn: jpsroot
objectclass: top
objectclass: OrclContainer
```
The distinguished name of the root node (illustrated by the string jpsroot above) must be distinct from any other distinguished name. Some LDAP servers enforce case sensitivity by default. One root node can be shared by multiple WebLogic domains. It is not required that this node be created at the top level, as long as read and write access to the subtree is granted to the Oracle Internet Directory administrator.
Import this data into the LDAP server using the command ldapadd, as illustrated in the following example (there should be no line break in the command invocation):
```
>ldapadd -h ldap_host -p ldap_port -D cn=orcladmin -w password -c -v -f  jpstestnode.ldif
```
Verify that the node has been successfully inserted using the command ldapsearch, as illustrated in the following example (there should be no line break in the command invocation):
```
>ldapsearch -h ldap_host -p ldap_port -D cn=orcladmin -w password 
-b "cn=jpsroot" objectclass="orclContainer"
```
Run the utility oidstats.sql to generate database statistics for optimal database performance, as illustrated in the following example:
```
>$ORACLE_HOME/ldap/admin/oidstats.sql
```
The above utility must be run just once after the initial provisioning. For details about this utility, consult the Oracle Fusion Middleware User Reference for Oracle Identity Management.

To reassociate a policy store, see Reassociating the Domain Policy Store.

7.2 Reassociating the Domain Policy Store

Reassociating the policy store consists in migrating policy data from a file- or LDAP-based repository to an LDAP-based repository, that is, reassociation changes the repository preserving the integrity of the data stored. For each policy in the source policy store, reassociation searches the target LDAP directory and, if it finds a match, it updates the matching policy as appropriate. If none is found, it simply migrates the policy as is.

At any time, after a domain policy store has been instantiated, a file- or LDAP-based policy store can be reassociated into an LDAP-based policy store storing the same data. To support it, the domain has to be configured, as appropriate, to use and LDAP policy store.

Reassociation is carried out using either Fusion Middleware Control or the WLST command reassociateSecurityStore. This operation is typically performed when setting a domain to use the an LDAP-based domain store instead of the out-of-the-box file-based store.

Important:

The repositories for the policy store and the credential store must both be file-based or both LDAP-based. Moreover, in the LDAP-based case, both stores must use the same kind of LDAP server. To preserve this coherence, note that reassociating one store implies reassociating the other one.

7.2.1 Reassociating Domain Stores with Fusion Middleware Control

The reassociation of security stores migrates policies and credentials from one repository to another, thus reconfiguring those security store providers; this reconfiguration is typically performed when, for example, transitioning from a test environment to a production environment. OPSS supports LDAP- to LDAP-based or file- to LDAP-based reassociation, where the LDAP server is the Oracle Internet Directory. LDAP- to file- based reassociation, however, is not supported.

This section explains the steps you follow to reassociate policies and credentials to an LDAP-based storage using Oracle Internet Directory.

To reassociate domain stores manually, use the WLST command reassociateSecurityStore.

For information about other uses of the Security Provider Configuration page, see Configuring Other Artifacts with Oracle Fusion Middleware Control.

Notes:

The procedure below reassociates both the policy and the credential stores to the same LDAP-based store.
Before starting a reassociation ensure that you have accomplished the requisites in Prerequisites to Using an LDAP-Based Policy Store.
If reassociation is to use a one-way SSL, follow the instructions in Setting Up a One- Way SSL Connection before initiating the reassociation (with either Fusion Middleware Control or the WLST command reassociateSecurityStore).
After reassociation, to secure access to the root node of the Oracle Internet Directory store, follow the instructions in Securing Access to Oracle Internet Directory Nodes.

To reassociate both the policy and the credential stores in a given domain to a new LDAP repository with Fusion Middleware Control, proceed as follows:

Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration, to display the Security Provider Configuration page. This page is partially illustrated in the following graphic:

The table underneath the button Change Association shows the characteristics of the current provider configured in the domain.
Click the button Change Association in the area Policy and Credential Store Providers to display the page Set Security Provider, partially illustrated in Figure 7-1.

Figure 7-1 Configuring a Security Provider
In the LDAP Server Details area, specify details and connection information about the target LDAP server:
1. Enter the host name and port number of your target OID LDAP server.
2. Optionally, check the box Use SSL to Connect to establish an anonymous SSL transmission to the LDAP server.
  
  When checking this box, keep in mind the following points:
  
  The port of the target LDAP server must be configured to handle an anonymous SSL transmission; this port is distinct from the default (non-secure) LDAP server port.
  
  If the reassociation is to use a one-way SSL, be sure to follow the instructions in Setting Up a One- Way SSL Connection before completing this step. Among other things, that set up identifies the port to support a one-way SSL channel, and it is that port that should be specified in this step. Reassociation through a two-way SSL channel is not supported in this release.
  
  Fusion Middleware Control modifies the file weblogic.policy by adding the necessary grant to support the anonymous SSL connection.
3. In the text box Connect DN, enter the full distinguished name, a string containing between 1 and 256 characters. For example, cn=orcladmin,dc=us,dc=oracle,dc=com.
4. In the box Password, enter the user password, also a string containing between 1 and 256 characters.
5. To verify that the connection to the LDAP server using the entered data works, click the button Test LDAP Authentication. If you run into any connection problem, see Section J.10, "Failure to Establish an Anonymous SSL Connection."
In the LDAP Root Node Details area, enter the root DN in the box JPS Root DN, which identifies the top of the tree that contains the data in the LDAP repository. The Domain Name defaults to the name of the selected domain.

To solve most common errors arising from the specifications in these two fields, see Section J.2, "Reassociation Failure."
In the Policy Store Properties and Credential Store Properties areas, optionally, enter service instance properties, such as Enable Lazy Load and Role Member Cache Size.

To add a new property: click Add to display the Add New Property dialog; in this dialog, enter strings for Property Name and Value; click OK. The added property-value pair is displayed in the table Custom Properties.

These properties are typically used to initialize the instance when it is created.

A property-value pair you enter modifies the domain configuration file jps-config.xml by adding a <property> element in the configuration of the LDAP service instance.

To illustrate how a service instance is modified, suppose you enter the property name foo and value bar; then the configuration for the LDAP service instance changes to contain a <property> element as illustrated in the following excerpt:
```
<serviceInstance name="myNewLDAPprovider" provider="someProvider"
  ...
  <property name="foo" value="bar"/>
  ...
</serviceInstance>
```
When finished entering your data, click OK to return to the Security Provider Configuration page. The system displays a dialog notifying the status of the reassociation. The table in the Policy and Credential Store Providers area is modified to show, as the current provider, the provider you have just specified.
Restart the Oracle WebLogic Server. Changes do not take effect until the server has been restarted.

Reassociation modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml: it deletes any configuration for the old store provider, inserts a configuration for the new store provider, and moves the policy and credential information from the source to the destination store.

If the destination store is LDAP-based, the information is stored under the domain DN according to the following format:

cn=<domain_name>,cn=JpsContext,<JPS ROOT DN>

As long as the configuration of the installation relies upon the above domain DN, that node should not be deleted from the LDAP Server.

7.2.1.1 Setting Up a One- Way SSL Connection

This section describes how to set up a one-way SSL channel between the Oracle WebLogic server and a target LDAP Oracle Internet Directory store to reassociate domain stores. This setup should be in place before using Fusion Middleware Control or the WLST command reassociateSecurityStore.

Prerequisite: Configuring the Oracle Internet Directory Server

To configure the Oracle Internet Directory server to listen in one-way SSL mode, see section Enabling SSL on Oracle Internet Directory Listeners in Oracle Fusion Middleware Administrator's Guide.

Exporting Oracle Internet Directory's Certificate Authority (CA)

The use of orapki to create a certificate is needed only if the CA is unknown to the Oracle WebLogic server.

The following sample illustrates the use of this command to create the certificate serverTrust.cert:

>orapki wallet export -wallet CA -dn "CN=myCA" -cert serverTrust.cert

The above invocation prompts the user to enter the keystore password.

Setting Up the WebLogic Server

To set up the server whose domain includes the stores to be reassociated, proceed as follows:

If the CA is known to the Oracle WebLogic server, skip this step; otherwise, use the utility keytool to import the Oracle Internet Directory's CA into the WebLogic truststore.

The following invocation, which outputs the file myKeys.jks, illustrates the use of this command to import the file serverTrust.cert:
```
>keytool -import -v -trustcacerts -alias trust -file serverTrust.cert -keystore myKeys.jks -storepass keyStorePassword
```
Use the WebLogic Administration Console to set, in the appropriate domain, a truststore that points to the file myKeys.jks, as follows:
1. Navigate to Environment > Servers.
2. Select the name of the administration server in your domain.
3. Select the tab Keystore.
4. Change the keystore mode from Demo Identity and Demo Trust to Custom Identity and Custom Trust.
5. In the Trust section enter data as follows: in the field Custom Trust Keystore, enter the absolute path name of the keystore file myKeys.jks; in the field Keystore Type, enter JKS; in the fields Custom Trust Keystore Passphrase and Confirm Custom Trust Keystore Passphrase, enter the keystore password.
Modify the script (typically startWebLogic.sh) that starts your server to include a line like the following, and then restart the server:
```
-Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>
```

7.2.1.2 Securing Access to Oracle Internet Directory Nodes

The procedure explained in this section is optional and performed only to enhance the security to access an Oracle Internet Directory.

An access control list (ACL) is a list that specifies who can access information and what operations are allowed on the Oracle Internet Directory directory objects. The control list is specified at a node, and its restrictions apply to all entries in the subtree under that node.

ACL can be used to control the access to policy and credential data stored in an LDAP Oracle Internet Directory repository, and it is, typically, specified at the top, root node of the store.

To specify an ACL at a node in an Oracle Internet Directory repository, proceed as follows:

Create an LDIF file with a content that specifies the ACL:
```
dn: <storeRootDN>
changetype: modify
add: orclACI
access to entry by dn="<userDN>" (browse,add,delete) by * (none)
access to attr=(*) by dn="<userDN>" (search,read,write,compare) by * (none)
```
where storeRootDN stands for a node (typically the root node of the store), and userDN stands for the DN of the administrator data (the same userDN that was entered to perform reassociation).
Use the Oracle Internet Directory utility ldapmodify to apply these specifications to the Oracle Internet Directory.

Here is an example of an LDIF file specifying an ACL:

dn: cn=jpsRootNode
changetype: modify
add: orclACI
access to entry by dn="cn=myAdmin,cn=users,dc=us,dc=oracle,dc=com" (browse,add,delete) by * ( none )
access to attr=(*) by dn="cn=myAdmin,cn=users,dc=us,dc=oracle,dc=com" (search,read,write,compare) by * (none)

For more information about access control lists and the command ldapmodify, see chapter 18 in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

7.2.2 Reassociating Domain Stores with the Command reassociateSecurityStore

Domain stores can also be manually reassociated with the WLST command reassociateSecurityStore. For details about this command, see reassociateSecurityStore.

7.2.3 Cataloging Oracle Internet Directory Attributes

An Oracle Internet Directory attribute used in a search filter must be indexed and cataloged. These operations are optional but recommended for OPSS-related attributes since they improve performance.

In a production environment, it is recommended that attribute indexing and cataloging be performed after the reassociation of the domain policy store has been completed.

For details about managing attribute catalogs and identifying whether an attribute is indexed, see the following sections in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory:

Adding an Index to a New Attribute by Using Oracle Directory Services Manager
Adding an Index to an Existing Attribute by Using Oracle Directory Services Manager
Dropping an Index from an Attribute by Using Oracle Directory Services Manager
Indexing an Attribute for Which Data Exists by Using Oracle Directory Services Manager
Creating and Dropping Indexes from Existing Attributes Using Catalog

The command ldapmodify, who se syntax is illustrated below, can also be used to index attributes specified in an LDIF file:

>ldapmodify -h <host> -p <port> -D <bind DN> -w <bind password> -v -f <catalogue modify ldif file name>

For example, the above command can be used with the following sample LDIF file to catalog the attributes createtimestamp and modifytimestamp:

dn: cn=catalogs
changetype: modify
add: orclindexedattribute
orclindexedattribute: modifytimestamp
orclindexedattribute: createtimestamp

Each of the following Oracle Internet Directory attributes must be indexed:

orclrolescope

orclassignedroles

orclApplicationCommonName

orclAppFullName

orclCSFAlias

orclCSFKey

orclCSFName

orclCSFDBUrl

orclCSFDBPort

orclCSFCredentialType

orclCSFExpiryTime

modifytimestamp

createtimestamp

orcljpsassignee

7.3 Migrating Policies to the Domain Policy Store

A domain includes one and only one policy store. Applications can specify their own policies, but these are stored as policies in the domain policy store when the application is deployed to a server. Thus, all applications deployed in a domain use a common policy store, the domain policy store. The domain policy store is logically partitioned in stripes, one for each application name specified in the file $DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml under the element <applications>.

During application development, an application specifies its own policies, and these can be migrated to the domain policy store when the application is deployed with Fusion Middleware Control. Policies can also be migrated manually; in addition, each application component can specify the use of anonymous user and role, authenticated role, and JAAS mode.

The configuration of the domain policy store is performed by the domain administrator.

These topics are explained in the following sections:

Migrating Application Policies with Fusion Middleware Control
Migrating Policies with the Command migrateSecurityStore

Note:

Use the system property jps.deployment.handler.disabled to disable the migration of application policies and credentials for applications deployed in a WebLogic Server.

When this system property is set to TRUE, the migration of policies and credentials at deployment is disabled for all applications regardless of the particular application settings in the application file weblogic-application.xml.

7.3.1 Migrating Application Policies with Fusion Middleware Control

Application policies are specified in the application file jazn-data.xml and can be migrated to the domain policy store when the application is deployed to a server in the WebLogic environment with Fusion Middleware Control; they can also be removed from the domain policy store when the application is undeployed or be updated when the application is redeployed.

All three operations, the migration, the removal, and the updating of application policies, can take place regardless of the type of policy repository, but they do require particular configurations.

For details, see procedure in Section 6.5.2, "Migrating Policies and Credentials at Deployment."

7.3.2 Migrating Policies with the Command migrateSecurityStore

Application-specific policies or system policies can be migrated manually from a source repository to a target repository using the WLST command migrateSecurityStore.

This command is offline, that is, it does not require a connection to a running server to operate; therefore, the configuration file passed to the argument configFile need not be an actual domain configuration file, but it can be assembled just to specify the source and destination repositories of the migration.

Note:

Since the command migrateSecurityStore recreates GUIDs and takes a long time to migrate large volume of data, you may want to consider migrating stores with an alternate procedure that uses Oracle Internet Directory bulk operations. For details, see Section 6.5.2.3, "Migrating Large Volume Policy and Credential Stores.".

For further details about WLST commands and their syntax, see section Overview of WLST Command Categories, in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

To migrate all policies (system and application-specific, for all applications) use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type policyStore
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext

migrateSecurityStore(type="policyStore", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")

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

configFile specifies the location of a configuration file jps-config.xml relative to the directory where the command is run. Typically, this configuration file is created just to be used with the command and serves no other purpose. This files contains two jps-contexts that specify the source and destination stores.

In addition, if the migration involves one or two LDAP-based stores, then this file must contain a bootstrap jps-context that refers to the location of a cwallet.sso file where the credentials to access the LDAP based involved in the migration are kept. See second example below.
src specifies the name of a jps-context in the configuration file passed to the argument configFile.
dst specifies the name of another jps-context in the configuration file passed to the argument configFile.

The contexts passed to src and dst must be defined in the passed configuration file and must have distinct names. From these two contexts, the command determines the locations of the source and the target repositories involved in the migration.

To migrate just system policies, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type globalPolicies
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext

migrateSecurityStore(type="globalPolicies", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")

The meanings of the arguments (all required) are identical to the previous case.

To migrate just application-specific policies, for one application, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type appPolicies
                        -configFile jpsConfigFileLocation
                        -src srcJpsContext
                        -dst dstJpsContext
                        -srcApp srcAppName
                       [-dstApp dstAppName]
                       [-overWrite trueOrfalse]
                       [migrateIdStoreMapping trueOrfalse]
                                       [mode laxOrstrict]

migrateSecurityStore(type="appPolicies", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext", srcApp="srcAppName", [dstApp="dstAppName"], [overWrite="trueOrfalse"], [migrateIdStoreMapping="trueOrfalse"], [mode="strict"])

The meanings of the arguments configFile, src, and dst are identical to the previous cases. The meaning of other five arguments is as follows:

srcApp specifies the name of the source application, that is, the application whose policies are being migrated.
dstApp specifies the name of the target application, that is, the application whose policies are being written. If unspecified, it defaults to the name of the source application.
migrateIdStoreMapping specifies whether enterprise policies should be migrated. The default value is True. To filter out enterprise policies from the migration, that is, to migrate just application policies, set it to False.
overWrite specifies whether a target policy matching a source policy should be overwritten by or merged with the source policy. Set to true to overwrite the target policy; set to false to merge matching policies. Optional. If unspecified, defaults to false.
mode specifies whether the migration should stop and signal an error upon encountering a duplicate principal or a duplicate permission in an application policy. Either do not specify or set to lax to allow the migration to continue upon encountering duplicate items, to migrate just one of the duplicated items, and to log a warning to this effect.

If the input does not follow the syntax requirements above, the command execution fails and returns an error. In particular, the input must satisfy the following requisites: (a) the file jps-config.xml is found in the passed location; (b) the file jps-config.xml includes the passed jps-contexts; and (c) the source and the destination context names are distinct.

7.3.2.1 Examples of Use

For complete examples illustrating the use of this command, see Section 6.5.2.1, "Migrating Policies Manually."

7.4 Managing the Domain Policy Store

The following sections explain how an administrator can manage policies using either Fusion Middleware Control, WLST commands, or Oracle Authorization Policy Manager. Typical operations include:

Changing the grants of an existing application role.
Revoking a permission from a principal.
Creating and deleting application roles.
Listing all application roles and members of an application role.

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

Managing Policies with Fusion Middleware Control
Managing Policies with WLST Commands
Managing Policies with Oracle Authorization Policy Manager

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.12, "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.6, "Failure to Grant or Revoke Permissions - Case Mismatch."

Important Point 3:

Strings in a policy store cannot contain any special ASCII character in the range [0, 15].

For other issues regarding the use of characters in policy stores, see Section J.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.

7.4.1 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

7.4.1.1 Managing Application Policies

This section explains the steps you follow to manage the policies of a deployed application with Fusion Middleware Control, such as, for example, to change the permission grants of an existing application role. To manage system policies, see Managing System 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.

Log in to Fusion Middleware Control and navigate to Application > Security > Application Policies, to display the Application Policies page for the selected Application. This page is partially illustrated in the following graphic:

The area Policy Store Provider is read-only and, when expanded, displays the policy store provider currently in use in the domain where the application is deployed.

Note:
If the page does not initially display policies and roles, click the blue button to display all items.
To display existing application policies matching a given principal or permission, expand the Search area, enter the data to match (a principal name or a permission name or both), and click the blue button. The results of the search are displayed in the table at the bottom of the page.

Note:
If, and only if, the selected application uses a policy stripe name different from the application name, the box Select Application Stripe to Search is displayed. In this case, check the box and select a stripe name from the pull-down list.
To create an application policy, click Create to display the Create Application Grant page. The top area Grant Details displays read-only information about the application.
1. To add permissions to the policy being created, click Add in the Permissions area to display the Add Permission dialog.
  
  Using the Search to identify permissions matching a class or resource name, determine the Permission Class and Resource Name of the permission. Optionally, use the Customize area to further qualify the permission.
  
  When finished, click OK to return to the Create Application Grant page. The permission you created is displayed in the table in the Permissions area.
2. To add users to the policy being created, click the button Add User in the Grantee area to display the dialog Add User.
  
  Using the Search, identify users names matching a string; the result of the query is displayed in the Available Users box.
  
  Using the various buttons, move the users you want to grant permissions from the Available Users box to the Selected Users box.
  
  When finished, click OK to return to the Create Application Grant page. The users you selected are displayed in the table in the Grantee area.
3. To add application roles to the policy being created, click the button Add Application Role in the Grantee area to display the dialog Add Application Role.
  
  Using the Search, identify role names matching a type or name; the result of the query is displayed in the Available Roles box.
  
  Using the various buttons, move the roles you want to grant permissions from the Available Roles box to the Selected Roles box.
  
  When finished, click OK to return to the Create Application Grant page. The roles you selected are displayed in the table in the Grantee area.
4. To add groups to the policy being created, click the button Add Group in the Grantee area to display the dialog Add Group.
  
  Using the Search, identify the group names matching a string; the result of the query is displayed in the Available Groups box.
  
  Using the various buttons, move the groups you want to add to the policy from the Available Groups box to the Selected Groups box.
  
  When finished, click OK to return to the Create Application Grant page. The groups you selected are displayed in the table in the Grantee area.
5. At any point you can remove an item from the 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.
6. 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.
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 and enter users, application roles, or groups, as appropriate, as explained in the substeps of step 3 above, and then click OK.

7.4.1.2 Managing Application Roles

This section explains the steps you follow to manage the roles of a deployed application with Fusion Middleware Control. Management operations that control the access a user or group has to resources, include creating application roles, mapping an application role to users, groups, or other application roles, and managing the members in application roles.

Log in to Fusion Middleware Control and navigate to Application > Security > Application Roles, to display the Application Roles page. This page is partially illustrated in the following graphic:

The area Policy Store Provider is read-only and, when expanded, displays the policy store provider currently in use in the domain where the application is deployed.

Note:
If the page does not initially display application roles, click the blue button to display all items.
Select the application whose roles to search; if the application stripe is the same as the application stripe, select the radio button Select Application Name to Search, and choose the application; otherwise, if the application name differs from the application stripe, select the radio button Select Application Stripe to Search, and choose the application stripe.
To display application roles matching a given name, enter the data to match in the box Role Name, and click the blue button. The results of a query are displayed in the table at the bottom of the page.

To redisplay the table of all current application policies, leave the Role Name blank and click the blue button.
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 Application Role, to display the Add Application Role dialog.
2. In this dialog, identify the available role with a name matching a string by entering the string in the box Role Name, and then clicking the blue button; the result of the query is displayed in the Available Roles box.
3. Select roles from the box Available Roles, as appropriate, and use the buttons in between the boxes to move them to the box Selected Roles.
4. When finished, click OK to return to the Create Application Role page. The selected application roles are displayed in the table Roles.
To add groups to the application role being created:
1. Click Add Group, to display the Add Group dialog.
2. In this dialog, identify the available groups with a name matching a string by entering the string the box Group Name, and then clicking the blue button; the result of the query is displayed in the Available Groups box.
3. Select groups from the box Available Groups, as appropriate, and use the buttons in between the boxes to move them to the box Selected Groups.
4. When finished, click OK to return to the Create Application Role page. The selected groups are displayed in the table Roles.
To add users to the application role being created:
1. Click Add User, to display the Add User dialog.
2. In this dialog, identify the available users with a name matching a string by entering the string in the box User Name, and then clicking the blue button; the result of the query is displayed in the Available Users box.
3. Select users from the box Available Users, as appropriate, and use the buttons in between the boxes to move them to the box Selected Users.
4. When finished, click OK to return to the Create Application Role page. The selected users are displayed in the table Users.
At any point you can remove an item from the 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.
Click OK to effect the role creation (or update) and to return to the Application Roles page. The role just created is displayed in the table at the bottom of that page.
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 the role and user tables are 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."

7.4.1.3 Managing System Policies

This section explains the steps you follow to manage system policies for a domain with Fusion Middleware Control. To manage application policies, see Managing Application Policies.

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.

Log in to Fusion Middleware Control and navigate to Domain > Security > System Policies to display the page System Policies. This page is partially illustrated in the following graphic:

The area Policy Store Provider is read-only and, when expanded, displays the policy store provider currently in use in the domain.
To display application policies matching a given type, name, or permission, expand the Search area, enter the data to match, and click the blue button. The results of a query are displayed in the table at the bottom of the page.

To redisplay the table of current application policies, select the type All and leave the name and permission boxes blank.
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:

Click Create to display the Create System Grant page.
In the area Grant Details, select type of policy to create. The valid types are Principal or Codebase. The UI differs slightly depending on the type chose. The steps below assume the selection Principal.
To add permissions to policy being created, click the button Add in the Permissions area to display the Add Permission dialog. In this dialog 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 query 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.
At any point, you can select a permission from the table and use the button Edit to change the characteristics of the permission, or the button Delete to remove from the list.
To add users to the policy being created, click the button Add User in the Grantee area to display the Add User dialog.
1. Use the Search to display user names matching a pattern. The results of the query are displayed in the box Available Users.
2. Use the buttons in between the boxes to move users from the Available Users box to the Selected Users box.
3. Click OK to return to the Create System Grant page. The users you have selected are added to the table Grantee.
To add roles to the policy being created, click the button Add Role in the Grantee area to display the Add Role dialog.
1. Use the Search to display role names matching a type or role name. The results of the query are displayed in the box Available Roles.
2. Use the buttons in between the boxes to move roles from the Available Roles box to the Selected Roles box.
3. Click OK to return to the Create System Grant page. The roles you have selected are added to the table Grantee.
Click OK to return to the System Policies page. An message at the top of the page informs you the result of the operation. If successful, the policy is added to the table at the bottom of the page.

To create a system policy based on an existing system policy:

Select a policy from the table.
Click Create Like to display the Create System Grant page. Notice that some entries in the page are filled in with data extracted from the policy selected in the previous step.
Follow the preceding procedure (to create a system policy) to modify those values and enter new ones, as appropriate.

7.4.2 Managing Policies with WLST Commands

If a domain administrator does not want to use Fusion Middleware Control to manage policies or wants to execute a frequent task automatically, the administrator can create a WLST script that invokes WLST security-related commands.

An online command is a command that, to perform, requires a connection to a running Oracle WebLogic Server. All commands below are online commands and operate on a domain policy store, regardless of whether it is file- or LDAP-based.

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

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

Important:

Before invoking a security-related WLST command in a shell, you must run the script wlst.sh, as illustrated in the following sample:

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

This ensures that the required JARs are added to the class path. Failure to run the above script in a new shell renders the WLST commands unusable.

Before running an online command, connect to the server as follows:

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

OPSS supports the following online commands to administer policies:

createAppRole
deleteAppRole
grantAppRole
revokeAppRole
listAppRoles
listAppRolesMembers
grantPermission
revokePermission
listPermissions
deleteAppPolicies
createResourceType
getResourceType
deleteResourceType
reassociateSecurityStore

All class names specified in these commands 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 domain policies pertaining to a particular application.

For important information about the authenticated and the anonymous roles and WLST commands, see Section 7.4.2.15, "Granting Policies to Anonymous and Authenticated Roles with WLST Commands."

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

7.4.2.1 createAppRole

The command createAppRole creates an application role in the domain 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

7.4.2.2 deleteAppRole

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

Removing any grants where the role is present.
Removing the role from any other role of which it is a member.
Removing any 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

7.4.2.3 grantAppRole

The command 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

7.4.2.4 revokeAppRole

The command 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

7.4.2.5 listAppRoles

The command 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

7.4.2.6 listAppRolesMembers

The command 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

7.4.2.7 grantPermission

The command grantPermission creates a permission granted to a code base 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 command 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

7.4.2.8 revokePermission

The command revokePermission removes a permission from a principal or code base 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 command 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

7.4.2.9 listPermissions

The command 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 command 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

7.4.2.10 deleteAppPolicies

The command 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 command works on just system policies.

Example of Use

deleteAppPolicies -appStripe myApp

7.4.2.11 createResourceType

The command createResourceType inserts a new <resource-type> entry in the domain 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 ;

7.4.2.12 getResourceType

The command getResourceType returns the relevant parameters of a <resource-type> entry in the domain 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

7.4.2.13 deleteResourceType

The command deleteResourceType removes a resource type with a given name from the passed application stripe. This command applies a cascading deletion by removing all resource instances of the resource type from permission sets (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

7.4.2.14 reassociateSecurityStore

The command reassociateSecurityStore migrates, within a give domain, both the policy store and the credential store to a target LDAP server repository, and it changes the default policy and credential services to the target repository. It also allows specifying that the domain policy and credential stores be shared with those in a different domain (see optional argument join below).

The function of this command is equivalent to reassociating domain stores with Fusion Middleware Control.

The only kind of server target supported is the LDAP-based Oracle Internet Directory. The source repository can be file- or LDAP-based. This command uses and modifies the domain configuration file jps-config.xml, and it is supported in only the interactive mode.

Before issuing this command, ensure that you have accomplished the requisites explained in Prerequisites to Using an LDAP-Based Policy Store.

An alternate way of performing reassociation using Fusion Middleware Control is explained in Reassociating Domain Stores with Fusion Middleware Control.

If this operation is to use a one-way SSL connection to the target store, follow the procedures explained in Setting Up a One- Way SSL Connection before invoking the command.

After reassociation, to secure access to the root node of the Oracle Internet Directory store, follow the instructions in Securing Access to Oracle Internet Directory Nodes.

Interactive Mode Syntax

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

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

domain specifies the domain name where the reassociating takes place.
admin specifies the administrator's user name on the LDAP server. The format is cn=usrName.
password 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. The only valid type is OID (Oracle Internet Directory).
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 a policy store specified in another domain. Optional. Set to true to share an existing policy store in another domain; set to false otherwise. The use of this argument allows multiple WebLogic domains to point to the same logical policy store.

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 command as follows:

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

7.4.2.15 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 commands 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

7.4.2.16 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

7.4.3 Managing Policies with Oracle Authorization Policy Manager

In a WebLogic domain that uses an Oracle Internet Directory LDAP policy store, Oracle Authorization Policy Manager allows managing and searching application policies and other security artifacts, and managing the many-to-many mapping of application roles to external roles.

For details, see the following chapters in Oracle Authorization Policy Manager Administrator's Guide:

7.5 Configuring Other Artifacts with Oracle Fusion Middleware Control

This section explains how to use Fusion Middleware Control to configure parameters used by the User and Role APIs, property and property sets, and to specify the Single Sign-On Provider, in the following sections:

Configuring the Identity Store Provider
Configuring Properties and Property Sets
Specifying a Single Sign-On Solution

Note:

The area of the page Security Provider Configuration labeled Web Services Manager Authentication Providers pertains to the configuration of Login Modules and the Keystore for Web Services Manager only and is not relevant to ADF or JavaEE applications.

In regards to the Keystore: a Keystore configuration should not be modified; to change any settings for the Keystore, first remove the existing configuration (uncheck the box Configure Keystore and then click OK), and then continue to specify a new one. Failure to proceed this way leads to errors and unexpected behavior.

For details about the login modules available, their parameters, and the keystore for those components, see chapter 9 in Oracle Fusion Middleware Security and Administrator's Guide for Oracle Web Services.

7.5.1 Configuring the Identity Store Provider

To configure the parameters used by the User and Role API that interact with the identity store, proceed as follows:

Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration; the page Security Provider Configuration appears.
Expand, if necessary, the area Identity Store Provider, and click Configure to display the page Identity Store Configuration.
Manage custom properties, as appropriate, using the buttons Add and Delete.
When finished, click OK to save your settings and to return to the Security Provider Configuration page.

7.5.2 Configuring Properties and Property Sets

A property set is collection of properties typically used to define the properties of a service instance or generic properties of the domain.

For a list of OPSS configuration properties, see Appendix F, "OPSS Configuration Properties."

The elements <property> and <properySet> in the file $DOMAIN_HOME/config/fmwconfig/jps-config.xml are used to define property and property sets. Property sets can be referenced by the element <propertySetRef>.

To define a property or a property set, proceed as follows:

Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration; the page Security Provider Configuration appears.
Expand, if necessary, the area Advanced Properties, and click Configure to display the page Advanced Properties, in which you can enter properties and property sets.
To enter a property, click Add in the Properties area to display the dialog Add New Property, and enter a property name and value. When finished, click OK. The entered property appears on the Properties table.
To enter a property set, click Add Property Set in the Property Sets area to display the dialog Add Property Set, and enter the property set name.
To enter a property in a property set, select a property set from the existing ones, then click Add Property to display the dialog Add New Property, and then enter a property name and value. The entered property is added to the list of properties in the selected property set.
Use the button Delete to remove a selected item from any table. When finished entering or editing properties and property sets, click OK.
Restart the Oracle WebLogic Server. Changes do not take effect until the server has been restarted.

The addition or deletion of property sets modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml; the changes do not take effect until the server is restarted.

The elements <property> and <propertySet> added by the previous procedure are inserted directly under the element <jpsConfig>.

7.5.3 Specifying a Single Sign-On Solution

This section explains the OPSS Single Sign-On (SSO) Framework and how to configure an SSO solution using Fusion Middleware Control, in the following sections:

The OPSS SSO Framework
Configuring an SSO Solution with Fusion Middleware Control
OAM Configuration Example

7.5.3.1 The OPSS SSO Framework

The OPSS SSO Framework provides a way to integrate applications in a domain with an SSO solution. Specifically, it provides applications a common set of APIs across SSO products, to handle login, logout and auto login.

One of these solutions, the OAM solution, is available out-of-the-box, and it includes the following features:

Dynamic authentication - Upon accessing a part of a secured artifact that requires authentication, the application triggers authentication and redirects the user to be authenticated by the appropriate solution.
Auto login - A user who has initially accessed an application anonymously registers an account with the application; upon a successful registration, the user is redirected to the authentication URL; the user can also be automatically logged in without being prompted.
Global logout - When a user logs out of one application, the logout propagates across to any other application that is enabled by the solution.

For a configuration example of an OAM solution, see OAM Configuration Example.

An SSO solution must provide a standard way for applications to login and logout users. After successful authentication, the SSO service is responsible to redirect the user to the appropriate URL.It is assumed that the domain where the solution is applied has been configured to allow the Subject to contain the anonymous user and role before login and after logout, and authenticated roles after login. It is also assumed that the SSO provider has implemented a Credential Mapping Service. In the case of the out-of-the-box OAM solution, the provider implements CredentialMapperService that produces the appropriate OAM token.

The OPSS SSO framework does not support multi-level authentication.

Integration with the desired SSO solution requires a separate installation and appropriate configuration of the solution. For details about recommended solutions, see Chapter 9, "Configuring Single Sign-On in Oracle Fusion Middleware."

7.5.3.2 Configuring an SSO Solution with Fusion Middleware Control

To specify the SSO solution used by a domain, proceed as follows:

Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration; the page Security Provider Configuration appears.
Expand, if necessary, the area Single Sign-On Provider, and click Configure to display the page Single Sign-On Provider.
Check the box Configure Single Sign-On, to allow entering data for the provider. All boxes are grayed out until this box is checked.
Select the Provider Type from the pull-down list, and enter the corresponding data for the selected provider (the list of data changes with the provider selected).
Optionally, manage the provider Custom Properties using the buttons Add, Edit, and Delete, at the bottom of the page.
When finished, click OK to save the entered data.

7.5.3.3 OAM Configuration Example

The SSO service configuration entered with the procedure described in Configuring an SSO Solution with Fusion Middleware Control is written to the file jps-config.xml. The data specified includes:

A particular SSO service
The auto-login and auto-logout URIs
The authentication level
The query parameters contained in the URLs returned by the selected SSO service
The appropriate settings for token generation

The following fragment of a jps-config.xml file illustrates the configuration of an OAM SSO provider:

<propertySets>
  <propertySet name = "props.auth.url">
    <property name = "login.url.BASIC" value = "http://host:port/oam_login.cgi?level=BASIC"/>
    <property name = "login.url.FORM" value = "http://host:port/oam_login.cgi?level=FORM"/>
    <property name = "login.url.DIGEST" value = "http://host:port/oam_login.cgi?level= DIGEST"/>
    <property name = "autologin.url" value = " http://host:port/obrar.cgi"/>
    <property name = "logout.url" value = "http://host:port/logout.cgi"/>
    <property name = "param.login.successurl"  value = "successurl"/>
    <property name = "param.login.cancelurl"   value = "cancelurl"/>
    <property name = "param.autologin.targeturl" value = "redirectto"/>
    <property name = "param.autologin.token"   value = "cookie"/>
    <property name = "param.logout.targeturl"   value = "targeturl"/>
  </propertySet>

  <propertySet name="props.auth.uri">
    <property name="login.url.BASIC" value="/${app.context}/adfauthentication?level=BASIC" /> 
    <property name="login.url.FORM" value="/${app.context}/adfauthentication?level=FORM" /> 
    <property name="login.url.DIGEST" value="/${app.context}/adfauthentication?level=DIGEST" /> 
    <property name="autologin.url" value="/obrar.cgi" /> 
    <property name="logout.url" value="/${app.context}/adfauthentication?logout=true" /> 
  </propertySet>

  <propertySet name = "props.auth.level">
    <property name = "level.anonymous" value = "0"/>
    <property name = "level.BASIC"    value = "1"/>
    <property name = "level.FORM"    value = "2"/>
    <property name = "level.DIGEST"   value = "3"/>
  </propertySet>
<propertySets>

<serviceProviders>
  <serviceProvider name = "sso.provider"
    class = "oracle.security.jps.internal.sso.SsoServiceProvider" 
    type = "SSO">
    <description>SSO service provider</description>
  </serviceProvider>
</serviceProviders>

<serviceInstances>
  <serviceInstance name = "sso" provider = "sso.provider">
    <propertySetRef ref = "props.auth.url"/>
    <propertySetRef ref = "props.auth.level"/>
    <property name = "default.auth.level" value = "2"/>
    <property name = "token.type" value = "OAMSSOToken"/>
    <property name = "token.provider.class" value = "oracle.security.jps.wls.internal.sso.WlsTokenProvider"/>
    <property name="sso.provider.class" value="oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl"/>
  </serviceInstance>
</serviceInstances>

<jpsContexts default = "default">
  <jpsContext name = "default">
    <serviceInstanceRef ref = "sso"/>
  </jpsContext>
</jpsContexts>

Regarding the configuration of an SSO provider, note the following important remarks:

Any SSO provider must define the URI for at least the FORM login with the property login.url.FORM. The value need not be a URL.
If the application supports a self-registration page URI or URL, it must be specified with the property autologin.url.
If the SSO solution supports a global logout URI or URL, it must be specified with the property logout.url. The OAM solution supports global logout.
The following properties, illustrated in the preceding example, are optional:
- param.login.successurl
- param.login.cancelurl
- param.autologin.targeturl
- param.login.token
- param.logout.targeturl
The use of the variable app.context in URI specifications, illustrated in values within the property set props.auth.uri in the preceding example, is allowed for only ADF applications when integrating with the OAM solution.
The property set props.auth.level is required.
The reference to props.auth.url is required.
The property sso.provider.class within a service instance of the SSO provider is the fully qualified name of the class implementing a specific SSO solution.

In the case of the OAM solution, the provided class name is oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl.
The property name default.auth.level within a service instance of the SSO provider must be set to 2, as illustrated in the preceding example.
The property token.type within a service instance of the SSO provider is required.

This token type identifies the token set on the HTTP request by the SSO provider upon a successful authentication; the SSO provider uses this token, after the first time, to ensure that the user does not need to be reauthenticated and that his sign-on is still valid. In the case of the OAM solution, the token type must be OAMSSOToken, as illustrated in the preceding example.
The property token.provider.class within a service instance of the SSO provider is the fully qualified name of the token class, and it is provider-specific.
If an application implements a self-registration logic and wants to auto login a user after successful self-registration, it must call the OPSS autoLogin API; in turn, to allow this call, it must grant that application a code source permission named CredentialMapping with class JpsPermission.

The following fragment of the file system-jazn-data.xml illustrates the specification of this permission to the application MyApp:
```
<grant>
  <grantee>
    <codesource>
      <url>file:${domain.home}/servers/MyApp/-</url>
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.JpsPermission</class>
      <name>CredentialMapping</name>
    </permission>
  </permissions>
</grant>
```

7.6 Configuring LDAP-Based Policy Stores

The following sections provide guidelines for setting OPSS parameters and properties, and profiling LDAP-based policy stores:

OPSS System Properties for JVM
LDAP Policy Store Property Configuration for Maximum performance
Profiling LDAP Policy Store APIs

7.6.1 OPSS System Properties for JVM

Table 7-1 lists some recommended special settings for OPSS system properties. These are typically specified in the script that starts Oracle WebLogic Server.

Table 7-1 OPSS System Properties for JVM

Property Name	Value	Description
domain.home	$DOMAIN_HOME	Required for code-based grants that depend on the value of this system property. This property must be set as a command-line parameter due to JVM bootstrapping restrictions.
jps.authz	ACC	Different from current out-of-the-box setting, which is DEBUG_ACC. Setting -Djps.auth=ACC reduces runtime and debugging overhead.
jps.policystore.hybrid.mode	false	Different from current out-of-the-box setting, which is true. Setting -Djps.policystore.hybrid.mode=false reduces runtime overhead.
jps.combiner.optimize	true	Different from current out-of-the-box setting, which is false. Setting -Djps.combiner.optimize=true improves Java2 authorization performance.
jps.combiner.optimize.lazyeval	true	Different from current out-of-the-box setting, which is false. Setting -Djps.combiner.optimize.lazyeval=true improves Java2 authorization performance.

7.6.2 LDAP Policy Store Property Configuration for Maximum performance

Table 7-2 lists the properties that are required to be present in any instance of an LDAP policy store service. The properties of an instance can be specified and modified with the script described in Section E.1, "Configuring OPSS Service Provider Instances with a WLST Script."

Table 7-2 LDAP Policy Store Service Instance Properties

Name	Default	Recommended	Description
oracle.security.jps.policystore.rolemember.cache.type	STATIC	STATIC	Role Member Cache Type.
oracle.security.jps.policystore.rolemember.cache.strategy	FIFO	FIFO	Role Member Cache Strategy.
oracle.security.jps.policystore.rolemember.cache.size	1000	5000	Role Member Cache Size.
oracle.security.jps.policystore.policy.lazy.load.enable	true	true	Enable Policy Lazy Load.
oracle.security.jps.policystore.policy.cache.strategy	PERMISSION_FIFO	PERMISSION_FIFO	Permission Cache Strategy.
oracle.security.jps.policystore.policy.cache.size	1000	1000	Permission Cache Size.
oracle.security.jps.policystore.refresh.enable	true	true	Enables policy store refresh from LDAP server.
oracle.security.jps.policystore.refresh.purge.timeout	43200000	43200000	Forced policy store refresh time in milliseconds.
oracle.security.jps.ldap.policystore.refresh.interval	600000	600000	Policy store refresh polling time in milliseconds.

7.6.3 Profiling LDAP Policy Store APIs

Table 7-3 lists loggers to profile the timing of several LDAP policy store runtime APIs. These profilers are specified with Fusion Middleware Control pages, as explained in Section J.1.1.4, "Using Fusion Middleware Control Logging Support."

Table 7-3 OPSS Profilers

Category	Logger Name	Log Level	Profiles
refresh	oracle.security.jps.policystore.refresh.full.profiler	FINE	The time taken by refresh for policies.
refresh	oracle.security.jps.policystore.refresh.partial.profiler	FINE	The time taken by fine-grained various activities during policy refresh.
policy management APIs	oracle.security.jps.policystore.management.profiler	FINE	The time taken by selective policy management APIs (getAllAppRoleEntries, searchAppRoles).
policy runtime APIs	oracle.security.jps.policystore.runtime.profiler	FINE	The time taken by on-demand loading (during cache miss) of direct roles and the granted permissions for a given user.
OPSS Filter and EJB Interceptor	oracle.security.jps.policystore.runtime.profiler	FINE	The time taken to compute the application roles for the give subject by the OPSS filter and the OPSS EJB interceptor.