8 Security

This chapter describes Oracle Identity Federation security topics, including:

• Configuring SSL for Oracle Identity Federation

• Managing Signing and Encryption Wallets

• Setting up JCE Policy Files for Oracle WebLogic Server

8.1 Configuring SSL for Oracle Identity Federation

Oracle Identity Federation only supports configuring one password for signing and encryption keystores, and uses that password to open both the keystore and the private key. This means that if a keystore is configured with different store password and key password, an error will occur when Oracle Identity Federation tries to access the private key.

To avoid this error, ensure that the private key password for the configured key alias is the same as the keystore password.

Note: In Oracle Identity Federation 11g Release 1 (11.1.1), if you change the key password to match the keystore password, you must remove the old keystore/wallet from the configuration.

Note: Keystores, trusted certificates and certificates for Oracle Identity Federation are managed the same way as they are for any other Oracle Fusion Middleware component. For details, see the Oracle Fusion Middleware Administrator's Guide.

This section contains these topics:

• Configuring Oracle Identity Federation as an SSL Server

• Configuring Oracle Identity Federation as an SSL Client

8.1.1 Configuring Oracle Identity Federation as an SSL Server

This section explains how to configure the SSL port for Oracle WebLogic Server, and how to configure Oracle Identity Federation to use SSL.

8.1.1.1 Setting up SSL on Oracle WebLogic Server

Take these steps to configure the SSL port and keystore for the Oracle WebLogic Server for which you are setting up SSL:

1. Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.

2. Select the server for which you want to set up SSL.

3. Check SSL Listen Port Enabled and enter an SSL listening port number (for example. 443).

   We will subsequently refer to this port as $SSL_PORT.

4. Click Save.

5. Go to the Keystores tab, and click Lock & Edit.

6. In Keystores, select an option that includes Custom Identity.

7. In the Identity section, fill in properties as follows:

   • Custom Identity Keystore: location of keystore containing the SSL private key and certificate

   • Custom Identity Keystore type: jks

   • Custom Identity Keystore Passphrase: storepassword

8. Click Save.

9. Go to the SSL tab.

10. In the Identity section, fill in properties as follows:

    • Private Key Alias: keyalias

    • Private Key Passphrase: keypassword

11. Click Save, then click Activate Changes.

12. Restart the server.

13. To verify that SSL was set up correctly, go to https://$HOSTNAME:$SSL_PORT; a certificate should be presented. View the certificate; the subject should match the cn entered when creating the certificate.

Notes: The CN of the SSL server certificate must be the fully qualified hostname, for example eaevma1302.de.mycorp.com, not eaevma1302. For complete information on how to set up SSL on Oracle Weblogic Server, refer to Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server.

If you wish to configure Oracle WebLogic Server to require a client SSL certificate, take the following steps:

1. Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.

2. Select the server for which you want to set up SSL.

3. Go to the SSL tab, then Advanced.

4. For the property "Two Way Client Cert Behavior", select "Client Certs Requested and Enforced".

5. Click Save.

6. Go to the Keystores tab.

7. In Keystores, select an option that has the type of Trust Keystore type you wish to configure, and populate the fields in the Trust section.

8. Click Save, and click Activate Changes.

9. Restart the server.

You will need to import the CA that issued the client certificate into the Trust Keystore you specified in the Oracle WebLogic Configuration. If it is a Java Keystore, you can use the following command:

keytool -import -alias aliasfortrustedca -trustcacerts -file trustedcafile.pem -keystore keystorelocation -storepass truststorepassword

8.1.1.2 Configuring Oracle Identity Federation

Once you have enabled an SSL listening port and uploaded the server and trusted certificates to the respective keystores, you will need to configure Oracle Identity Federation to use SSL.

Follow these steps:

1. Log in to Fusion Middleware Control and locate the Oracle Identity Federation instance.

2. Navigate to Server Properties.

3. Update the port (and SOAP port, if necessary) to reflect the SSL port configured in the Oracle Weblogic Server administration console.

4. Check the SSL Enabled checkbox.

5. To force the use of SSL if a request is received at a non-SSL port, check the Force SSL box. Leave unchecked otherwise.

6. To force client authentication, check the Require Client Certificate box. Leave unchecked otherwise.

7. Click Apply.

You must re-generate and re-distribute metadata to peer providers after enabling SSL.

Notes: Changing the port (and SOAP port) modifies the server's metadata to reflect the correct service URLs. The metadata at the peer providers' sites must be updated with the new version.

8.1.2 Configuring Oracle Identity Federation as an SSL Client

There are two ways to configure Oracle Identity Federation as an SSL client to connect to remote SSL servers:

• Set up Oracle Identity Federation to use the Oracle WebLogic Server keystores as its identity and trust repositories. This approach is described in Section 8.1.2.1, "Configuring Oracle WebLogic Server" and Section 8.1.2.2, "Configuring Keystore Passwords in Oracle Identity Federation".

• Set up Oracle Identity Federation to use its own identity and trust keystores. This approach is described in Section 8.1.2.3, "Alternative Way to Configure Oracle Identity Federation as SSL Client".

Topics in this section include:

• Configuring Oracle WebLogic Server

• Configuring Keystore Passwords in Oracle Identity Federation

• Alternative Way to Configure Oracle Identity Federation as SSL Client

• Connecting to an LDAP Server over SSL

• Ensuring that Fusion Middleware Control can Manage an Oracle Identity Federation Target

8.1.2.1 Configuring Oracle WebLogic Server

Some SSL servers might require authentication of the client performed during the SSL handshake. This operation is typically done by having the SSL client present an SSL Client certificate to the SSL server.

This section describes how to configure Oracle WebLogic Server and Oracle Identity Federation to present a Client SSL certificate when it is requested by an SSL server. This requires:

• setting up trust for the CA that issued the SSL server certificates

• obtaining a certificate for the Oracle Identity Federation SSL client.

Take these steps to achieve this:

1. Log in to the Oracle WebLogic Server administration console and navigate to Environment, then Servers.

2. Select the server for which you want to set up SSL.

3. Go to the Keystores tab, and click Lock & Edit.

4. In Keystores, select an option that includes Custom Identity and the Trust Keystore type you wish to configure.

5. In the Identity section, fill in properties as follows:

   • Custom Identity Keystore: location of keystore with SSL private key and certificate

   • Custom Identity Keystore type: identity keystore type

   • Custom Identity Keystore Passphrase: storepassword

6. In the Trust section, fill in the properties with the Trust Keystore information.

7. Click Save, then click Activate Changes.

8. Restart the server.

8.1.2.2 Configuring Keystore Passwords in Oracle Identity Federation

If Oracle Identity Federation needs to connect to a remote provider and provide an SSL client certificate, you must configure the identity and trust keystore passwords in Oracle Identity Federation setup, not in Oracle WebLogic Server. Follow these steps:

1. Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

2. Navigate to Administration, then Server Properties.

3. In the Outbound Connections section under SSL Settings, enter the values of these two properties:

   • WebLogic Server Identity Keystore Password - the password of the identity keystore you entered in the Oracle WebLogic Server configuration.

   • WebLogic Server Trust Keystore Password - the password of the trust keystore you entered in the Oracle WebLogic Server configuration. If this property is left empty, the trust keystore will be opened without a password.

8.1.2.3 Alternative Way to Configure Oracle Identity Federation as SSL Client

If you do not wish to enter identity and trust keystore information in the Oracle WebLogic Server configuration, there is an alternate way to configure Oracle Identity Federation as an SSL Client when connecting to remote SSL servers.

With this approach, you will need to use the Oracle Identity Federation WLST commands or MBeans to set certain configuration properties. You will also need to enter the keystore passwords in the credential store.

8.1.2.3.1 Setting properties in Oracle Identity Federation configuration

You will need to set these five "serverconfig" properties to the following values:

• usewlssslconfig - false

• clientsslkeystoreloc - the path and filename of the identity keystore. The path can be absolute or relative to the domain home.

• clientsslkeystoretype – the identity keystore type. If no type is specified, the type is assumed to be JKS.

• clientssltruststoreloc – the path and filename of the trust keystore. The path can be absolute or relative to the domain home.

• clientssltruststoretype – the trust keystore type. If no type is specified, the type is assumed to be JKS.

Example: Using the WLST commands

setConfigProperty('serverconfig', 'usewlssslconfig', 'false', 'BOOLEAN')
setConfigProperty('serverconfig', 'clientsslkeystoreloc',    '/usr/local/ssl/keystore', 'STRING')
setConfigProperty('serverconfig', 'clientsslkeystoretype', 'JKS', 'STRING')
setConfigProperty('serverconfig', 'clientssltruststoreloc',    '/usr/local/ssl/truststore', 'STRING')
setConfigProperty('serverconfig', 'clientssltruststoretype', 'JKS', 'STRING')

See Chapter 9, "Oracle Identity Federation Command-Line Tools" for details about WLST command usage.

Example: Using the MBeans

In the ConfigMXBean with name "serverconfig", invoke the "putProperty" operation five times with the following arguments:

Property Name	Property Value	Property Type
usewlssslconfig	false	BOOLEAN
clientsslkeystoreloc	/usr/local/ssl/keystore	STRING
clientsslkeystoretype	JKS	STRING
clientssltruststoreloc	/usr/local/ssl/keystore	STRING
clientssltruststoretype	JKS	STRING

See Appendix A, "Oracle Identity Federation MBeans" for details.

8.1.2.3.2 Entering keystore passwords in the credential store

You will need to store the identity and trust keystore passwords in the credential store. The keys for these passwords in the credential store are:

• clientsslkeystorepwd – the password of the Identity Keystore

• clientssltruststorepwd – the password of the Trust Keystore

Following is an example of how to use WLST commands to create and update these passwords in the credential store. This example assumes that Oracle Identity Federation is deployed with application name "OIF"; the password of both the Identity and Trust keystore is denoted as "mypassword".

Create the keystore credentials:

createCred(map="OIF", key="clientsslkeystorepwd",  
user="UniqueUserNameCredential", password="mypassword", desc="identity keystore pwd")
 
createCred(map="OIF", key="clientssltruststorepwd",  
user="UniqueUserNameCredential", password="mypassword", desc="trust keystore pwd")

Update the keystore credentials:

updateCred(map="OIF", key="clientsslkeystorepwd",  
user="UniqueUserNameCredential", password="mypassword", desc="identity keystore pwd")
 
updateCred(map="OIF", key="clientssltruststorepwd",  
user="UniqueUserNameCredential", password="mypassword", desc="trust keystore pwd")

See Section 4.5, "Managing Credentials for Oracle Identity Federation" for details.

8.1.2.4 Connecting to an LDAP Server over SSL

When Oracle Identity Federation needs to connect to an LDAP server using SSL, you first need to add the LDAP's CA certificate to the trust keystore in the Oracle WebLogic Server Administration Console; this information is provided on the Server/Keystores configuration screen for the managed server where Oracle Identity Federation is running.

You must also enter the trust keystore password in Oracle Identity Federation configuration (See Section 8.1.2.1, "Configuring Oracle WebLogic Server" and Section 8.1.2.2, "Configuring Keystore Passwords in Oracle Identity Federation").

Notes: Oracle Identity Federation does not support client authentication when connecting to LDAP servers. Oracle Identity Federation will only use the WLS trust keystore when connecting to LDAP servers.

When Searching LDAP Server over SSL

If the user and/or federation data stores are LDAP servers using SSL, and you wish to use the search operations in Fusion Middleware Control (navigate to Administration, then Identities), you will need to import the LDAP's CA certificate to the JVM's cacert keystore.

When performing the search operation, you will see the following error printed in the logs:

SEVERE: NamingException: error while interacting with an LDAP server or JNDI module
javax.naming.NameNotFoundException: remaining name: env/jmx/runtime

This is expected and will not affect the search.

8.1.2.5 Ensuring that Fusion Middleware Control can Manage an Oracle Identity Federation Target

Take these steps to enable Fusion Middleware Control to manage an Oracle Identity Federation server target:

1. Locate $INSTANCE_HOME/EMAGENT/EMAGENT/sysman/emd/targets.xml.

   Change the protocol for the 'serviceURL' property to the correct protocol. If you have more than one Oracle Identity Federation target (besides host and oracle_emd), you need to modify the 'serviceURL' for each target.

2. Locate $INSTANCE_HOME/EMAGENT/EMAGENT/sysman/config/emd.properties.

   If necessary, update the protocol for 'REPOSITORY_URL' to the correct protocol. The EM Agent uses this property to connect to Fusion Middleware Control.

3. Stop the EM Agent using the command:

   $INSTANCE_HOME/bin/opmnctl stopproc ias-component=EMAGNET
   

4. Secure the EM Agent using the command:

   $INSTANCE_HOME/EMAGENT/EMAGENT/bin/emctl secure fmagent -admin_host
   <host> -admin_port <port> -admin_user <username> [-admin_pwd <pwd>]
   

5. Restart the EM Agent using the command:

   $INSTANCE_HOME/bin/opmnctl startproc ias-component=EMAGNET
   

8.2 Managing Signing and Encryption Wallets

Oracle Identity Federation provides a way to update signing and/or encryption wallets smoothly, without interrupting service.

When you need to replace a signing or encryption wallet and a new one is uploaded, Oracle Identity Federation saves the old wallet. The server then continues to use the old wallet in all transactions until it is removed. However, generated metadata will contain the new wallet information and the old information. This allows time to notify remote providers about the change.

Once new metadata has been created and distributed to all remote providers, the old wallet can be deleted and Oracle Identity Federation will use the newly uploaded wallet for all subsequent transactions.

This section contains these topics:

• Signing and Encryption Passwords

• Replacing a Signing or Encryption Wallet

8.2.1 Signing and Encryption Passwords

As of 11g Release 1 (11.1.1) Patch Set 3, the keystore (signing key) password and the encryption key password do not need to be the same. The treatment of passwords is as follows:

• You can configure distinct store password and key password.

• If not configured, the key password is assumed to be the same as the store password.

See Also: Managing Keystores, Wallets, and Certificates in the Oracle Fusion Middleware Administrator's Guide for details about keystore management.

8.2.2 Replacing a Signing or Encryption Wallet

Follow these steps when replacing a signing or encryption wallet:

1. Upload the new wallet.

   1. Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

   2. Navigate to Administration, then Security and Trust.

   3. In the Wallets tab, click Update.

   4. Check the Update checkbox for the wallet you want to update.

   5. Select the keystore type, wallet location, password, and alias.

   6. Click OK.

2. Generate and distribute new metadata.

   1. Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

   2. Navigate to Administration, then Security and Trust.

   3. In the Provider Metadata tab, under the Generate Metadata section, select the provider type and the protocol of the metadata to be generated, and click Generate.

   4. Save the generated metadata.

   5. Distribute the generated metadata to all remote peer providers.

3. Delete the old wallet.

   1. Log in to Fusion Middleware Control and navigate to the Oracle Identity Federation instance.

   2. Navigate to Administration, then Security and Trust.

   3. In the Wallets tab, click Update.

   4. In the wallet that you have updated, click Delete old Wallet.

8.3 Setting up JCE Policy Files for Oracle WebLogic Server

By default, Oracle Identity Federation supports low-strength cryptographic key sizes for encryption/decryption operations such as XML encryption.

In order to use strong symmetric encryption algorithms, such as AES-256, you need to modify the JVM to include the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy.

Take these steps:

1. Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction policy files from this URL:

   http://www.oracle.com/technetwork/java/javase/downloads/index.html
   

2. Unzip the files in all the $JAVA_HOME/jre/lib/security directories located under the $BEA_HOME folder (to find those directories, look for US_export_policy.jar files). For every $JAVA_HOME/jre/lib/security directory, overwrite the default low strength local_policy.jar and US_export_policy.jar files with the ones provided by Oracle.

3. Restart the administration server and the managed server where Oracle Identity Federation is running.