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

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

Go to previous page
Previous
Go to next page
Next
View PDF

8 Configuring the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, and keys. For an introduction to policies and credentials, see the following sections:

This chapter explains the features of the OPSS security store common to policies and credentials, and it is divided into the following sections:

For 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 WebLogic domain is setup to use policies based on the OPSS security store, JACC policies and the Java Security Manager become unavailable on all managed servers in that domain.

Important:

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

8.1 Introduction to the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, and keys. This centralization facilitates the administration and maintenance of policy, credential, and key data.

The OPSS security store can be file-, LDAP-, or DB-based depending on the choice of repository type, and it can be reassociated (that is, the repository type can be changed) from file-based to LDAP- or DB-based; from DB-based to LDAP- or DB-based; and from LDAP-based to LDAP- or DB-based. No other reassociation is supported. For details about the tools and procedures available to reassociate the OPSS security store, see sections Reassociating with Fusion Middleware Control and Reassociating with the Script reassociateSecurityStore. Out-of-the-box, the OPSS security store is file-based.

The security data relevant to a JavaEE application is typically packaged with the application and it can be migrated at deploy time to the OPSS security store. For details about the tools and procedures available to migrate to the OPSS security store, see sections Migrating with Fusion Middleware Control and Migrating with the Script migrateSecurityStore.

8.2 Using an LDAP-Based OPSS Security Store

An LDAP-based policy store is typically used in production environments. The only LDAP server supported in this release is the Oracle Internet Directory (release 10.1.4.3 or later).

Note:

Depending on the version, the following patches to Oracle Internet Directory are required:
  • Patch to fix bug 9093298 in Oracle Internet Directory 10.1.4.

  • Patch to fix bug 8736355 in Oracle Internet Directory 11.x.

To apply a patch, proceed as follows:

  1. Visit Oracle Automated Release Updates.

  2. Click the Patches tab.

  3. Enter the bug number in the Request Number box, and click Search.

  4. Apply the patch.

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

Important:

OPSS does not support enabling referencial integrity on Oracle Internet Directory servers. The server will not work as expected if referencial integrity is enabled.

To disable a server's referencial integrity, use Oracle Enterprise Manager Fusion Middleware Control as follows:

  1. Select Administration, then Shared Properties from the Oracle Internet Directory menu, and then select General.

  2. Select Disabled from the Enable referencial Integrity list.

For a list of properties that can be specified in a service instance, see Appendix F, "Properties Common to All LDAP-Based Instances."

The information in this section is divided into the following topics:

8.2.1 Multiple-Node Server Environments

In domains where several server instances are distributed across multiple machines, it is highly recommended that the OPSS security store be LDAP- or DB-based.

Typically, applications do not change policy, credential, or key 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, it is recommended that any such changes be performed in the domain administration server (and not in 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. For details about properties you can set on policies and credentials, see sections Appendix F, "Policy Store Properties," and Appendix F, "Credential Store Properties."

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

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

8.2.2 Prerequisites to Using an LDAP-Based Security Store

The only supported LDAP-based OPSS security store is Oracle Internet Directory. In order to ensure the proper access to the Oracle Internet Directory, you must set a node in the server directory as explained below.

Fusion Middleware Control automatically provides bootstrap credentials in the file cwallet.sso when that tool is used to reassociate to an LDAP-based repository. To specify these required credentials manually, see section Section 21.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:

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

  2. 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 -v -f  jpstestnode.ldif
    
  3. 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 -s base 
    -b "cn=jpsroot" objectclass="orclContainer"
    
  4. 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 OPSS Security Store.

8.3 Using a DB-Based OPSS Security Store

A DB-based security store is typically used in production environments. The only supported DB-based security store is Oracle RDBMS (releases 10.2.0.4 or later; releases 11.1.0.7 or later; and releases 11.2.0.1 or later).

To use a DB-based OPSS security store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or OPSS scripts.

For a list of properties that can be configured, see Appendix F, "OPSS Configuration Properties."

This section contains the following topics:

8.3.1 Prerequisites to Using a DB-Based Security Store

To use a database repository for the OPSS security store, one must first use Oracle Fusion Middleware Repository Creation Utility (RCU) to create the required schema and to seed some initial data. This setup is also required before reassociating the OPSS security store to a DB-based security store.

For details about RCU, see chapters Repository Creation Utility Overview and Running Repository Creation Utility in Oracle Fusion Middleware Repository Creation Utility User's Guide.

The creation the schema and seeding of initial data are explained in the following sections:

8.3.1.1 Creating the OPSS Schema in an Oracle Database

To create the OPSS schema in an Oracle database with RCU, proceed as follows:

  1. Start RCU to display the RCU Welcome page; in this page, click Next to display the Create Repository page.

  2. In that page, select the radio button Create; then click Next to display the Database Connections Details page.

  3. In that page, enter the appropriate connectivity information: Database Type, Host Name, Port, Service Name, Username, Password, and Role.

    Then click Next to have RCU check the entered data and perform pre-creation operations; once this check is successfully completed, RCU displays the Select Components dialog.

  4. In that dialog, choose to use an existing schema prefix or create a new prefix, and pick the OPSS component to install the schema.

    When finished selecting components, click Next to display the Schema Passwords dialog where you supply passwords, and then click Next to display the Map Tablespaces dialog which shows the tablespace summary. Use one default tablespace and one temporary tablespace; the default tablespace names are PREFIX_IAS_OPSS and PREFIX_IAS_TEMP, respectively.

    To create a non-default tablespace or datafile, click the button Manage Tablespaces to display the Manage Tablespaces dialog, where you can specify the information to create them. When finished, click OK. If the specified tablespaces are not yet in the database, RCU creates them and informs about this in the Creating Tablespaces; click OK to display the Summary dialog, which displays the summary of data you have entered, and then click Create to effect the creation of the additional tablespace(s) or datafile(s).

  5. When the creation is completed, RCU displays the Completion Summary, which shows the database details.

  6. Invoke the SQLPlus command illustrated below to verify that the database schema has been properly created:

    SQL> desc jps_dn;
    

8.3.1.2 Dropping the OPSS Schema in an Oracle Database

Dropping the OPSS schema is required only if one no longer wishes to use that DB for storing OPSS security policies.

After the OPSS schema has been successfully created, use RCU to drop the OPSS schema as follows:

  1. Start RCU to display the RCU Welcome page; in this page, click Next to display the Drop Repository page.

  2. In that page, select the radio button Drop; then click Next to display the Database Connections Details page.

  3. In that page, enter the appropriate connectivity information: Database Type, Host Name, Port, Service Name, Username, Password, and Role. Then click Next to display the Select Components dialog.

  4. In that dialog, select the prefix and, in the Component hierarchy, check AS Common Schemas and Oracle Platform Security Services; then click Next to display the Summary page.

  5. In that page, verify that the details gathered are correct, and click Drop to trigger the dropping; when the operation is successfully completed, RCU displays the Completion Summary page detailing the schema dropped.

8.3.1.3 Creating a Data Source Instance

To create a data source instance, see section Creating a JDBC Data Source in Oracle Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server. The JNDI name of the JDBC data source entered in the procedure in that section is used in the configuration of a DB-based store.

To set up a data source on WebSphere Application Server, see Oracle Fusion Middleware Third-Party Application Server Guide.

Note:

11.2 Oracle JDBC driver deprecated the following time zones: Etc/UCT, UCT, Etc/UTC, Etc/Universal, Etc/Zulu, and Universal. When setting a time zone for your Oracle JDBC driver, make sure that it is a non-deprecated time zone.

8.3.2 Maintaining a DB-Based Security Store

This section describes a few tasks that an administrator can follow to maintain a DB-based security store.

A DB-based security store maintains a change log that should be periodically purged. To purge it, an administrator can use the provided SQL script opss_purge_changelog.sql, which will purge change logs older than 24 hours, or connect to the database and run SQL delete (with the appropriate arguments) as illustrated in the following lines:

SQL>delete from jps_changelog where createdate < (select(max(createdate) - 1) from jps_changelog);
SQL>Commit;

If the OPSS management API performs slowly while accessing the DB-based security store, run the DBMS_STATS package to gather statistics about the physical storage of a DB table, index, of cluster. These statistics are stored in the data dictionary and can be used to optimize the execution plan for SQL statements accessing analyzed objects.

Here is a sample illustrating the use of the DBMS_STATS package to gather information about the DB schema:

EXEC DBMS_STATS.GATHER_SCHEMA_STATS('OPSS_DEV', DBMS_STATS.AUTO_SAMPLE_SIZE);

where OPSS_DEV denotes the name of the DB schema created during the RCU setup (see section Creating the OPSS Schema in an Oracle Database). For details about the DBMS_STATS package, see the Oracle Database Administrator's Guide.

8.3.3 Setting Up an SSL Connection to the DB

This section describes how to establish a one- or two-way SSL connection to a DB-Based OPSS security store. This set up is optional and the procedures involved in it are explained in the following sections:

For additional and detailed information about SSL-related topics see the following documents:

8.3.3.1 Configuring SSL on an Oracle DB Server

To configure SSL on an Oracle DB server, start Oracle Wallet Manager on the host where the DB server is running and using this tool proceed as follows:

  1. Create a wallet.

  2. Obtain a certificate from a trusted Certificate Authority (CA) and import it into the wallet created.

  3. Create a certificate request for the DB server.

  4. Send the certificate request to the CA and obtain a signed certificate from the CA.

  5. Import the signed certificate into the wallet; this certificate is the DB server's certificate.

  6. Check the box Auto Login under the menu Wallet to ensure that the DB server picks up the wallet.

  7. Save the wallet.

On the host where the DB server is running, start Oracle Net Manager and using this tool proceed as follows:

  1. Navigate to Oracle Net Configuration > Local > Profile, then select Oracle Advanced Security, and then click the tab SSL.

  2. In that tab, set Wallet Directory to the wallet saved in step 7 above, and check Configure SSL for Server. For a two-way SSL, check the box Require Client Authentication.

  3. Set the listener as follows:

    1. Navigate to Oracle Net Configuration > Local > Listeners > LISTENER.

    2. Add an address (the recommended port number is 2484).

    3. Set its protocol to TCP/IP with SSL.

  4. Optionally, to create a TNS service to connect the DB with SSL on the host, proceed as follows:

    1. Navigate to Oracle Net Configuration > Local > Service Naming.

    2. Create a new service.

    3. Set its protocol to TCP/IP with SSL.

    4. Set its port number to the port number entered for the listener.

  5. Save the network configuration, and restart the DB listener. At this point, the DB server should support SSL on the specified port.

8.3.3.1.1 Configuration Samples

The following snippets illustrate portions of the files sqlnet.ora, listener.ora, and tnsnames.ora (all located in $ORACLE_HOME/network/admin) after the above procedures are completed:

sqlnet.ora
        QLNET.AUTHENTICATION_SERVICES= (BEQ, TCPS)
        SSL_CLIENT_AUTHENTICATION = FALSE
        WALLET_LOCATION =
          (SOURCE =
            (METHOD = FILE)
            (METHOD_DATA =
              (DIRECTORY = /myHome/owm/wallets/myWallets)
            )
          )
 
listener.ora
        SSL_CLIENT_AUTHENTICATION = FALSE
        WALLET_LOCATION =
          (SOURCE =
            (METHOD = FILE)
            (METHOD_DATA =
              (DIRECTORY = /myHome/owm/wallets/myWallets)
            )
          )
 
        LISTENER =
          (DESCRIPTION_LIST =
            (DESCRIPTION =
              (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1521))
            )
            (DESCRIPTION =
              (ADDRESS = (PROTOCOL = TCP)(HOST = myHost.com)(PORT = 1521))
            )
            (DESCRIPTION =
              (ADDRESS = (PROTOCOL = TCPS)(HOST = myHost.com)(PORT = 2484))
            )
          )
 
tnsnames.ora
        ORCLSSL =
          (DESCRIPTION =
            (ADDRESS_LIST =
              (ADDRESS = (PROTOCOL = TCPS)(HOST = myHost.com)(PORT = 2484))
            )
            (CONNECT_DATA =
              (SERVICE_NAME = myService.com)
            )
          )

8.3.3.2 Configuring SSL on a Client

This section explains how to connect a client to a DB server over SSL in the following sections:

8.3.3.2.1 Connecting to a DB Server with sqlplus or JDBC OCI Driver

This task involves specifying a trusted certificate (for one-way SSL) and a client certificate (for two-way SSL).

On the host where the client is running, start Oracle Wallet Manager and using this tool proceed as follows:

  1. Create a wallet and import the DB server trusted CA certificate (created in the first procedure in section Configuring SSL on an Oracle DB Server).

  2. To establish two-way SSL:

    1. Create a certificate request.

    2. Sign the certificate with the CA certificate.

    3. Import the certificate into wallet. This certificate is used as the client certificate when connecting to DB server over a two-way SSL.

  3. Check the check box Auto Login under the menu Wallet.

  4. Save the wallet.

If connecting to the server with sqlplus, use Oracle Net Manager to create a TNS service by navigating to Oracle Net Configuration > Configure SSL for Client > Service Naming.

Important:

If for this TNS service you set Match server X.509 name to Yes, then the value of SSL_SERVER_CERT_DN must be the same as the value of DN set in the DB server certificate, as illustrated below (where CN=dbserver,OU=OPSS,O=Oracle,ST=Beijing,C=CN is the DB server certificate DN):
(SECURITY= 
     (SSL_SERVER_CERT_DN="CN=dbserver,OU=OPSS,O=Oracle,ST=Beijing,C=CN")
)
8.3.3.2.2 Connecting to a DB Server with JDBC Thin Driver

In this scenario, proceed as follows:

  1. Set your JDBC URL with following SSL-specific settings:

    • PROTOCOL=TCPS.

    • SECURITY with correct SSL SERVER_CERT_CN value.

    The following snippet illustrates this setting:

    jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=myServer.us.oracle.com)(PORT=2484)))(CONNECT_DATA=(SERVICE_NAME=orcl.us.oracle.com))(SECURITY=(SSL_SERVER_CERT_DN="CN=dbserver,OU=OPSS,O=Oracle,ST=Beijing,C=CN")))
    
  2. Set the following system properties with the appropriate values:

    oracle.net.ssl_server_dn_match
    javax.net.ssl.trustStore
    javax.net.ssl.trustStoreType
    javax.net.ssl.trustStorePassword
    javax.net.ssl.keystore
    javax.net.ssl.keyStoreType
    javax.net.ssl.keyStorePassword
    

    For a J2SE application, set the above properties using the -D option when starting a JVM.

  3. For a Data Source on the Oracle WebLogic Server, use the WebLogic Administration console to specify the above properties and values in the tab Configuration > Connection Pool of the Data Source. For details, see Oracle Fusion Middleware Administrator's Guide.

  4. For a Data Source on the WebSphere Application Server, use the Administration Console as follows:

    1. Navigate to Data Sources > YourDataSourceName > Custom Properties.

    2. Create the new custom property connectionProperties with a value as illustrated in the following line:

      oracle.net.ssl_server_dn_match=true;javax.net.ssl.trustStore=/scratch/weiniu/work/certs/qatestca.jks;javax.net.ssl.trustStoreType=JKS;javax.net.ssl.trustStorePassword=welcome1;javax.net.ssl.keyStore=/scratch/weiniu/work/certs/jksuser1.jks;javax.net.ssl.keyStoreType=JKS;javax.net.ssl.keyStorePassword=welcome1;oracle.net.ssl_version=3.0
      

      Note that the values are separated by a semicolon, and the setting oracle.net.ssl_version=3.0 is required.

8.4 Configuring the OPSS Security Store

For examples of store configurations for JavaSE applications, see Section 24.1, "Configuring Policy and Credential Stores in JavaSE Applications."

For examples of store configurations for JavaEE applications, see Example 1and Example 4.

For details about configuring other artifacts, see Configuring the Identity Provider, Property Sets, and SSO.

8.5 Reassociating the OPSS Security Store

Reassociating the OPSS security store consists in relocating the policy, credential, and key stores from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The only type of LDAP target supported is Oracle Internet Directory; the only type of DB target supported is DB_ORACLE.

Reassociation changes the repository preserving the integrity of the data stored. For each security artifact, reassociation searches the target store and, if it finds a match for it, it updates the matching artifact; otherwise, creates a new artifact.

Reassociation is typically performed, for example, when setting a domain to use an LDAP- or DB-based OPSS store instead of the out-of-the-box file-based store. This operation can take place at any time after the OPSS store has been configured and instantiated, and it is carried out using either Fusion Middleware Control or reassociateSecurityStore as explained in the following sections:

8.5.1 Reassociating with Fusion Middleware Control

Reassociation migrates the OPSS policy store (policies, credentials, and keys) from one repository to another and reconfigures the appropriate security store providers. This section explains how to perform reassociation with Fusion Middleware Control pages.

For information about other uses of the Security Provider Configuration page, see Configuring the Identity Provider, Property Sets, and SSO.

Important Points

To reassociate the OPSS security store with Fusion Middleware Control, proceed as follows:

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration (if connected to Oracle WebLogic Server) or to Cell > Security > Security Provider Configuration (if connected to WebSphere Application Server), to display the Security Provider Configuration page, partially illustrated in the following graphic:

    Surrounding text describes emsecprovconf.gif.

    The table in the area Security Stores shows the characteristics of the current provider configured in the domain.

  2. Click the button Change Association to display the Set Security Provider page, and choose the Store Type from the pull-down list. The text displayed on this page depends on the store type selected. The following graphic partially illustrates this page when Oracle Internet Directory is selected.

    Surrounding text describes emsetsecprvdr.gif.
  3. If you have selected Database, enter the name of the data source in the Datasource Name box. This should be the name of the JDBC data source entered when the data source was created; see Creating a Data Source Instance for details. If needed, click Select to obtain a list of configured data source names.

  4. If you have selected Oracle Internet Directory, 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 Oracle Internet Directory 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 setup 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 L.9, "Failure to Establish an Anonymous SSL Connection."

  5. In the Root Node Details area, enter the root DN in the box 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 L.2, "Reassociation Failure."

  6. Optionally, in the Policy Store Properties and Credential Store Properties areas, 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>
    
  7. 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 Security Stores area is modified to reflect the provider you have specified.

  8. Restart the application server. Changes do not take effect until it 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.

8.5.1.1 Setting Up a One- Way SSL Connection

This section describes how to set up a one-way SSL channel between Oracle WebLogic server or a J2SE application and the LDAP Oracle Internet Directory target of a reassociation. This set up is optional, but, if required, it should be in place before reassociating the OPSS security store.

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.

Before You Begin

Before configuring SSL, note that:

  • The following procedures are required if the type of SSL being established is server-auth, and they are not required in any other case (no-auth or client-auth).

  • If the flags specified in the procedures below are used in a multi-application environment, then the trust store must be shared by all those applications.

Setting Up the WebLogic Server in Case of a J2EE Application

The difference in the following procedures is because the identity store service and the policy store service use different socket factories.

To establish a one-way SSL connection between the server and the identity store, proceed as follows (if applicable, the trust CA is assumed exported):

  1. 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
    
  2. Modify the script (typically startWebLogic.sh) that starts the server to include a line like the following, and then restart the server:

    -Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>
    

To establish a one-way SSL connection between the server and the policy store, proceed as follows (if applicable, the trust CA is assumed exported):

  1. Use the utility keytool to import trust CA to the trust key store, as illustrated in the following invocation:

    >keytool -import -v -trustcacerts -alias trust -file serverTrust.cert -keystore myKeys.jks -storepass keyStorePassword
    
  2. Modify the script (typically startWebLogic.sh) that starts the server to include a line like the following, and then restart the server:

    -Dweblogic.security.SSL.trustedCAKeyStore=<absolute path name to file myKeys.jks>
    
  3. If the OID server uses a wild card in the SSL certificate, then add the following line to the script that starts the WebLogic server:

    -Dweblogic.security.SSL.ignoreHostnameVerification=true
    

Setting Up the WebLogic Server in Case of a J2SE Application

The setting up in the case of J2SE applications is the same for both the identity and the policy store services.

  1. 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
    
  2. Modify the script that starts the JMV to include a line like the following:

    -Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>
    

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

  1. 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).

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

8.5.2 Reassociating with the Script reassociateSecurityStore

The OPSS store can be reassociated with the OPSS script reassociateSecurityStore. For details, see Section 9.3.29, "reassociateSecurityStore."

8.6 Migrating the OPSS Security Store

A domain includes one and only one policy store. Applications can specify their own policies, but these are stored as policies in the policy store when the application is deployed to a server. All applications deployed in a domain use a common policy store, the policy store. The 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>.

Migrating the OPSS security store consists in relocating the policy, credential, and key stores from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The OPSS binaries and the target policy store must have compatible versions; for details, see Section L.20, "Incompatible Versions of Binaries and Policy Store."

During application development, an application specifies its own policies, and these can be migrated to the OPSS security 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 policy store is performed by an administrator.

These topics are explained in the following sections:

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.

8.6.1 Migrating with Fusion Middleware Control

Application policies are specified in the application file jazn-data.xml and can be migrated to the 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 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."

8.6.2 Migrating with the Script migrateSecurityStore

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

This script 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 script 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 OPSS scripts and their syntax, see section Overview of WLST Command Categories, in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For platform-specific requirements to run an OPSS script, see Important Note.

To migrate all policies (system and application-specific, for all applications) on WebLogic 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 script is run. Typically, this configuration file is created just to be used with the script 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.

  • 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 script determines the locations of the source and the target repositories involved in the migration.

To migrate just system policies on WebLogic, 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 on WebLogic, 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 script 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.

8.6.2.1 Examples of Use

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

8.7 Configuring the Identity Provider, Property Sets, and SSO

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:

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.

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.

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

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration, or to Cell > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. Expand, if necessary, the area Identity Store Provider, and click Configure to display the page Identity Store Configuration.

  3. Manage custom properties, as appropriate, using the buttons Add and Delete.

  4. When finished, click OK to save your settings and to return to the Security Provider Configuration page.

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

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration, or to Cell > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. Expand, if necessary, the area Advanced Properties, and click Configure to display the Advanced Properties page, in which you can enter properties and property sets.

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

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

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

  6. Use the button Delete to remove a selected item from any table. When finished entering or editing properties and property sets, click OK.

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

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

8.7.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 Part IV, "Single Sign-On Configuration".

8.7.3.2 Configuring an SSO Solution with Fusion Middleware Control

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

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Security Provider Configuration or Cell > Security > Security Provider Configuration to display the Security Provider Configuration page.

  2. In that page, check the box Configure Single Sign-On, to allow entering data for the provider. All boxes are grayed out until this box is checked.

  3. Select the Provider Type from the pull-down list, and enter the corresponding data for the selected provider (the data required changes with the type selected).

  4. Select the Authentication Level from the pull-down list.

  5. Optionally, manage the provider Custom Properties using the buttons Add, Edit, and Delete, at the bottom of the page.

  6. When finished, click OK to save the entered data.

8.7.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:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}
         </url>
        </codesource>
      </grantee>
      <permissions>
        <permission>
          <class>oracle.security.jps.JpsPermission</class>
          <name>CredentialMapping</name>
        </permission>
      </permissions>
    </grant>
    

    Note the use of system variables in the URL specification. For details, see Example in <url>.

8.8 Cataloging Oracle Internet Directory Attributes

An Oracle Internet Directory attribute used in a search filter must be indexed and cataloged. Indexing and cataloging are optional operations, in general, but required for OPSS-related attributes.

In a production environment, it is recommended that attribute indexing and cataloging be performed after the reassociation of the 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:

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:

For a note related to the need to catalog an attribute, see Section L.18, "Search Failure when Matching Attribute in Policy Store."