Oracle® Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service 11g Release 1 (11.1.1) Part Number E15478-06 |
|
|
PDF · Mobi · ePub |
This appendix provides the information and steps required to ensure that OAM 11g Servers and clients (OAM Agents) can communicate securely across the Access Protocol channel. This chapter provides the following details:
Confirm that the OAM Server is running.
Securing communication between OAM Servers and clients (Webgates) means defining the transport security mode for the NAP (also known as the OAP) channel within the component registration page. The security level for the channel is specified as either:
Open: Un-encrypted communication
In Open mode, there is no authentication or encryption between the Webgate and OAM Server. The Webgate does not ask for proof of the OAM Server's identity and the OAM Server accepts connections from all Webgates. Use Open mode if communication security is not an issue in your deployment.
Simple: Encrypted communication through the Secure Sockets Layer (SSL) protocol with a public key certificate issued by Oracle
Use Simple mode if you have some security concerns, such as not wanting to transmit passwords as plain text, but you do not manage your own Certificate Authority (CA). In this case, OAM 11g Servers and Webgates use the same certificates, issued and signed by Oracle CA. For more information, see "About Simple Mode, Encryption, and Keys".
Cert: Encrypted communication through SSL with a public key certificate issued by a trusted third-party certificate authority (CA).
Use Cert mode if you want different certificates on OAM 11g Servers and Webgates and you have access to a trusted third-party CA. In this mode, you must encrypt the private key using the DES algorithm. Oracle Access Manager components use X.509 digital certificates in PEM format only. PEM refers to Privacy Enhanced Mail, which requires a passphrase. 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. For more information, see "About Cert Mode Encryption and Files".
Figure E-1 illustrates the communication channels used by OAM Servers and Webgates during user authentication and authorization.
Figure E-1 Communication Channels for OAM Servers and Webgates
Process overview: Authentication and authorization
Request is intercepted by Webgate.
Authentication (credential collection) occurs over HTTP(s) channel.
Authorization occurs over the NAP channel with OAM Agents only (not mod_osso).
Using the secure-sockets layer (SSL) protocol helps prevent eavesdropping and successful man-in-the-middle attacks across the HTTP (HTTPS) channel. The SSL protocol is included as part of most Web server products and Web browsers. SSL uses the public-and-private key encryption system, which includes the use of a digital certificate. For details about enabling SSL communication for a Web server or directory server, see your vendor's documentation.
The PEM (Privacy Enhanced Mail) format (BASE64-encoded ASCII) is preferred for private keys, digital certificates, and trusted certificate authorities (CAs). The preferred keystore format for OAM Servers is JCEKS and for OAM Clients is JKS (Java KeyStore) format. Oracle Access Manager components use X.509 digital certificates in DER (binary form of a certificate) format only.
For more information, see:
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.
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.
Administrators must ensure that the OAM Server is reachable only over the transport specified in the OAM Server configuration. OAM Server configuration defines the end points for the Server and accounts for the deployment of load balancers or reverse proxies. When the OAM Server is reachable over both HTTP and HTTPS, all requests (over either transport) are accepted.
To allow the user to interact with the OAM Server (and logout) over SSL with non-X509 authentication schemes, the specified Server Port must not be configured to require CLIENT CERTS.
With the X509 authentication scheme (X509Scheme), the OAM Server SSL Port must differ from the Server Port, and must be configured to require Client Certificates. When X509Scheme is used, the X509 module is called after credential collection. X509Scheme requires the X509 challenge method and the X509 authentication module. The fully-qualified URL to the credential collector must be specified as the Challenge URL within X509Scheme. For example: https://<oam_server>:<ssl_port>/oam/CredCollectServlet/X509.
Note:
If a relative Challenge URL is specified with X509Scheme, 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.See Also:
"Managing SSO Tokens and IP Validation"Administrators use the Oracle-provided importcert
tool for several different procedures related to keystores, keys, and certificates. Table E-1 provides the syntax for importcert
commands.
Table E-1 importcert Command Syntax
Option | Description |
---|---|
keystore |
Follow this command with the path to an existing (or new) keystore. For example: /scratch/.oamkeystore or /scratch/clientKey.jks |
privatekeyfile |
Follow this option with the path to your private key. For example: /scratch/aaa_key.der |
signedcertfile |
Follow this option with the path to your signed certificate. For example: /scratch/aaa_cert.der |
alias |
Follow this option with your keystore entry alias. Required with genkeystore.: alias |
storetype |
Follow this option with your keystore type. By default, the store type is JCEKS (OAM Server keystore). For example: Server keystore .oamkeystore, of type: JCEKS Client keystore/scratch/clientTrustStore.jks and /scratch/clientKey.jks can be used. Both are type: JKS |
genkeystore |
This flag is required for generating OAM client certificates. The client does not expose the alias and alias password parameters. However, importcert tool sets the keystore password as the alias password. Specify: Yes or No Yes imports the certificates in a new keystore. No imports certificates into an existing keystore. |
Sample for OAM Server |
- java -cp importcert.jar oracle.security.am.common.tools.importcerts.CertificateImport -keystore <path to .oamkeystore> -privatekeyfile <path to aaa_key.der> -signedcertfile <path to aaa_cert.der> -alias oam.certmode -aliaspassword <password> -storetype <JCEKS> genkeystore <yes> Enter the keystore password and alias password when prompted. |
Sample for OAM Client See Also "Generating Client Keystores for OAM Tester in Cert Mode" |
- java -cp importcert.jar oracle.security.am.common.tools.importcerts.CertificateImport -keystore <path to clientkey.JKS> -privatekeyfile <path to aaa_key.der> -signedcertfile <path to aaa_cert.der> -storetype <JKS> genkeystore <yes> Enter the keystore password when prompted. |
This section is required to generate JKS keystores to be used with OAM Tester in Cert mode only. Otherwise, you can skip this section. This section describes how to use importcert commands to generate client keystores for OAM Tester in Cert mode to contain the imported trusted certificate chain.
See Also:
"About the Importcert Tool"To generate client keystores for OAM Tester in Cert mode
Use ImportCert tool to create JKS keystores (file name specified by -privatekeyfile and -signedcertfile). For example:
- java -cp importcert.jar oracle.security.am.common.tools.importcerts.CertificateImport -keystore <Keystore path> -privatekeyfile <Private key file> -signedcertfile <Signed certificate file> path -storetype <JKS> genkeystore <yes>
Enter the keystore password when prompted.
Proceed as needed for your environment:
Remove a Keystore: Use the following command to remove the JKS keystore. For example:
keytool -delete -alias <alias> -keystore <path to clientkey.JKS> -storetype <JKS>
Enter the keystore password when prompted.
This section describes how to configure Cert mode communication for OAM 11g.
The following tasks apply to Cert mode only. In Simple mode, the bundled OAM-CA-signed certificates are used and most of the following tasks here are not needed.
Task overview: Adding certificates for the OAM Server includes
Reviewing :
Generating a Certificate Request and Private Key for OAM Server
Importing the Trusted, Signed Certificate Chain Into the Keystore
Generating a Private Key and Certificate Request for Webgates
The certificate request for Webgate generates the request file aaa_req.pem, which you must send to a root CA that is trusted by the OAM Sever. The root CA returns the 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 (reserved name for Webgate key file, which cannot be changed)
aaa_cert.pem (reserved name for Webgate certificate file, which cannot be changed)
aaa_chain.pem (reserved name for CA Cert for Webgate side)
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. However, you cannot complete OAM deployment until the certificates are issued and installed.
If you choose Cert mode when registering Webgate as 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).
Use the following procedure to retrieve the private key, certificate, and CA certificate for the OAM Server.
Note:
The certified tool to maintain consistency between 10g and 11g registration, is openSSL. Oracle recommends that you use openSSL rather than other tools to generate certificates and keys in PEM format.To retrieve the private key and certificates for OAM 11g Server
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 -config openssl_silent_ohs11g.cnf
Submit the certificate request (aaa_req.pem) to a trusted CA.
Download the CA Certificate in base64 as aaa_chain.pem.
Download the Certificate in both base64 and DER format as aaa_cert.pem and aaa_cert.der.
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
Proceed to "Retrieving the OAM Keystore Alias and Password".
Users with valid Administrator credentials can perform the following task to retrieve the alias of the certificate in the specified keystore to be used for authentication, and the password that is required to import a certificate.
To retrieve the OAM Keystore password
Confirm the Oracle Access Manager Console is running.
On the computer hosting the Oracle Access Manager 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.
Start the WebLogic Scripting Tool:
·/ wlst.sh
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>
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()
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.
Pay close attention to the password of the OAM Keystore that is displayed because this is required to import the certificates.
Proceed to "Importing the Trusted, Signed Certificate Chain Into the Keystore".
The Oracle-provided importcert tool is used to import existing private key, signed certificate (public key) files into the specified keystore format: JKS (client keystore format) or JCEKS (OAM Server keystore format; .oamkeystore for instance.).
The keystores associated with Oracle Access Manager 11g accepts only PKCS8 DER format certificates:
If you have PEM format certificates signed by your certificate authority (CA), the following procedure describes how to convert and then import these using the importcert
shipped with Oracle Access Manager 11g.
If PEM format certificates are not available, create a certificate request and have it signed by your CA before beginning the following procedure.
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.
Note:
When you use the keytool utility, the default key pair generation algorithm is Digital Signature Algorithm (DSA). However, OAM and WebLogic Server do not support DSA and you must specify another key pair generation and signature algorithm.Prerequisites
Retrieving the OAM Keystore Alias and Password
To import the trusted certificate chain into the keystore
Locate the keytool for OAM 11g in the following path:
$MW_HOME/jdk160_18/bin/keytool
Unzip importcert.zip and locate the Readme file in the following location:
$ORACLE_IDM/oam/server/tools/importcert/README
aaa_chain.pem: Using a text editor, modify the aaa_chain.pem file to remove all data except that which is contained within the CERTIFICATE blocks, then save the file.
----BEGIN CERTIFICATE----- ... CERTIFICATE ... -----END CERTIFICATE-----
Import the trusted certificate chain using the following command with details for your environment. For example:
keytool -importcert -file aaa_chain.pem -trustcacerts -storepass <password> -keystore <$ORACLE_HOME>\user_projects\domains\$DOMAIN\config\fmwconfig\ .oamkeystore -storetype JCEKS
When prompted to trust this certificate, type yes
.
aaa_cert.pem:
Edit aaa_certn.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. For example:
----BEGIN CERTIFICATE----- ... CERTIFICATE ... -----END CERTIFICATE-----
Enter the following command to convert the signed certificate (aaa_cert.pem) to DER format using openSSL or any other tool. For example:
openssl x509 -in aaa_cert.pem -inform PEM -out aaa_cert.der -outform DER
aaa_key.pem:
Edit aaa_key.pem 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. For example:
----BEGIN CERTIFICATE----- ... CERTIFICATE ... -----END CERTIFICATE-----
Enter the following command to convert the private key (aaa_key.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
Import signed DER format certificates into the keystore. For example:
Import aaa_key.der using the following command line arguments and details for your environment. For example:
c:\Middleware\idm_home\oam\server\tools\importcert
- java -cp importcert.jar oracle.security.am.common.tools.importcerts.CertificateImport -keystore <> -privatekeyfile <path> -signedcertfile <path> -alias [ -storetype <> genkeystore <> -help]
Note:
Enter the key store password and alias password when prompted. On a Windows system, use a semicolon (;) instead of a colon (:) in the command line.Proceed to "Adding Certificate Details to Access Manager Settings".
After importing the certificates into the keystore, you must add the alias and password that you specified earlier into Access Manager settings configuration in Oracle Access Manager Console, as described here.
Note:
No explicit configuration is needed for Simple mode, which is provided out of the box for OAM 11g.Prerequisites
Importing the Trusted, Signed Certificate Chain Into the Keystore
To add certificate details to Access Manager Settings
From the Oracle Access Manager Console, click the System Configuration tab.
From the System Configuration tab, Access Manager Settings section, open the Access Manager Settings page.
Expand the Access Protocol section of the page, if needed.
Fill in the alias and alias password details acquired in the previous procedure. For example:
Cert Mode Configuration
PEM keystore Alias: my_keystore_alias
PEM keystore Alias Password: my_keystore_alias_pw
Click Apply to save the configuration.
Close the page.
Open the OAM Server registration page, click the Proxy tab, change the Proxy mode to Cert, and click Apply.
Restart the OAM Server.
Proceed to "Generating a Private Key and Certificate Request for Webgates".
Use the following procedure to retrieve the private key, certificate, and CA certificate for the Webgate.
Note:
The certified tool to maintain consistency between 10g and 11g registration, is openSSL. Oracle recommends that you use openSSL rather than other tools to generate certificates and keys in PEM format.To retrieve the private key and certificates for Webgates
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
Submit the certificate request (aaa_req.pem) to a trusted CA.
Download the CA Certificate in base64 as aaa_chain.pem.
Download the Certificate in base64 format as aaa_cert.pem.
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
Proceed to "Updating Webgate to Use Certificates".
For all communication modes (Open, Simple, or Cert), the Agent registration should be updated from the Oracle Access Manager 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 Access Manager Settings
To update the communication mode in the Webgate Agent registration
From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node, and expand OAM Agents.
On the Search page, define your criteria and open the desired agent registration, as described in "Searching for an OAM Agent Registration".
On the agent's registration page, locate the Security options and click Cert (or Simple).
Cert Mode: Enter the Agent key Password as specified in Step 5 of "Generating a Private Key and Certificate Request for Webgates".
Click Apply to submit the changes.
Copy your updated Webgate files as follows:
11g Webgate:
From: $IDM_DOMAIN_HOME/output/AGENT_NAME
To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g Webgate: ObAccessClient.xml
From: $WLS_DOMAIN_HOME/output/AGENT_NAME
To: $Webgate_install_dir/oblix/lib
10g Webgate: password.xml
From: $WLS_DOMAIN_HOME/output/AGENT_NAME
To: $Webgate_install_dir/oblix/config
Copy the following files that were created when "Generating a Certificate Request and Private Key for OAM Server":
11g Webgate:
From:
To: OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g Webgate:
From:
To: $Webgate_install_dir/oblix/config
Restart the OAM Server and the Oracle HTTP Server instance.
The transport security communication mode is chosen during OAM installation. In Simple mode, the installer generates a random global passphrase initially, which can be edited as required later.
When you register an OAM Agent or a new OAM Server, you can specify the mode. However, changing the global passphrase requires that you reconfigure all agents to use Simple mode and the new global passphrase.
During agent registration, at least one OAM Server instance must be running in the same mode as the agent. Otherwise, registration fails. After agent registration, however, you could change the communication mode of the OAM Server.
Note:
Communication between the agent and server works when the Webgate mode matches (or is higher) than the OAM Server mode.The agent mode can be higher but not lower. The highest level of security is Cert mode, the lowest is Open mode:
Cert mode Simple mode Open mode
This section provides the information you need to configure Simple mode communicat
Task overview: Configuring Simple mode communication with OAM 11g includes
Reviewing:
For Simple mode encryption, Oracle Access Manager includes a certificate authority with its own private key, which is installed across all Webgates and OAM Servers. During installation, the OAM server generates and saves the private-public keypair for the server. Similarly, for the OAM agent, an Oracle certificate authority is installed with the agent installation.
The installer generates a random global passphrase initially, which can be edited or viewed as needed. When an agent is registered in SIMPLE mode, the following client certificates are generated to be consumed by clients:
aaa_key.pem: Contains private key
aaa_cert.pem: Signed certificate
password.xml: Contains the random global passphrase in obfuscated format
Note:
Changing the global passphrase requires reconfiguring all agents that are already configured in Simple mode.Oracle Access Manager generates a random global passphrase for Simple mode communication during installation. The following procedure describes how to retrieve this password.
To retrieve the random global passphrase for Simple mode communication
Ensure that the Oracle Access Manager Console is running.
On the computer hosting the Oracle Access Manager Console, locate the WebLogic Scripting Tool in the following path. For example:
$Oracle_IDM/common/bin
Where $Oracle_IDM represents the base Oracle Access Manager installation directory path; /common/bin is the path wherein the scripting tool is located.
Start the WebLogic scripting tool. For example, on a Unix system:
./ wlst.sh
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 [weblogic] : Please enter your server URL [t3://localhost:7001] : wls:/base_domain/serverConfig>
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()
View the global passphrase by entering the following command. For example:
wls:/OAM_AC> displaySimpleModeGlobalPassphrase()
Proceed to Updating 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
From the System Configuration tab, Access Manager Settings section, expand the SSO Agents node, and expand OAM Agents.
On the Search page, define your criteria and open the desired agent registration, as described in "Searching for an OAM Agent Registration".
In the registration page, locate the Security options and click Simple.
Click Apply to submit the changes.
Copy the updated Webgate files as follows:
11g Webgate:
From: $WLS_DOMAIN_HOME/output/AGENT_NAME (the WebLogic domain home where the OAM AdminServer is installed)
To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config
10g Webgate: ObAccessClient.xml
From: $WLS_DOMAIN_HOME/output/AGENT_NAME
To: $Webgate_install_dir/oblix/lib
10g Webgate: password.xml
From: $WLS_DOMAIN_HOME/output/AGENT_NAME
To: $Webgate_install_dir/oblix/config
Copy the following files, as directed for your Webgate release:
11g Webgate:
From: $IDM_DOMAIN_HOME/output/AGENT_NAME
To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/webgate/config/simple
10g Webgate:
From: $IDM_DOMAIN_HOME/output/AGENT_NAME
To: $Webgate_install_dir/oblix/config/simple
Restart the OAM Server and the Oracle HTTP Server instance.
You must restart the Web server to instantiate the change to Simple mode. Then you can validate the results
To validate Simple mode changes
From a command-line window, restart the Web server. For example:
d:\middleware\ohs_home\instances\ohs_webgate11g\bin opmnctl stopall opmnctl startall
In a browser window, enter the URL to a resource protected by the Webgate using Simple mode.
Enter your login credentials, when asked.
Confirm that the resource is served.