E Securing Communication with OAM 11g

About Certificates, Authorities, and Encryption Keys

Oracle Access Manager components use X.509 digital certificates in PEM format only. PEM refers to Privacy Enhanced Mail, which requires a pass phrase.

The PEM (Privacy Enhanced Mail) format is preferred for private keys, digital certificates, and trusted certificate authorities (CAs). The preferred keystore format is the JKS (Java KeyStore) format.

In cryptography, a public key is a value provided by a designated authority to be used as an encryption key. The system for using public keys is called a public key infrastructure (PKI). As part of a public key infrastructure, a certificate authority checks with a registration authority (RA) to verify information provided by the requestor of a digital certificate. When the RA verifies the requestor's information, the CA can issue a certificate.

Private keys can be derived from a public key. Combining public and private keys is known as asymmetric cryptography, which can be used to effectively encrypt messages and digital signatures.

Depending on the public key infrastructure, the digital certificate establishes credentials for Web-based transactions based on:

• Certificate owner's name

• Certificate serial number

• Certificate expiration date

• A copy of the certificate holder's public key, which is used to encrypt messages and digital signatures

• The digital signature of the certificate-issuing authority is provided so that a recipient can verify that the certificate is real

Digital certificates can be stored in a registry from which authenticating users can look up the public keys of other users.

About Security Modes and X509Scheme Authentication

OAM Server configuration defines the end points for the OAM Server and accounts for the deployment of load balancers or reverse proxies. When the HTTPS protocol is specified, the specified Server Port must not be configured to require CLIENT CERTS. This allows the user to interact with the server over SSL for all non-X509 authentication schemes and logout.

X509Module is called after Credential Collection if the corresponding authentication scheme is configured.

The X509 authentication scheme (X509Scheme) requires the X509 challenge method and X509 authentication module. The X509 module is called after credential collection when the X509Scheme is used.

When the X509Scheme is specified as the authentication scheme and the user must be challenged for credentials, the fully-qualified URL to the credential collector must be specified as the Challenge URL parameter of the authentication scheme. For example: https://<oam_server>:<ssl_port>/oam/CredCollectServlet/X509.

The specified SSL Port must be different from the Server Port and must be configured to require CLIENT CERTS. If a relative Challenge URL is specified, the OAM Server uses the specified Server Port/Host/Port to construct the fully-qualified URL of the X509 Credential Collector. However, this configuration will not work.

When the OAM Server is reachable over both HTTP and HTTPS, all requests (come over either transport) are accepted. Administrators must ensure that the OAM Server is only reachable over the transport specified in the OAM Server configuration.

About Cert Mode Encryption and Files

The certificate request for WebGate generates the request file aaa_req.pem. You must send this WebGate certificate request to a root CA that is trusted by the OAM Sever. The root CA returns the WebGate certificates, which can then be installed either during or after 10g WebGate installation (for 11g WebGate these must be copied to the WebGate instance area manually after WebGate installation and configuration).

• aaa_key.pem

• aaa_cert.pem

• aaa_chain.pem

During component installation in Cert mode, you are asked to present a certificate obtained from an external CA. If you do not yet have a certificate you can request one. Until you receive the certificate, you can configure the WebGate in Simple mode. You cannot complete OAM deployment until the certificates are issued and installed.

If you choose Cert mode when registering an OAM Agent, a field appears where you can enter the Agent Key Password. When editing an 11g WebGate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In cert mode, once generated, password.xml cannot be updated. Editing the agent Key Password does not result in creation of a new password.xml.

You must create a Cert request and send that to the CA. When the certificate is returned you must import it to the OAM Server (or copy it to the WebGate).

Generating a Private Key, Certificate Request, Installing Certificates for OAM Server

Use the following procedure to retrieve the private key, certificate, and CA certificate for the OAM Server.

To retrieve the private key and certificates for OAM 11g Server

1. Generate both the certificate request (aaa_req.pem) and Private Key (aaa_key.pem) as follows:

   openssl req -new -keyout aaa_key.pem -out aaa_req.pem -utf8 -nodes
   

2. Submit the certificate request (aaa_req.pem) to a trusted CA.

3. Download the CA Certificate in base64 as aaa_chain.pem.

4. Download the Certificate in both base64 and DER format as aaa_cert.pem and aaa_cert.der.

5. Encrypt the private key (aaa_key.pem) using a password as follows:

   openssl rsa -in aaa_key.pem -passin pass: -out aaa_key.pem -passout pass: 
   ******** -des 
   

6. Proceed to "Retrieving the OAM Keystore Alias and Password Using Custom WLST Commands".

Retrieving the OAM Keystore Alias and Password Using Custom WLST Commands

Users with valid OAM Administrator credentials can perform the following task to retrieve the keystore alias and password that is required to import a certificate.

To retrieve the OAM Keystore password

1. Confirm the OAM Administration Console is running.

2. On the computer hosting the OAM Administration Console, locate the WebLogic Scripting Tool in the OAM Installation path to use when retrieving the keystore password. For example:

   $ORACLE_IDM/common/bin/

   Here, $ORACLE_IDM is the OAM 11g base installation directory; /common/bin is the path in which the scripting tool is located.

3. Start the WebLogic Scripting Tool:

   ·/ wlst.sh
   

4. In the WLST shell, enter the command to connect and then enter the requested information. For example:

   wls:/offline> connect() 
   Please enter your username [weblogic] :  
   Please enter your password [welcome1] :
   Please enter your server URL [t3://localhost:7001] :
   wls:/base_domain/serverConfig>
   

5. Enter the following command to change the location to the read-only domainRuntime tree (For help, use help(domainRuntime)). For example:

   wls:/OAM_AC> domainRuntime() 
   

6. Enter the following command to list the credentials for the OAM keystore. For example:

   wls:/OAM_AC/domainruntime> listCred(map="OAM_STORE",key="jks")
   

   Here, OAM_STORE represents the name of your OAM Keystore.

7. Pay close attention to the password of the OAM Keystore that is displayed because this is required to import the certificates.

8. Proceed to "Importing CA-Signed Certificates Into the Keystore".

Importing CA-Signed Certificates Into the Keystore

The keystore associated with Oracle Access Manager 11g accepts only PEM format certificates.

If you already have certificates signed by your certificate authority (CA) in PEM format, the following procedure describes how to import the certificate using the keytool importcert tool shipped with OAM 11g. The Readme file that is bundled with the tool provides instructions for importing the certificates in the keystore.

Following are the steps for using the JDK version 6 keytool. If you have a different version of keytool, refer the documentation for your JDK version.

Prerequisites

Retrieving the OAM Keystore Alias and Password Using Custom WLST Commands

To import certificates into the keystore

1. Locate the importcert tool for OAM 11g in the following path:

   $ORACLE_IDM/oam/server/tools/importcert

2. Unzip importcert.zip and locate the Readme file.

3. Import the trusted certificate chain using the following command and details for your environment:

   keytool -importcert -file aaa_chain.pem - trustcacerts -storepass <password> 
   -keystore <MW_HOME>/user_projects/domains/domain_name/config/fmwconfig/ 
   .oamkeystore -storetype JCEKS 
   

4. Convert the private key (aaa_key.pem) and signed certificate (aaa_cert.pem) to DER format using openSSL or any other tool. For example:

   openssl pkcs8 -topk8 -nocrypt -in aaa_key.pem -inform PEM -out aaa_key.der  
   -outform DER
   

   Perform the following if you do not have aaa_cert.der.

   1. Enter the following command:

      openssl x509 -in aaa_cert.pem -inform PEM -out aaa_cert.der -outform DER
      -outform DER
      
      

   2. Edit aaa_chain.pem using TextPad to remove all data except that which is contained within the CERTIFICATE blocks, and save the file in a new location to retain the original.

      -----BEGIN CERTIFICATE-----
      ...
      CERTIFICATE
      ...
      -----END CERTIFICATE-----
      

5. Import signed PEM format certificates into the keystore. For example:

   1. Locate the importcert tool for OAM 11g in the following path:

      $ORACLE_IDM/oam/server/tools/importcert

   2. Unzip importcert.zip and locate the Readme file.

   3. Import signed PEM format certificates using the following command line arguments and details for your environment:

      - java -cp importcert.jar:$CLASSPATH oracle.security.am.common.tools.importcerts.CertificateImport -keystore <> -keystorepassword <> -privatekeyfile <> -signedcertificate <> -alias 
      [-aliaspassword <>]
      

6. Proceed with "Adding Certificate Details to OAM Common Server Properties"

Adding Certificate Details to OAM Common Server Properties

After importing the certificates into the keystore, you must add the alias and password that you retrieved earlier into the OAM Proxy section of each OAM Server configuration in the Oracle Access Manager 11g Administration Console.

The Secure Sockets Layer (SSL) protocol is commonly used to manage secure communication on the Internet. Using the SSL protocol to protect communication between OAM Servers and WebGates helps prevent eavesdropping and successful man-in-the-middle attacks. The SSL protocol is included as part of most Web server products and Web browsers (Microsoft and Netscape, for instance). SSL uses the public-and-private key encryption system, which includes the use of a digital certificate.

Prerequisites

Importing CA-Signed Certificates Into the Keystore

To add certificate details to OAM Server configurations

1. From the Oracle Access Manager 11g Administration Console, click the System Configuration tab.

2. From the System Configuration tab, navigation tree, double-click Server Instances to view the OAM Server Common Properties page.

3. Click the OAM Proxy tab.

4. Fill in the alias and alias password details acquired in Step 5c of "Importing CA-Signed Certificates Into the Keystore", like one of the following examples:

   Simple Mode Configuration

   Global Passphrase: simple_passphrase

   Cert Mode Configuration

   PEM KeyStore Alias: my_keystore_alias

   PEM KeyStore Alias Password: my_keystore_alias_pw

5. Click Apply to save the configuration.

6. Close the page.

7. Open the OAM Server registration page, click the Proxy tab, change the Proxy mode to Cert, and click Apply.

8. Restart the OAM Server.

9. Proceed to "Generating a Private Key, Certificate Request, and Getting Certs for WebGates".

Generating a Private Key, Certificate Request, and Getting Certs for WebGates

Use the following procedure to retrieve the private key, certificate, and CA certificate for the WebGate.

To retrieve the private key and certificates for WebGates

1. Generate both the certificate request (aaa_req.pem) and Private Key (aaa_key.pem) as follows:

   openssl req -new -keyout aaa_key.pem -out aaa_req.pem -utf8 -nodes
   

2. Submit the certificate request (aaa_req.pem) to a trusted CA.

3. Download the CA Certificate in base64 as aaa_chain.pem.

4. Download the Certificate in base64 format as aaa_cert.pem.

5. Encrypt the private key (aaa_key.pem) using a password as follows:

   openssl rsa -in aaa_key.pem -passin pass: -out aaa_key.pem -passout pass: 
   ******** -des 
   

6. Proceed to "Updating the WebGate to Use Certificates".

Updating the WebGate to Use Certificates

For all communication modes (Open, Simple, or Cert), the Agent registration should be updated from the OAM Administration Console.

If you choose Cert mode when registering an OAM Agent, a field appears where you can enter the Agent Key Password. When editing an 11g WebGate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert. In cert mode, once generated, password.xml cannot be updated. Editing the agent Key Password does not result in creation of a new password.xml.

Prerequisites

Adding Certificate Details to OAM Common Server Properties

To update the communication mode in the WebGate Agent registration

1. From the System Configuration tab, navigation tree, expand the Agents node.

2. Expand OAM Agents, expand the 11g Webgates (or 10g Webgates) node, and then double-click the desired agent's name.

3. On the agent's registration page, locate the Security options and click Cert (or Simple).

4. Cert Mode: Enter the Agent key Password as specified in Step 5 of "Generating a Private Key, Certificate Request, and Getting Certs for WebGates".

5. Click Apply to submit the changes.

6. Copy the following updated WebGate files as follows:

   
   ObAccessClient.xml
   cwallet.sso
   password.xml
   

   • From: IDM_DOMAIN_HOME/output/AGENT_NAME

   • To: OHS_INSTANCE_HOME/config/OHS/ohs2webgate/config

7. Copy the following files (created during "Generating a Private Key, Certificate Request, Installing Certificates for OAM Server") as follows:

   
   aaa_key.pem
   aaa_cert.pem
   aaa_chain.pem
   

   • From: IDM_DOMAIN_HOME/output/AGENT_NAME

   • To: OHS_INSTANCE_HOME/config/OHS/ohs2webgate/config

8. Restart the OAM Server and the Oracle HTTP Server instance.

About Simple Mode, Encryption, and Keys

For Simple mode encryption, Oracle Access Manager ships a certificate authority with its own private key, which is installed across all WebGates and OAM Servers. For each public key there is a corresponding private key that Oracle Access Manager stores in the aaa_key.pem file.

A program named openSSL in the \tools subdirectory automatically generates the key pair and the following files for Simple mode security:

• cacert.pem the certificate request, signed by the Oracle-provided openSSL Certificate Authority

• password.xml contains the random global passphrase that was designated during agent registration, in obfuscated format. This needs to be copied to the WebGate instance location.

• aaa_key.pem contains your private key (generated by openSSL).

• aaa_cert.pem signed certificates in PEM format

The transport security communication mode is chosen during OAM installation. The installer generates a random global passphrase initially, which can be edited as required later.

When you install an OAM Agent, you can request CA certificates. When you register an OAM Agent or a new OAM Server, you must specify the communication mode. However, changing the global passphrase requires reconfiguring all agents to use Simple mode and the new global passphrase.

Updating the WebGate Registration for Simple Mode

Artifacts generated for Simple Security mode use the Global Pass phrase and a change must be propagated to WebGates. You can delete the WebGate registration and re-register it (specifying Simple mode and disabling the automatic generation of policies) or you can edit the WebGate registration and then copy the artifacts as described here.

To update the WebGate registration for Simple mode

1. From the System Configuration tab, navigation tree, expand the Agents node.

2. Expand OAM Agents, expand the 11g Webgates (or 10g Webgates) node, and then double-click the desired agent's name.

3. On the agent's registration page, locate the Security options and click Simple.

4. Click Apply to submit the changes.

5. Copy the following updated WebGate files as follows:

   
   ObAccessClient.xml
   cwallet.sso (11g WebGate only)
   password.xml
   

   • From: $WLS_DOMAIN_HOME/output/AGENT_NAME (the WebLogic domain home where the OAM AdminServer is installed)

   • To: OHS_INSTANCE_HOME/config/OHS/ohs2webgate/config

6. Copy the following files, as directed here:

   
   aaa_key.pem
   aaa_cert.pem
   

   • From: IDM_DOMAIN_HOME/output/AGENT_NAME

   • To: OHS_INSTANCE_HOME/config/OHS/ohs2webgate/config/simple

7. Restart the OAM Server and the Oracle HTTP Server instance.

Verifying Simple Mode Configuration

You must restart the Web server to instantiate the change to Simple mode. Then you can validate the results

To validate Simple mode changes

1. From a command-line window, restart the Web server. For example:

   d:\middleware\ohs_home\instances\ohs_webgate11g\bin
   opmnctl stopall
   opmnctl startall
   

2. In a browser window, enter the URL to a resource protected by the WebGate using Simple mode.

3. Enter your login credentials, when asked.

4. Confirm that the resource is served.