1. Administering Oracle Access Management
  2. Appendixes
  3. Securing Communication

B Securing Communication

Ensure that the OAM Servers and clients (OAM Agents) can communicate securely across the Access Protocol channel.

You need to perform the following tasks to secure communication:

B.1 Prerequisites to Setting up a Secure Communication between OAM Servers and Webgates

Before you proceed with setting up a secure Communication between OAM servers and webgates ensure the system level requirements are met.

Following are the requirements to perform tasks in this chapter:

  • If OAM Server mode is CERT mode, agents must use CERT mode.

  • During agent registration, at least one OAM Server instance must be running in the same mode as the agent. After agent registration, you can change the mode of the OAM Server.

See Also:

B.2 Securing Communication Between OAM Servers and WebGates

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 Servers and WebGates use the same certificates, issued and signed by Oracle CA.

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

    See About Cert Mode Encryption and Files.

See Also:

About Certificates, Authorities, and Encryption Keys

Logically the request is to the Access Manager credential collector. However, when you have a Web server proxy in front of the WebLogic AdminServer, with a <LocationMatch "/*">, all requests are routed through the proxy. In this case, there is perimeter defense using the proxy.

Figure B-1 illustrates the communication channels used by OAM Servers and WebGates during user authentication and authorization.

Figure B-1 Communication Channels for OAM Servers and WebGates

Description of Figure B-1 follows
Description of "Figure B-1 Communication Channels for OAM Servers and WebGates"

Process overview: Authentication and authorization

  1. Request is intercepted by WebGate.

  2. Authentication (credential collection) occurs over HTTP(s) channel.

  3. Authorization occurs over the NAP channel with OAM Agents only.

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. Access Manager components use X.509 digital certificates in DER (binary form of a certificate) format only.

See:

B.2.1 About Certificates, Authorities, and Encryption Keys

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

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

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.

See Also:

B.2.2 About Security Modes and X509Scheme Authentication

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://managed_server_host:managed_server_ssl_port/oam/CredCollectServlet/X509

Note:

  • If a relative Challenge URL is specified with X509Scheme, the OAM Server uses the specified Server Host/Port to construct the fully-qualified URL of the X509 Credential Collector. However, this configuration will not work.
  • When using x509 authentication, you are never prompted to re-enter the CAC card reader pin, or select/provide cert for the browser. This is expected behavior and is CAC card and/or browser specific.

See Also:

"Managing SSO Tokens and IP Validation"

B.2.3 The Importcert Tool

Administrators use the Oracle-provided importcert tool for several different procedures related to keystores, keys, and certificates.

Table B-1 provides the syntax for importcert commands.

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

B.2.4 TLS 1.2 Support in Oracle Access Management

Transport Layer Security (TLS) 1.2 is supported with 12c to provide communications security over the Internet. This protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery.

OAM supports TLS 1.2 across the following channels:

Channel TLS 1.2 Status

Front

TLS 1.2 is fully supported since incoming traffic is terminated on the Load Balancer, Web Server or Weblogic Server.

OAP Back

The 12c Webgates fully support TLS 1.2.

LDAP Back

TLS 1.2 transport is supported with 11.1.2.3.0 BP8. However, TLS 1.2 is not supported when using an IDS Profile based User Identity Store.

JDBC Back

Databases are abstracted using WLS Datasources, which can be configured to use TLS 1.2 to connect to the database. OES uses JDBC as the Database abstraction and can be configured to use TLS 1.2.

Outbound HTTPS

All outbound calls are done using JSSE and rely on the JDK specific defaults. Starting with JDK 6 121 Update and JDK 7 Update 95, you can control the platform TLS protocols by setting the system property jdk.tls.client.protocols.

TLS 1.2 supports cipher suites that gets installed with JDK.

In a freshly installed environment,

  • Consider 12c PS3 OAM server and 12c PS3 webgates, employing latest versions of OAM server and webgate. SSL communication between them will use TLSv1.2 protocol and SHA-2 certificates.

  • Consider 12c PS3 OAM server and 12CPS2/ R2PS3 webgates, employing older versions of webgate and OAM server. OAM can support TLSv1.2 and SHA-2 certificates but 12CPS2/ R2PS3 webgates cannot.

    Since we have latest 12c OAM server combined with older versions of webgate/OAM servers where TLS1.2 and SHA2 is not supported, we need to relax the security posture in OAM by updating the java.security file with the following changes:

    • Open the java.security file located at JAVA_HOME/jre/lib/security/ in an editor.

    • Remove TLSv1, TLSv1.1, MD5withRSA from the following key:

      key - jdk.tls.disabledAlgorithms

    • Remove MD5 from the following key:

      key - jdk.certpath.disabledAlgorithms

Steps to enable TLSv1.2 in OAM 12c environment

Enable TLSv1.2 in OHS:

Update the below two files in 12c OHS:

/scratch/work/TLStest/OHS12c/Oracle_Home/user_projects/domains/base_domain/config/fmwconfig/components/OHS/ohs1/ssl.conf
/scratch/work/TLStest/OHS12c/Oracle_Home/user_projects/domains/base_domain/config/fmwconfig/components/OHS/instances/ohs1/ssl.conf
SSLProtocol -ALL +TLSv1.2

Enable TLSv1.2 in DB:

Follow the below steps to enable in DB:

  • Create a wallet for server jnetadmin_s and one for client jnetadmin_c

    
mkdir root

mkdir jnetadmin_s

mkdir jnetadmin_c

export ORACLE_HOME=/scratch/alice/work/db1427

export T_WORK=$ORACLE_HOME

export ROOT_CERT_DIR=$T_WORK/root

export TNS_ADMIN_SERVER=$T_WORK/jnetadmin_s

export TNS_ADMIN_CLIENT=$T_WORK/jnetadmin_c

 

./orapki wallet create -wallet $ROOT_CERT_DIR -pwd welcome1

./orapki wallet add -wallet $ROOT_CERT_DIR -dn "CN=Root,C=US" -keysize 2048 -self_signed -validity 3650 -pwd welcome1

./orapki wallet export -wallet $ROOT_CERT_DIR -dn "CN=Root,C=US" -cert $ROOT_CERT_DIR/b64certificate.txt -pwd welcome1

./orapki wallet create -wallet $TNS_ADMIN_SERVER -auto_login -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_SERVER -dn "CN=Server,OU=ST,O=Oracle,ST=California,C=US" -keysize 2048 -pwd welcome1

./orapki wallet export -wallet $TNS_ADMIN_SERVER -dn "CN=Server,OU=ST,O=Oracle,ST=California,C=US" -request $TNS_ADMIN_SERVER/creq.txt -pwd welcome1

./orapki cert create -wallet $ROOT_CERT_DIR -request $TNS_ADMIN_SERVER/creq.txt -cert $TNS_ADMIN_SERVER/cert.txt -validity 3650 -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_SERVER -trusted_cert -cert $ROOT_CERT_DIR/b64certificate.txt -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_SERVER -user_cert -cert $TNS_ADMIN_SERVER/cert.txt -pwd welcome1

./orapki wallet create -wallet $TNS_ADMIN_CLIENT -auto_login -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_CLIENT -dn "CN=Client,OU=ST,O=Oracle,ST=CA,C=US" -keysize 2048 -pwd welcome1

./orapki wallet export -wallet $TNS_ADMIN_CLIENT -dn "CN=Client,OU=ST,O=Oracle,ST=CA,C=US" -request $TNS_ADMIN_CLIENT/creq.txt -pwd welcome1

./orapki cert create -wallet $ROOT_CERT_DIR -request $TNS_ADMIN_CLIENT/creq.txt -cert $TNS_ADMIN_CLIENT/cert.txt -validity 3650 -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_CLIENT -trusted_cert -cert $ROOT_CERT_DIR/b64certificate.txt -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_CLIENT -user_cert -cert $TNS_ADMIN_CLIENT/cert.txt -pwd welcome1

./orapki wallet add -wallet $TNS_ADMIN_CLIENT -trusted_cert -cert $TNS_ADMIN_SERVER/cert.txt -pwd welcome1

  • Create/Modify wallet.ora files

    cd jnetadmin_s

    vim wallet.ora

    content as below:

    
WALLET_LOCATION=

  (SOURCE=

     (METHOD=FILE)

     (METHOD_DATA=

         (DIRECTORY=/scratch/alice/work/db1427/jnetadmin_s/)

     )

  )

  • Modify sqlnet.ora

    
SSL_VERSION=1.2

ssl_client_authentication=false

ifile=/scratch/alice/work/db1427/jnetadmin_s/wallet.ora

  • Modify listener.ora

    
LISTENER =

  (DESCRIPTION_LIST =

    (DESCRIPTION =

      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1521))

      (ADDRESS = (PROTOCOL = TCP)(HOST = slc03rvu.us.oracle.com)(PORT = 1521))

        (ADDRESS=(PROTOCOL=tcps)(HOST=slc03rvu.us.oracle.com)(PORT=5551))

    )

  )

ADR_BASE_LISTENER = /scratch/work

ssl_client_authentication=false

ifile=/scratch/alice/work/db1427/jnetadmin_s/wallet.ora

SSL_VERSION=1.2

SID_LIST_listener=(SID_LIST=

  (SID_DESC=(SID_NAME=db1427)(ORACLE_HOME=/scratch/alice/work/db1427))

  (SID_DESC=(SID_NAME=db1427)(GLOBAL_DBNAME=db1427.us.oracle.com))

)

  • Restart database and listener

    restart DB

    lsnrctl stop

    lsnrctl start

  • Use openssl to verify TLSv1.2

    openssl s_client -showcerts -tls1_2 -connect slc03rvu.us.oracle.com:5551

Add WLS JDBC TLS Datasources:

  • Import DB server cert generated in step 3 to WLS Demo Trust.jks

    keytool -importcert -trustcacerts -alias dbroot -keystore $MW_HOME/wlserver/server/lib/DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase -file $ROOT_CERT_DIR/b64certificate.txt

  • Navigate to wls console->Service->Data Sources, update below JDBC Data Source with TLS connection details.

  • Open each data source, click Connection Pool, update URL and Properties as below:

    URL example:

    jdbc:oracle:thin:/@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=slc03sfc.us.oracle.com)(PORT=2484)))(CONNECT_DATA=(SERVICE_NAME=db4758..us.oracle.com))(SECURITY=(SSL_SERVER_CERT_DN="CN=slc03sfc.us.oracle.com")))

    Properties example:

    
javax.net.ssl.trustStoreType=JKS

javax.net.ssl.trustStorePassword=DemoTrustKeyStorePassPhrase

javax.net.ssl.trustStore=/net/slc03sfc/scratch/work/mw4838/wlserver_10.3/server/lib/DemoTrust.jks

  • Restart the servers.

Enable TLS for OAP channel on WLS using multiple modes:

See, Configuring Oracle HTTP Server WebGate for Oracle Access Manager to configure 12c Cert and Simple Mode.

For Simple mode, remove MD5 from jdk.certpath.disabledAlgorithms option in java.security file and add the following property in $OHS_ORACLE_HOME/user_projects/domains/base_domain/config/fmwconfig/components/OHS/ohs1/ohs.plugins.nodemanager.properties file, 
environment.ORACLE_SSL_ALLOW_MD5_CERT_SIGNATURES=1

Enable TLS for OAM using OAM ID store

Follow the below steps:

  • Login to OAM console.

  • Create a new OAM ID Store.

    Create New OAMID Store

  • Update the Default store to the ID store you just created.

    User Identity Stores

  • Update LDAP Authentication Module to the ID Store you just created.

    LDAP Authentication Module

  • Shutdown all servers, and import OUD's certificate to JDK key store.

    openssl s_client -showcerts -connect slc06bku.us.oracle.com:1636 </dev/null2>/dev/null|openssl x509 -outform PEM >cert.pem
openssl x509 -outform der -in cert.pem -out cert.der
keytool  -importcert -alias oud -file cert.der -keystore cacerts  -storepass changeit

  • Update oam-config.xml,

    Increase version number:

    <Setting Name=”Version” Type=”xsd:integer”>91</Setting>

    Update to SSL:

    <Setting Name=”LDAP_URL” Type=”xsd:string”>ldaps://slc06bku.us.oracle.com:1636</Setting>

    Add TLS1.2 parameter:

    <Setting Name="LDAP_SSL_PROTOCOL" Type="xsd:string">TLSv1.2</Setting>

  • Adding below lines to config/fmwconfig/servers/oam_server1/logging.xml and config/fmwconfig/servers/AdminServer/logging.xml

    <logger name='oracle.oam.user.identity.provider' level='TRACE:32'useParentHandlers='false'>
<handler name='odl-handler'/>
</logger>

  • Start servers and access protected resources, you will see tls logs in oam_server1-diagnostic.log:

    [2016-08-09T01:46:49.398-07:00] [oam_server1] [TRACE:32] [] [oracle.oam.user.identity.provider] [tid: [ACTIVE].ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid: 036b5306-7533-4458-ad54-5f5be25adadf-00000106,0] [APP: oam_server] [partition-name: DOMAIN] [tenant-name: GLOBAL] [SRC_CLASS: oracle.security.am.engines.common.identity.provider.impl.ids.IDSLDAPConfigurator] [SRC_METHOD: getIDSInstance] Setting ssl protocol as TLSv1.2

Enable TLS for OAM using IDS Profile

Follow the below steps:

  • Log in to OAM console.

  • Create an IDS Profile.

    Create IDS Profile

  • Click Sync IDS Profile and update Default store to the IDS profile you just created.

    User Identity Store

  • Update LDAP Authentication Module to the ID Store you just created.

    LDAP Authentication Module

  • Add TLS parameter to ids libovd using wlst,

    modifyLDAPAdapter(adapterName='IdsProfile', attribute='Protocols', value='TLSv1.2', contextName='ids')

  • Create key store for ids libovd,

    export ORACLE_HOME=/scratch/work/mw169

    export WL_HOME=/scratch/work/mw169/wlserver

    export JAVA_HOME=/scratch/work/view/nowang_dte8461/bootstrap/java/1.8.0-51-16-150608.1.8.0.51.0016/jdk

    ./libovdconfig.sh -host slc03sfc.us.oracle.com -port 22899 -userName weblogic -domainPath /scratch/work/mw169/user_projects/domains/WLS_IDM -createKeystore -contextName ids

  • Add OUD certificate to libOVD key store,

    openssl s_client -showcerts -connect slc06bku.us.oracle.com:1636 </dev/null 2>/dev/null|openssl x509 -outform PEM >cert.pem

    openssl x509 -outform der -in cert.pem -out cert.der

    keytool -import -keystore adapters.jks -storepass weblogic1 -alias oud -file cert.der

  • Add "-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true -Djavax.net.debug=all" to setDomainEnv.sh and check the logs to see the TLS connection messages from the oam_server1 output console redirect file.

  • Restart all servers, and access protected resources.

See Also:

Configuring the LDAP and LDAPS Connection Handlers and Configuring Secure Sockets Layer (SSL)

B.3 Generating Client Keystores for OAM Tester in Cert Mode

Generate JKS keystores to be used with OAM Tester that is in Cert mode only, else skip this topic.

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:

The Importcert Tool

To generate client keystores for OAM Tester in Cert mode

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

  2. Proceed as needed for your environment:
  3. 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.

B.4 Configuring Cert Mode Communication for Access Manager

Configure Cert mode communication for Access Manager with at least one OAM Server instance running in the same mode as the agent.

This topic describes how to configure Cert mode communication for Access Manager. The following tasks apply to Cert mode only.

Note:

In Simple mode, the bundled Access Manager-CA-signed certificates are used and most of the following tasks are not needed.

Prerequisites

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.

Task overview: Adding certificates for the OAM Server includes

  1. Reviewing:

  2. Generating a Certificate Request and Private Key for OAM Server

  3. Importing the Trusted, Signed Certificate Chain Into the Keystore

  4. Adding Certificate Details to Access Manager Settings

  5. Generating a Private Key and Certificate Request for WebGates

  6. Updating WebGate to Use Certificates

B.4.1 About Cert Mode Encryption and Files

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

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 must be copied to the Webgate instance area manually after OAM 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 OAM 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.

B.4.2 Generating a Certificate Request and Private Key for OAM Server

Retrieve the private key, certificate, and CA certificate for the OAM Server.

Note:

The certified tool 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 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 -sha256
  2. Create CA that generates rootCA.key and aaa_chain.pem files.
    penssl genrsa -aes256 -out rootCA.key 4096
openssl req -x509 -new -nodes -key rootCA.key -days 7300 -sha256 -out aaa_chain.pem
  3. Submit the certificate request (aaa_req.pem) to a trusted CA to get a signed (aaa_cert.pem) certificate.
    openssl x509 -req -in aaa_req.pem -CA aaa_chain.pem -CAkey rootCA.key -CAcreateserial -sha256 -out aaa_cert.pem -days 500
  4. Convert aaa_cert.pem into DER format.
    openssl x509 -in aaa_cert.pem -inform PEM -out aaa_cert.der -outform DER
  5. Convert aaa_key.pem into DER format.
    openssl pkcs8 -topk8 -nocrypt -in aaa_key.pem -inform PEM -out aaa_key.der -outform DER

    Tip:

    The common name for generating a certificate request for OAM server could be the host name of the OAM cluster's load balancer for clustered environments and the name of the host where OAM server is deployed for the non-clustered environments.

B.4.3 Retrieving the .OAMKeystore password stored in UDM

You can retrieve the keystore credential with Oracle Enterprise Manager Fusion Middleware Control console.

  1. Log into the Oracle Enterprise Manager Fusion Middleware Control 12c console using the context URL, /em. For example, http://<HOST>:<PORT>/em.
  2. Navigate to the System MBean Browser page by clicking the Weblogic Domain drop-down and selecting System MBean Browser.
  3. Search for the credentialFromUDM operation as described in the following steps:
    1. Select the binoculars icon in the System Mbean Browser.
    2. Change the MBean name to Operations and enter the text credentialFromUDM. Press the enter key to search.
    3. Scroll down and select the credentialFromUDM operation link to open the corresponding page.
  4. To retrieve the .OAMKeystore password, enter the following parameter values and click Invoke.
    • p1 = oracle.oam.OAMStore (mapname)
    • p2 = JKS (key)

    The password is displayed in the Return Value pane.

B.4.4 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 Access Manager 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 Access Manager.

  • 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 8 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, Oracle Access Management and WebLogic Server do not support DSA and you must specify another key pair generation and signature algorithm.

Prerequisites

To import the trusted certificate chain into the keystore:

  1. For setting up OAM Server in CERT mode, before making any changes to .oamkeystore, download the artifacts using offline WLST command: 

    downloadAccessArtifacts(domainHome="/new/path/base_domain", propsFile="/path/dbschema.properties")

---- contents of dbschema.properties ----
oam.entityStore.schemaUser=MYPREFIX_OAM
oam.entityStore.schemaPassword=Secret
oam.entityStore.ConnectString=jdbc:oracle:thin:@dbhost.us.oracle.com:1521/servicename.us.oracle.com

    Note:

    At every restart of Admin servers , changes are pulled in from DB . Hence we need to downloadAccessArtifacts and saveAccessArtifacts , to save the cert mode changes .

  2. Locate the keytool in the following path:

    $MW_HOME/jdk8/bin/keytool

  3. Unzip importcert.zip and locate the Readme file in the following location:

    $ORACLE_IDM_HOME/oam/server/tools/importcert/README

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

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

  6. When prompted to trust this certificate, type yes.

  7. aaa_cert.pem:

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

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

  8. aaa_key.pem:

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

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

  9. Import signed DER format certificates into the keystore. For example:

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

  10. After making changes, please upload the changes to db using the following offline WLST command: saveAccessArtifacts(domainHome="/mwhome/user_projects/domains/base_domain", propsFile="/path/dbschema.properties").

  11. Proceed to Adding Certificate Details to Access Manager Settings.

B.4.5 Adding Certificate Details to Access Manager Settings

After importing the certificates into the keystore, add the alias and password that you specified earlier into Access Manager settings configuration in Oracle Access Management Console.

Note:

No explicit configuration is needed for Simple mode, which is provided out of the box.

See Also:

To add certificate details to Access Manager Settings

  1. In the Oracle Access Management Console, click Configuration at the top of the window.
  2. In the Launch Pad tab, select Access Manager from the View drop-down menu in the Settings section.
  3. In the Access Protocol section, 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

  4. Click Apply to save the configuration.
  5. Close the page.
  6. Open the OAM Server registration page, click the Proxy tab, change the Proxy mode to Cert, and click Apply.
  7. Restart the OAM Server.
  8. Proceed to the following topic:

B.4.6 Generating a Private Key and Certificate Request for WebGates

Retrieve the private key, certificate, and CA certificate for the WebGate using openSSL.

The certified tool 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

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

    Tip:

    The common name for generating a certificate request for WebGates could be the host name of the Web Server where the agent is deployed.

  6. Proceed to Updating WebGate to Use Certificates.

B.4.7 Supporting Two-Way SSL for CERT Mode Communication

In two-way SSL support for CERT mode communication, the user certificate is shared with server while performing the SSL handshake. Therefore, the user certificate must be added to cwallet.sso.

You must manually add the user certificate to the cwallet.sso using the orapki utility. See, Keystore Management Tools in Administering Oracle Fusion Middleware

Note down the DN of the user certificate before adding the user certificate to the wallet.
  1. Check if the trusted certificate exists in cwallet.sso.
    $MW_HOME/oracle_common/bin/orapki wallet display -wallet ./
    If the command displays the trusted certificate in the wallet content, proceed to next step. If the trusted certificate is not displayed, add it to the wallet:
    $MW_HOME/oracle_common/bin/orapki wallet add -wallet ./ -trusted_cert -cert aaa_chain.pem -auto_login_only
  2. Add user certificate request.

    For example,

    $MW_HOME/oracle_common/bin/orapki wallet add -wallet ./ -dn 'CN=oamserver,OU=OAM,O=Oracle,L=Canada,ST=Canada,C=US' -keysize 2048 -auto_login_only
  3. Export the user certificate request

    For example,

    $MW_HOME/oracle_common/bin/orapki wallet export -wallet ./ -dn 'CN=oamserver,OU=OAM,O=Oracle,L=Canada,ST=Canada,C=US' -request certreq.pem
  4. Submit the user certificate request (certreq.pem) to a trusted CA to get a signed (aaa_cert_file.pem) certificate.
    openssl x509 -req -days 1825 -in certreq.pem -CA aaa_chain.pem -CAkey aaa_key.pem -set_serial 01 -out aaa_cert_file.pem

    Add -sha256 flag if required.

  5. Add the user certificate to the wallet

    For example,

    $MW_HOME/oracle_common/bin/orapki wallet add -wallet ./ -cert aaa_cert_file.pem -user_cert -auto_login_only
  6. Verify the user certificate in the wallet
    $MW_HOME/oracle_common/bin/orapki wallet display -wallet ./
Start the server instance and test the two-way SSL for CERT mode.

B.4.8 Updating WebGate to Use Certificates

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

  • Registering an Agent: If you choose Cert mode when registering an OAM Agent, a field appears where you can enter the Agent Key Password.

  • Editing/Updating an Agent: When editing an OAM WebGate registration, password.xml is updated only when the mode is changed from Open to Cert or Simple to Cert.

    Editing the agent Key Password does not result in creation of a new password.xml. In Cert mode, once generated, password.xml cannot be updated.

Prerequisites

Adding Certificate Details to Access Manager Settings

To update the communication mode in the WebGate Agent registration

  1. In the Oracle Access Management Console, click Application Security at the top of the window.
  2. In the Launch Pad tab, click Agents.
  3. On the Search page, define your criteria and open the desired agent registration, as described in "WebGate Search Controls".
  4. On the agent's registration page, locate the Security options and click Cert (or Simple).
  5. Cert Mode: Enter the Agent key Password as specified in Step 5 of "Generating a Private Key and Certificate Request for WebGates".
  6. Click Apply to submit the changes.
  7. Copy your updated WebGate files as follows:

    OAM WebGate:

    • ObAccessClient.xml
    • cwallet.sso (OAM WebGate only)
    • password.xml

    • From: $IDM_DOMAIN_HOME/output/AGENT_NAME

    • To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config

  8. Copy the following files that were created when "Generating a Certificate Request and Private Key for OAM Server":

    OAM WebGate:

    • From:

      • aaa_key.pem: WebGate11g_home/webgate/ohs/tools/openssl
      • aaa_cert.pem: The location where this was saved after receiving from CA
      • aaa_chain.pem: The location where this was saved after receiving from CA

    • To: OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config

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

B.5 Configuring Simple Mode Communication with Access Manager

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.

Note:

Communication between the agent and server works when the WebGate mode matches (or is higher) than the OAM Server mode.

When you register an OAM Agent or a new OAM Server, you can specify the Security mode. However, changing the global passphrase requires that you reconfigure all agents to use the mode and the new global passphrase.

Note:

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.

The highest level of security is Cert mode, the lowest is Open mode. The agent mode can be higher but not lower. For example, Open mode can be updated to SIMPLE or CERT.

This section provides the information you need to configure Simple mode communication.

Task overview: Configuring Simple mode communication includes

  1. Reviewing:

  2. Retrieving the Global Passphrase for Simple Mode

  3. Updating WebGate Registration for Simple Mode

  4. Verifying SIMPLE Mode Configuration

B.5.1 About Simple Mode, Encryption, and Keys

For Simple mode encryption, 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.

B.5.2 Retrieving the Global Passphrase for Simple Mode

Retrieve the random global passphrase generated by Access Manager for Simple mode communication during installation.

To retrieve the random global passphrase for Simple mode communication

  1. Ensure that the Oracle Access Management Console is running.
  2. On the computer hosting the Oracle Access Management Console, locate the WebLogic Scripting Tool in the following path. For example:
    $ORACLE_IDM_HOME/common/bin

    Where $ORACLE_IDM_HOME represents the base installation directory path; /common/bin is the path wherein the scripting tool is located.

  3. Start the WebLogic scripting tool. For example, on a Unix system:
    ./ 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 [weblogic] :
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. View the global passphrase by entering the following command. For example:
    wls:/OAM_AC> displaySimpleModeGlobalPassphrase()
  7. Proceed to "Updating WebGate Registration for Simple Mode".

B.5.3 Updating WebGate Registration for Simple Mode

Artifacts generated for Simple Security mode use the Global Pass phrase and any change must be propagated to WebGates.

To update an existing WebGate registration for Simple mode, you can delete the WebGate registration using the Oracle Access Management Console, then re-register it (specifying Simple mode and disabling the automatic generation of policies). Alternatively, you can edit the WebGate registration and then copy the artifacts as described here.

See Also:

To update the WebGate registration for Simple mode

  1. In the Oracle Access Management Console, click Application Security at the top of the window.
  2. In the Launch Pad tab, click Agents.
  3. On the Search page, define your criteria and open the desired agent registration, as described in "WebGate Search Controls".
  4. In the registration page, locate the Security options and click Simple.
  5. Click Apply to submit the changes.
  6. Copy the updated WebGate files as follows:

    OAM WebGate:

    • ObAccessClient.xml
    • cwallet.sso (OAM 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/ohs2/webgate/config

  7. Copy the following files, as directed for your WebGate release:
    • aaa_key.pem
    • aaa_cert.pem

    OAM WebGate:

    For 11g Webgate:

    • From: $IDM_DOMAIN_HOME/output/AGENT_NAME

    • To: $OHS_INSTANCE_HOME/config/OHS/ohs2/webgate/config/simple

    For 12c Webgate:

    • From: $IDM_DOMAIN_HOME/output/AGENT_NAME

    • To: ${Oracle_Home}/user_projects/domains/base_domain/config/fmwconfig/components/OHS/ohs1/webgate/config/simple

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

B.5.4 Verifying SIMPLE Mode Configuration

Restart the Web server to instantiate the change to SIMPLE mode to validate the results

To validate SIMPLE mode changes:

  1. From a command-line window, restart the Web server as shown in the following example:
    For 11g Webgate:
    d:\middleware\ohs_home\instances\ohs_webgate11g\bin
opmnctl stopall
opmnctl startall
    For 12c Webgate:
    $(Oracle_Home)/user_projects/domains/base_domain/bin/stopComponent.sh ohs1
( stopComponent.sh ohs1 ) $(Oracle_Home)/user_projects/domains/base_domain/bin/startComponent.sh ohs1
  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.