Integrating Oracle Access Manager with WebLogic Server 10g

Hi all,
This post will talk about the integration between Oracle Access Manager 10g with WebLogic Server 10g. This is not applicable for WebLogic versions 10.3.1 and higher.  The functionality achieved with this integration is to get the Single Sign-On between applications deployed on WebLogic Server (webLogic resource) and non-WebLogic resources. Therefore SSPI connector can be used to achieve Single Sign-On between OAM access gates and web gates.
Infrastructure involved: 

• Oracle Access Manager 10.1.4.2 and higher
• WebLogic SSPI
• Oracle HTTP Server (for reverse proxy)

It is assumed that Oracle Access Manager is already installed and will not talk about any components installation unless needed for this integration.
It is good to upgrade the Oracle Access Manager to 10.1.4.2 if you are using 10.1.4.1 as there are some bugs associated with this integration.
WebLogic SSPI can be downloaded here (linux) or here (windows). Here I have selected OHS as reverse proxy and this can be any other webserver of your choice provided WebGate is already there.
Until WebLogic Server 10.3.0, this integration has been achieved using SSPI connector.
Security Service Provider Interface (SSPI) Connector:
WebLogic security framework and WLS connector are based on J2EE standards and an implementation of JAAS. Together, WebLogic implementation of JAAS is called SSPI.  SSPI consists of several provider modules such as Authentication provider, Identity Asserter, Authorization provider, Role Mapping provider, Deployment Provider.
Authentication Provider: This provider uses OAM authentication services to authenticate users (based on username and password) who acces WebLogic applications. This provider does not provide  Single Sign-On capability.
 Authorization Provider: This provider uses OAM authorization services to authenticate users who access WebLogic resource. The authorization is done based on policies that are specified in the Policy Manager.
Identity Asserter: This is very essential provider when a user wants Single Sign-On capability. This is similar to Authentication provider which validates the already authenticated user based on ObSSOCookie. This is used in case of proxied configuration.
Role Mapper: This provider returns security roles of a user. The groups that the user is part of, are returned as part of actions configured in a authentication policy of policy domain.
Deployment Provider: This provider (though not part of JAAS specification)  monitors the applications that are deployed or undeployed on the WebLogic Server and writes information about these applications to either NetPointDeployPolicy.txt or NetPointUndeployPolicy.txt. 
Architecture: 
 
Process Flow:

1. User requests for a WebLogic resource protected by OAM. In this case, the authen method configured in web.xml should be CLIENT-CERT.
2. WebGate intercepts the request and checks wit the Access Server whether the resource is protected or not. If the resource is protected, it fetches the Authentication scheme configured for that resource.
3. User is challenged for username and password based on the Auth scheme configured for that resource.
4. User submits the credentials.
5. WebGate will pass the credentials to Access Server for validation. If the user is authenticated successfully, access server creates session token and passes to WebGate. Webgate will set the ObSSOCookie and appends it in HTTP Header. The plugin configured in the Proxy server (mod_proxy) will forward the request to the WebLogic server.
6. The WebLogic server plugin passes the cookie to WebLogic server.
7. WebLogic security framework invokes the SSPI connector which inturn invokes the Identity Asserter. The Identity Asserter expects ObSSOCookie as an external token for validating the user. The Asserter sets the cookie in the HTTP response object once it validates the token.
8. The Identity Asserter extracts the cookie from HTTP header. The Asserter retrieves the user identity from the Access Server using a return action defined in a special auth scheme in OAM. A resource with URL /Authen/Basic is protected by OAM and is used by SSPI internally to authenticate users.
9. The Authorization provider talks to the Access Server to verify whether the user is authorized to access the resource or not. The Role Mapping provider uses the access gate to communicate with the Access Server to determine what OAM roles are defined to the user. These roles are mapped to security roles in WebLogic. In OAM, these roles are defined as return action /Authen/Roles when getting an authorization policy.

If the authorization is successful, WebLogic server enables the user to access the requested resource. The ObSSOCookie is set so that when user attempts to access additional OAM protected non-WebLogic resources, re-authentication is not performed. Thus Single Sign-On is achieved between webgates and access gates.
Installation and Configuration:
This integration involves:

• Configure OAM for SSPI
• SSPI connector install
• Configure SSPI Connector
• Deploy Policy Domains
• Deploy WebLogic Application
• Configure Reverse proxy
• Test for SSO
• Troubleshooting

Configure OAM for SSPI:
SSPI connector communicates with both Identity and Access Servers. SSPI connector also expects user information about privileges, groups, actions, responses etc., you will need an user with respect to SSPI to talk to access server. Lets name the user as wlsadmin (create the user) and assign the user Master Identity Administrator, Master Administrator, Delegated Identity Administrator.
1. Create the resource type definitions in OAM for the following.

• wl_url: resource operation as GET and POST
• wl_svr: resource operation as BOOT and DEFAULT
• wl_adm: resource operation as DEFAULT
• wl_ejb: resource operation as EXECUTE
• wl_authen: resource operation as LOGIN

2. Create the WebLogic authentication scheme to be used by the WebLogic policy domain with following values.
Name: Oracle WebLogic Access and Identity authentication scheme
Description: Used to authenticate users who access WebLogic resources.
Level: 1
Challenge Method: Basic
Challenge Parameter: realm:Oracle Access and Identity
SSL Required: No
Challenge Redirect: (Leave blank)
Enabled: (Leave as is)
Specify the credential_mapping and validate_password plugin values as shown below.

credential_mapping      obMappingBase="o=company,c=us",obMappingFilter=      "(&(&(objectclass=inetorgperson)(uid=%userid%))      (|(!(obuseraccountcontrol=*))      (obuseraccountcontrol=ACTIVATED)))"

validate_password obCredentialPassword="password"

Specify the domain name (o=company,c=us) as per your environment.
3. Create the second authentication scheme for un-protecting certain resources, such as gif images in WebLogic resources using the following details and the Anonymous authentication scheme as a template:
General tab:
Name: Oracle WebLogic Anonymous Authentication
Description: Used to un-protect gifs, and so on.
Level: 0
Challenge Method: Anonymous
Parameter: (Leave blank)
SSL Required: No
Challenge Redirect: (Leave blank)
Enabled: Yes
Provide the plugin values as shown below.

credential_mapping obMappingBase="o=company,c=us",obMappingFilter="
     (uid=OblixAnonymous)"

4. Configure an Access Gate for SSPI connector.  This is the access gate used by security providers to communicate with Access Server. Follow the OAM installation guide for creating an access gate. FYI, port need not be specified.
5. Backup the config.xml and boot.properties.
6. Install the SSPI connector. The steps are straight forward and I will make a note of few things to remember.
Select Advanced as Configuration option.
Enter allow for Map the authorization result obstain.
Enter the webpass hostname and port.
Enter the user and group search attributes.
Select the transport mode option as open or simple or cert.
Enter the access gate details as specified in Access gate profile.
Configure SSPI connector:
1. Goto the location sspi_install_dir/NetPointSecuProvForWeblogic.
2. Take backup of files NetPointResourceMap.conf, NetPointResourceMap.conf and NetPointProvidersConfig.properties.
3.  Edit the file NetPointProvidersConfig.properties with following values
OB_LogLevel=Info
OB_LogLevel=sspi_conn_install/NetPointSecuProvForWeblogic/

OB_AdminUserName=wlsadmin

 OB_AdminUserCreds=password

OB_CookieDomain=.domain.com (change it as per your environment)

4. Copy the file NetPointResourceMap.conf and NetPointProvidersConfig.properties to weblogic domain directory.

5. Copy the wl92NetPointSecurityProviders.jar from sspi_conn/NetPointSecuProvForWeblogic/oblix/lib/mbeantypes/wl92NetPointSecurityProviders.jar to wlsserver_103/server/lib/mbeantypes.

6. Take a backup of file setDomainEnv.sh or cmd and edit the file with values as shown below.

Search for end of file and place this text after export JAVA_OPTIONS line.

# SET WLSConnector Classpath and other paths
export OAMWLC="/u01/oracle/sspi/NetPointSecuProvForWeblogic"
export OAMWLCDIR="${OAMWLC}/oblix/lib"
LD_LIBRARY_PATH="${OAMWLCDIR}"
export LD_LIBRARY_PATH
export PATH="${PATH}:${OAMWLCDIR}"
export WLC_LIB_CLASSPATH="${OAMWLCDIR}/jobaccess.jar${CLASSPATHSEP}${OAMWLCDIR}/bcprov-jdk14-125.jar${CLASSPATHSEP}
${OAMWLCDIR}/wlNetPoint.jar${CLASSPATHSEP}${OAMWLCDIR}/xerces.jar"

Note:Be careful with WLC_LIB_CLASSPATH value as it should not have any spaces or line breaks.
7. Comment the existing classpath and replace with a new one as shown below.
CLASSPATH=”${PRE_CLASSPATH}${CLASSPATHSEP}${WLC_LIB_CLASSPATH}${CLASSPATHSEP}${WEBLOGIC_CLASSPATH}${CLASSPATHSEP}${POST_CLASSPATH}$
{CLASSPATHSEP}${WLP_POST_CLASSPATH}”
export CLASSPATH
8. Restart the weblogic server. Now you should see the new jars in the classpath.
9. Take a backup of file setupNetPointRealm.properties present in the location sspi_connector/NetPointSecuProvForWeblogic.
10. Edit the file  setupNetPointRealm.properties with values as shown below.
Enter the hostname, domain name, weblogic server port, username and password details and save it.
11. Goto the location  sspi_connector/NetPointSecuProvForWeblogic and execute setupNetPointRealm_wl92.sh.
Note: Though you are using weblogic server 10.3.0, you should execute setupNetPointRealm_wl92.sh file, don’t execute the file setupNetPointRealm.sh.
12. This script will create the NetPointRealm with necessary security providers.
Deploy Policy Domains:
1. Take backup of file NetPointWeblogicTools.properties present in location sspi_conn/NetPointSecuProvForWeblogic/oblix/tools/npWLTools and edit with values as given below.
ObWLTools.Debug=true
ObPolicyDomain.Name=WebLogic Server Security Provider
ObWLTools.DeployPolicy=false
ObWLSDomain.Dir=weblogic directory location 
ObWLAuthenticationScheme.Name=OAM WebLogic Server Basic Authentication
ObWLNoneAuthenticationScheme.Name=OAM WebLogic Anonymous Authentication
2. Create a file runDeployerTool.sh under this location sspi_conn/NetPointSecuProvForWeblogic/oblix/tools/npWLTools
export CLASSPATHSEP=”:”
export OAMWLC=”sspi_conn/NetPointSecuProvForWeblogic”
export OAMWLCDIR=”${OAMWLC}/oblix”
export CLASSPATH=”${CLASSPATH}${CLASSPATHSEP}${OAMWLCDIR}/lib/jobaccess.jar${CLASSPATHSEP}${OAMWLCDIR}/tools/npWLTools;
${CLASSPATHSEP}${OAMWLCDIR}/tools/npWLTools/npWLTools.jar”
export PATH=”${PATH}:${OAMWLCDIR}/lib”
export LD_LIBRARY_PATH=”${OAMWLCDIR}/lib”
echo $CLASSPATH
/u01/jdk160_05/bin/java com.oblix.weblogic.tools.NetPointPolicyDeployer wlsadmin password
Note: This is for linux environment, if its windows, follow the one shown below.
set CLASSPATHSEP=;
set OAMWLC=D:/sspi_Connector/NetPointSecuProvForWeblogic
set OAMWLCDIR=%OAMWLC%/oblix
set CLASSPATH=%CLASSPATH%;%OAMWLCDIR%/lib/jobaccess.jar;%OAMWLCDIR%/tools/npWLTools;%OAMWLCDIR%/tools/npWLTools/npWLTools.jar
set PATH=%PATH%;%OAMWLCDIR%/lib
set LD_LIBRARY_PATH=%OAMWLCDIR%/lib
echo %CLASSPATH%
D:/bea/jdk160_05/bin/java com.oblix.weblogic.tools.NetPointPolicyDeployer wlsadmin password
3. Run the deployertool and check the log for any errors. This tool will create a policy domain with resources, authorization policies etc., and verify it by logging it to OAM policy manager console.
4. Now login to weblogic console and inspect the new realm NetPointRealm created. Check for users and groups, security providers etc., Remember that this is not default realm yet.
5. Goto the providers tab, Certification Path and click the WebLogicCertPathProvivider and enable the check box set current builder.
6. Enable NetPointRealm as default realm in the console.
7. Stop the WebLogic server. Change the boot.properties file and edit the username and password with wlsadmin and password values.
8. Start the weblogic server and you should see Netpointrealm is the default realm and you should be able to login to WLS console using wlsadmin and password.
Deploy the WebLogic application: 
You can deploy a sample weblogic application to the server where Netpointrealm is the default realm. Goto the WebLogic policy domain in OAM console and add the resource /sample/index.jsp and save it.
Configure Reverse Proxy:
1. In this case, I have used OHS as reverse proxy.
2. Create a OHS webgate profile in OAM console and install the OHS webgate. I am not briefing about this more as its pretty straight forward.
3. Edit the httpd.conf file of OHS server and goto the end of file and enter the following lines.
ProxyPass /sample http://sspi_hostname:port/sample
Test the SSO:
1. Now access the application http://reverseproxy_hostname:port/sample.
2. You will be challenged with credentials with the authentication scheme configured for it.
3. If you access any other resource protected by the OAM with the same authentication level configured for /sample application, you should be able to access it directly without re-authentication.
Troubleshooting Tips:
Refer the Oracle Documentation.

References: 
Oracle SSPI Integration guide