This appendix presents instructions on configuring SOAP Web services access. It contains the following sections:
Setting Up Client Side Keystore to Secure the SOAP User Password
Setting Up the Base Environment in OAAM Native SOAP Integration
Out-of-the-box, OAAM publishes Web services at the URL: /oaam_server/services. Starting with OAAM 11g Release 2 (11.1.2.0.0), the default mechanism to secure OAAM Web Services is by using Oracle Web Services Manager (OWSM) policies. Configuration of OWSM policies for authentication (HTTP Basic authentication with username and password request) and authorization (user's membership in configured group of users) is covered in this section. Authentication checks whether the passed user credentials are correct and authorization checks whether user is allowed to access the requested resource based on the user's membership in a group, for example, the user/group in the WebLogic embedded user store. Oracle Web Services Manager (OWSM) policies manage SOAP authentication and authorization through Oracle Enterprise Manager Fusion Middleware Control.
The requirements for accessing the OAAM web service are the following:
Configuration of the SOAP web access requires the OAAM Extensions Shared Library for Native Integration using SOAP
The configurable properties must be specified in oaam_custom.properties and this file should be in the Java Classpath of the client application.
An overview of tasks you need to perform to secure OAAM Web Services is provided below.
Table I-1 Securing OAAM Web Access
| No. | Task | Information |
|---|---|---|
|
1 |
Enable web services authentication. Set up the Oracle Web Services Manager (OWSM) Policy to set HTTP Basic Authentication on |
OAAM Web Services can be protected by Oracle Web Services Manager (OWSM) using the policy |
|
2 |
Create a user with valid username and password and associate the user to a group that will be configured to be able to access OAAM web services. |
SOAP authentication is implemented using a user name and password. Web Services/SOAP clients need to send the user name and password for successful communication with OAAM web services. The user name and password must be associated with a user that is accessible to the application server. In order for that user to have permissions to perform operations on web services, the user must be in a group that is associated with an authorization policy. |
|
3 |
Configure web services authorization. |
Using the Oracle Web Services Manager (OWSM) policy |
|
4 |
Set up security for web services. |
Web Services/SOAP clients need to send the user name and password for successful communication with OAAM web services. The password needs to be stored in a KeyStore for security. Note: This step is not required if SOAP Authentication is disabled on the OAAM server. |
OAAM Web Services can be protected by Oracle Web Services Manager (OWSM) using the policy oracle/wss_http_token_service_policy. The wss_http_token_service_policy policy enforces authentication and uses the credentials in the HTTP header to authenticate users. SOAP requests would be authenticated (HTTP Basic authentication) against the configured realm (users in WebLogic embedded user store).
To set up the Oracle Web Services Manager (OWSM) Policy to set HTTP Basic Authentication on /oaam_server/services follow these steps:
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL http://weblogic-admin-hostname:port/em.
Under weblogic_domain, select the domain and select oaam_server_server1 and right-click and select the Web Services option.
Click Attach Policies.
Select all the rows corresponding to OAAM Web Services and click the Next button
To enable SOAP Authentication:
Select the row oracle/wss_http_token_service_policy.
To disable SOAP Authentication:
Select the rows oracle/no_authentication_service_policy and oracle/no_authorization_service_policy.
Click the Next button.
If you disable the SOAP Web Service authentication on the server (which is by default enabled), the client can use the Web service without having been authenticated.
Click the Attach button in the next page.
Restart OAAM Server if required.
By performing the authentication configuration in this section, OAAM Web Services can be accessed by any valid username/password present in a configured realm, for example, all the user credentials which can pass authentication, can access OAAM Web Services.
SOAP authentication is implemented using a user name and password. This user name and password must be associated with a user that is accessible to the application server. In order for that user to have permissions to perform operations on the web services, the user should be added to a group that can access the OAAM web services.
This section provides instructions to:
Create a group. Later you will associate the group with the authorization policy. This chapter will use OAAM_WebServices_Group as an example of a group that will have access to URL: /oaam_server/services.
Create a user that you will add to the OAAM_WebServices_Group.
In a WebLogic deployment, this SOAP user can be stored and managed within the WebLogic security realm.
OAAM clients are configured to use this user name and password when invoking web services through the following oaam_custom.properties properties:
vcrypt.soap.auth.keystorePassword - Base64 encoded Password used to open the system_soap.keystore vcrypt.soap.auth.aliasPassword - Base64 encoded Password used to retrieve the key stored in the keystore vcrypt.soap.auth.username - Username of the SOAP user vcrypt.soap.auth.keystoreFile - Filename of the keystore (should be system_soap.keystore)
To create the user and group, proceed as follows:
Using the WebLogic console, create a group in configured realm. This group will contain users who will be allowed access to OAAM web services once the group is associated with the authorization policy. For example, the OAAM_WebServices_Group group can be created.
Create a user, oaamsoap1, by providing details to identify the user and a username and password for the user.
Associate the user, oaamsoap1, with the group, OAAM_WebServices_Group, by configuring the group membership for the oaamsoap1.
Using the Oracle Web Services Manager (OWSM) policy oracle/binding_authorization_permitall_policy, authorization can be configured for OAAM Web Services. The binding_authorization_permitall_policy policy provides simple permission-based authorization for the request based on the authenticated user at the SOAP binding level. This policy ensures that the user has permission to perform an operation. This policy should follow an authentication policy where the user is established and can be attached to Web Service Endpoints.
Associate the OAAM_WebServices_Group group with the authorization policy.
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL
http://weblogic-admin-hostname:port/em
Expand the WebLogic Domain.
Right-click the domain hosting OAAM Server, Web Services, and Policies.
Select oracle/binding_authorization_permitall_policy.
Click Edit, and then the Settings tab.
Select Selected Roles from Authorization Setting.
Click Add (plus sign) and move the OAAM_WebServices_Group group to Roles Selected To Add list, and then click OK. The group was created in Section I.5, "Creating User and Group."
Click Save to save the policy.
To make sure that above policy configuration is working as expected, set property active.protocol to remote. The value for the property can be checked by navigating to domain hosting OAAM Server, right clicking Web Services, Platform Policy Configuration, and Policy Accessor Properties.
Attach the authorization policy to the Web Service Endpoints.
Note: To get list of Web Service Endpoints exposed by OAAM Server on Enterprise Manager, go to Fusion Middleware Control, Identity and Access. Expand OAAM, then oaam_server, and right-click Web Services.
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL
http://weblogic-admin-hostname:port/em
Under weblogic_domain, select the domain and select oaam_server_server1 and right-click and select the Web Services option.
Click Attach Policies.
Select all the rows corresponding to OAAM Web Services and click the Next button
Select the row oracle/binding_authorization_permitall_policy.
Click the Next button.
Click the Attach button in the next page.
Restart OAAM Server if required.
Web Services/SOAP clients need to send the user name and password for successful communication with OAAM web services.
The password needs to be stored in a KeyStore for security.
To set up security for Native Client web services:
In the $ORACLE_HOME/oaam/cli directory, create a file, for example, soap_key.file, and enter the HTTP authentication user password in it. (The password from the user that was added to the OAAM Web Services Group role/group).
Copy sample.config_3des_input.properties to soap_3des_input.properties.
cp sample.config_3des_input.properties soap_3des_input.properties
Update soap_3des_input.properties with the keystore password, the alias password, and password file.
#This is the password for opening the keystore. keystorepasswd= #This is the password reading alias (key) in the keystore. For example, #Welcome1 keystorealiaspasswd= #File containing from key. Please note, keys in AES could be binary. #Also note algorithms like 3DES require minimum 24 characters in the key #keyFile=soap_key.file keyFile= keystorefilename=system_soap.keystore keystorealias=vcrypt.soap.call.passwd
Set ORACLE_MW_HOME and JAVA_HOME and source setCliEnv.sh.
Generate the keystore.
For Unix/Linux, run
$JAVA_EXE -Djava.security.policy=conf/jmx.policy -classpath $CLSPTH com.bharosa.vcrypt.common.util.KeyStoreUtil updateOrCreateKeyStore readFromFile=soap_3des_input.properties
For Windows, run
genkeystore.cmd soap_3des_input.properties
If the KeyStore command was successful, you will see output similar to the following:
updateOrCreateKeyStore done! Keystore file:system_soap.keystore,algorithm=DESede KeyStore Password=ZG92ZTEyMzQ= Alias Password=ZG92ZTEyMw==
Write down the Keystore password and Alias Password printed on the screen. You will need to add these to oaam_custom.properties.
Add the following properties with the encoded passwords (from step 5) and the authentication user name to oaam_custom.properties.
OAAM clients are configured to use this user name and password when invoking web services through the following oaam_custom.properties properties:
vcrypt.soap.auth.keystorePassword - Base64 encoded keystore password used to open the system_soap.keystore vcrypt.soap.auth.aliasPassword - Base64 encoded password to the alias used to retrieve the key stored in the keystore vcrypt.soap.auth.username - Username of the SOAP user configured for accessing the SOAP services vcrypt.soap.auth.keystoreFile - Filename of the keystore (should be system_soap.keystore)
Save the system_soap.keystore file in your source code control system. Ensure you take adequate security precaution while handling this file. The file contains critical password information. Ensure that only authorized personnel have read access to this file. If you lose it, Oracle Adaptive Access Manager will not be able to recover data that is encrypted.
Copy your system_soap.keystore to application/WEB-INF/classes (classpath of the native client deployment).
Delete both the soap_key.file and soap_3des_input.properties files.
Set the following properties in oaam_custom.properties of the native application:
Set the vcrypt.common.util.vcryptsoap.impl.classname property.
This setting specifies for the application which libraries to use when creating SOAP messages to exchange with the OAAM services.
The available option is:
com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
Set the vcrypt.tracker.soap.url property:
vcrypt.tracker.soap.url=http://host-name:port/oaam_server/services
This setting is the location of the web services with which the application will communicate.
For example,
vcrypt.tracker.soap.url=http://localhost:14300/oaam_server/services/
Set the vcrypt.soap.call.timeout property in milliseconds.
For example,
vcrypt.soap.call.timeout=10000
vcrypt.tracker.impl.classname= com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl vcrypt.user.image.dirlist.property.name=bharosa.image.dirlist bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl bharosa.config.load.impl.classname= com.bharosa.common.util.BharosaConfigLoadPropsImpl vcrypt.tracker.soap.useSOAPServer=true vcrypt.soap.disable=false vcrypt.soap.auth.keystoreFile=system_soap.keystore # Environment specific values need to be replaced below this line bharosa.image.dirlist=absolute_folder_path_where_oaam_images_are_available # If SOAP Authentication is enabled, then the following have to be set # otherwise just set the property vcrypt.soap.auth=false vcrypt.soap.auth=true vcrypt.soap.auth.keystorePassword=Java_keystore_password vcrypt.soap.auth.aliasPassword=Keystore_alias_password vcrypt.soap.auth.username=SOAP_User_name
The required JAR files for setting up the base environment in OAAM native SOAP integration are listed in this section. The following JAR files must be set in the JAVA classpath:
jps-api.jar
jps-common.jar
jps-internal.jar
You can enable or disable authentication using Oracle Web Services Manager (OWSM) policies through Oracle Enterprise Manager Fusion Middleware Control.
If you disable the SOAP Web Service authentication on the server (which is by default enabled), the client can use the web service without having been authenticated.
Log in to Oracle Enterprise Manager Fusion Middleware Control of the Identity Management domain using the URL http://<host-name>:7001/em and WebLogic Admin user name and password.
Locate oaam_server_server1 in the left hand side menu by expanding WebLogic Domain and the OAAM domain under it.
Right click the oaam_server_server1 and select the Web Services menu option.
Click the Oracle Infrastructure Web Services tab.
Click the Attach Policies link in the top-right area of the page.
Select all the rows related to the OAAM Web services in the next page and click the Next button.
Select the rows oracle/no_authentication_service_policy and oracle/no_authorization_service_policy and click the Next button.
Click the Attach button in the next page.
Restart OAAM Server if required.