Understanding OAM 11g ASDK Configuration and Cert Requirements

Oracle provides documentation on developing an Access Client for the OAM 11g ASDKhttp://docs.oracle.com/cd/E40329_01/dev.1112/e27134/as_api.htm#autoId0, but getting it to work can be challenging when running the Access Servers in Simple or Cert Mode.  In this article I will not explain how to create an Access Client, there are already good examples out there for that.  What I want to cover is the correct structure of the Access Client configuration including all the required files and code snippets to hopefully save you a lot of time.

What is an Access Client?

An Access Client is basically a way to developed a custom WebGate using the OAM Access Server SDK — AKA ASDK.  The SDK and API can be used to develop anything from your own custom authentication web service, a way to validate a Users token, to a simple mechanism to enhance a User’s login with additional session information.

NOTE: 
At the time of this article the latest ASDK 11.1.2.2.0 can be downloaded by going to
http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/oid-11gr2-2104316.html. The newer ASDK is backward compatible with 10g, but also provides many new features:
* Enumerating sessions for the given user
* Terminating the given session
* Setting attributes in the given user session
* Retrieving attributes set in the given session
* ++ Validating user credentials without establishing a session
* ++ Validating user credentials without establishing a session and performing authorization in the same request
————————————————————————————————————————————————–

++ The last two functions are also provided with the com.oblix.access package in the Access Manager 11g Access SDK. Additionally, the Access SDK provides a modified implementation of the user logout functionality for removing the server side session. This functionality is not supported with 10g OAM Server.

Step 1) Creating the Configuration Structure 

The latest 11.1.2.2.0 OAM Development Guide provides a section 2.52. Configuration Requirements http://docs.oracle.com/cd/E40329_01/dev.1112/e27134/as_api.htm#autoId26, which provides plenty of information on various configuration requirements, but it lacks information on how to properly structure the configuration directories and where each required file related to OAP communication should come from. Knowing this information is key to getting an Access Client to work in SIMPLE or CERT mode, and even parts of it is required just to get it to work in OPEN mode. Below illustrates the directory structure of where the configuration files are stored, which files go where, and what exactly is needed for either OPEN, SIMPLE, or CERT modes. Start by creating this directory structure in your Java project along with copying or importing the appropriate files into your project as follows. See Table 1 to learn where to get all the required files found in the Access Client Configuration structure.

Access Client Configuration Certificate Structure -

config/
|
|– cwallet.sso (Get from WebGate – **)
|– jps-config.xml (Get from ASDK Sample – **)
|
`– oblix/
|
|– config/
|   |– password.xml (Get from WebGate – **)
|   |
|   `– simple/
|       |– oamclient-keystore.jks (Get from OAM Domain – **)
|       `– oamclient-truststore.jks (Get from OAM Domain – **)
`– lib/
     `– ObAccessClient.xml (Get from WebGate – *)

NOTE: 
Important Information -
*  - Required for All modes
** - Required for 11g Simple or Cert Mode
NOTE: If using Cert Mode then aaa_cert.pem and aaa_key.pem would be replaced by a third party CA 
(Certificate Authority) generated certificate along with importing the CA certificate into the 

OAM trust store.

As a side note If you need to switch your Access Servers from OPEN to SIMPLE mode, the following link provides the basic steps
http://docs.oracle.com/cd/E40329_01/admin.1112/e27239/keytool.htm#AIAAG5632.

Step 2) Setting the credstore location in the jps.config.xml

In OAM 11g the jps-config.xml file is used for a variety of things, but for the 11g ASDK it is used to let the ASDK know where the configuration structure is located. The jps-config.xml file is found within the OAM 11g ASDK download file. In the previous config structure you can see that the jps-config.xml file is under the root folder, in this case “config”. Since all the required files are below this the location parameter only needs to be set to the current directory. So below you can see location=”.” for current directory. This should already be default as “.”, if so no changes are required.

<!– Specify agent key wallet location relative to this jps-config.xml location –>
<serviceInstance name=”credstore” provider=”credstoressp” location=”.”>
     <description>File Based Credential Store Service Instance</description>
</serviceInstance>

Now we can set a variable that references the cred store following snippet line of code and should be placed toward the top of the Access Client where all the variables are defined. I used “./config” because in my example the top directory path for the certificate files is “config”, and as long as the compiled Java Access Client is placed in the path of ./config it will find all the right files as long as the lower part of the tree is structured as mentioned earlier.

// Declaring variables
public static final String m_configLocation = “./config”;

Step 3) Creating the Access Client Instance

Now that the structure is created in your project, the correct files are imported, the jps-config.xml is correctly set, and a static string has been defined to reference the configuration location, we can now create the Access Client instance.

Just below the main area of the Access Code an instance of the Access Client is normally created.  You will need to include the public static variable from earlier as a parameter.  The following code snippet is an example has the m_configuration variable, which is of course the variable pointing to the configuration. Using m_configuration without additional parameters tells the ASDK to default to a 11g Access Client which requires a 11g WebGate profile. This is in contrast to using ac = AccessClient.createDefaultInstance(m_configLocation,AccessClient.CompatibilityMode.OAM_10G); which would only be used if using a WebGate 10g profile. In our case we are better off using 11g. Another option is to us ac = AccessClient.createDefaultInstance(m_configLocation,AccessClient.CompatibilityMode.OAM_11G), but leaving it to just plain m_configLocation is fine and what is recommended.

// Creating an Access Client instance
ac = AccessClient.createDefaultInstance(m_configLocation);

Now build your code to see if it works.

Reference Table of Configuration Files with Explanations

To further help I am providing a table that includes all the important files used within the config directory along with explanations on the purpose behind these configuration files. For additional information on the files you can also see section 2.5.2 Configuration Requirements documentation http://docs.oracle.com/cd/E40329_01/dev.1112/e27134/as_api.htm#autoId26. The table also provides locations on where to get all the required files, which you would then place into the config structure that was described earlier.

File Name	Explanation
cwallet.sso	Created when registering a 11g WebGate and contains the secret key needed by the OAM Access Server when encrypting a token sent from the agent (Access Client is the agent).  Found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ <RREG_WEBGATE> directory.
jps-config.xml	This is required for an 11g Access Client and used to read the cwallet.sso, but also contains a parameter location=”.”  to reference the location of the config folder.
aaa_cert.pem	Generated when registering a 11g WebGate in Simple mode.  Found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ webgate-ssl directory.
aaa_key.pem	Generated when registering a 11g WebGate in Simple mode.  Found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ webgate-ssl directory.
oamclient-truststore.jks	Generated when using SIMPLE or CERT mode for OAM 11g and found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ webgate-ssl directory.  This file is more or less like an internal CA for OAM.  If using CERT mode the third party CA would need to be imported into this file.
oamclient-keystore.jks	The private keystore for the oamclient-truststore.jks file.  Also found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ webgate-ssl directory.
password.xml	Contains the Global Passphrase used by OAM 11g for the aaa_cert.pem and aaa_key.pem files.  Also found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ <RREG_WEBGATE> directory.
ObAccessClient.xml	Holds all the configuration information for the Access Client in order too not only communicate with the Access Server(s), but also defines the behavior the Access Client will abide.  Found in the $ORACLE_HOME/user_projects/domains/<oam_domain>/output/ <RREG_WEBGATE> directory.

Tips on Validating the TrustStore and PEM Certificate

There may be times where you get complaints about the certs or keys, but hopefully if you take the following steps it will work out the first time.

1) Configure SIMPLE mode if not already done using http://docs.oracle.com/cd/E40329_01/admin.1112/e27239/keytool.htm#AIAAG5632 that was already mentioned earlier.

2) Register the 11g WebGate in SIMPLE mode from the OAM Console and get the following files from $ORACLE_HOME/user_projects/domains/<oam_domain>/output/<RREG_WEBGATE> to the respective config location.
• cwallet.sso
• ObAccessClient.xml

3) Copy the following files from $ORACLE_HOME/user_projects/domains/<oam_domain>/output/webgate-ssl to the respective config location.
• oamclient-truststore.jks
• oamclient-keystore.jks
• aaa_cert.pem
• aaa_key.pem
• password.xml

4) Get the jps-config.xml file from the ASDK download http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/oid-11gr2-2104316.html and copy it to the respective config location.  Leaving the default config location in the jps-config.xml file should be fine unless you find a reason to change it.

5) For CERT mode the only changes would be following section 2.5.4.2 Cert Transport Security Mode http://docs.oracle.com/cd/E40329_01/dev.1112/e27134/as_api.htm#autoId30 and making sure you import the third party CA certificate into the oamclient-truststore.jks file.

If you still find errors relating to the certs, you can validate your truststore and cert using some common tools. For the oamclient-truststore.jks file run the keytool command as follows.

keytool –list –keystore oamclient-truststore.jks –v

You will get a prompt for a password, but you can just press enter to continue which should present you with something similar to this. Pay attention to the Owner and Issuer. This is the built in OAM CA and should also be present in the WebGate aaa_cert.pem file.

Results:

***************** WARNING WARNING WARNING *****************
* The integrity of the information stored in your keystore *
* has NOT been verified! In order to verify its integrity, *
* you must provide your keystore password. *
***************** WARNING WARNING WARNING *****************
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: oam.simple.ca
Creation date: Jul 7, 2014
Entry type: trustedCertEntry
Owner: CN=NetPoint Simple Security CA - Not for General Use, OU=NetPoint, O="Oblix, Inc.", L=Cupertino, ST=California, C=US
Issuer: CN=NetPoint Simple Security CA - Not for General Use, OU=NetPoint, O="Oblix, Inc.", L=Cupertino, ST=California, C=US
Serial number: 0
Valid from: Wed Apr 01 07:57:22 CDT 2009 until: Thu Mar 28 07:57:22 CDT 2024
Certificate fingerprints:
      MD5: 05:F4:8C:84:85:37:DB:E3:66:87:EF:39:E0:E6:B2:3F
      SHA1: 97:B0:F8:19:7D:0E:22:6B:40:2A:73:73:1B:27:B2:7B:8D:64:82:21
      Signature algorithm name: MD5withRSA
      Version: 1
*******************************************
*******************************************

TIP: If you run the keytool command and get the following error “keytool error: gnu.javax.crypto.keyring.MalformedKeyringException: incorrect magic”, that means the keytool being used is probably incorrect.  Use the keytool found in the JAVA home under $JAVA_HOME/bin directory.

Just in case you are using the aaa_cert.pem file you can use OpenSSL to list the certificate chain to make sure the CA matches the truststore. Run the following command openssl command; OpenSSL should be part of Linux.

openssl –x509 aaa_cert.pem –text

TIP:  If openssl command is not found you can use the openssl that is included in the WebGate or AccessServerSDK install under the <Install Path>/oblix/tools/openssl directory.

You should see the beginning of the output that similar to below.  The CA should be found in the Issuer, but in a reverse order of what you saw from the oamclient-truststore.jks output.   If this is CERT mode then you would verify that the CA matches the third party certificate that was imported into the oamclient-truststore.jks file.

Certificate:
  Data:
     Version: 1 (0x0)
     Serial Number: 10 (0xa)
     Signature Algorithm: md5WithRSAEncryption
     Issuer: C=US, ST=California, L=Cupertino, O=Oblix, Inc., OU=NetPoint, CN=NetPoint Simple Security    CA - Not for General Use
     Validity
        Not Before: Jul 7 23:27:28 2014 GMT
        Not After : Jul 4 23:27:28 2024 GMT
     Subject: CN=oam.simple.cert
     Subject Public Key Info:
        Public Key Algorithm: rsaEncryption
        RSA Public Key: (1024 bit)
           Modulus (1024 bit):
           00:b6:61:b1:d6:1e:50:98:1e:03:05:b5:9f:2d:61:
           a8:ce:a0:c2:02:04:bd:ec:fe:2a:be:29:1d:98:74:
           38:49:79:1a:51:69:c5:8b:6e:15:32:a4:a9:5e:3a:

Summary

Though this article does not provide all the information in creating an Access Client, nor could it, it should still provide some key information that is missing in the official Oracle Developer’s Guide for OAM that can certainly save you a lot of frustration in getting an Access Client to work especially when running in SIMPLE or CERT mode. Using what has been covered along with the existing documentation and the basic sample Access Client found in section 2.2.3 Sample Code: Simple Access Client http://docs.oracle.com/cd/E40329_01/dev.1112/e27134/as_api.htm#autoId10should help get you up and running in no time. Good luck!