16 Securing Web Services and OAM MBeans

This chapter describes enabling authentication settings for REST- and SOAP-based Web services and for securing the Oracle Access Manager (OAM) MBeans in Oracle Communications Services Gatekeeper (Services Gatekeeper).

Introduction

One of the first things you must do in setting up your Services Gatekeeper implementation is decide how to protect your Web service communication and OAM MBeans.

For more information about Services Gatekeeper security and how these tasks help to create a secure Services Gatekeeper implementation, see Oracle Communications Services Gatekeeper Security Guide.

Understanding Web Services Security

Web service security controls the network traffic between Services Gatekeeper and applications and network nodes it communicates with. By default, Oracle Communications Services Gatekeeper is preconfigured to send credentials in clear text and this is enforced only for inbound traffic. Outbound security is not enabled because there is no way for Services Gatekeeper to know what security policies may be required by a client. Of course, as soon as you find out what your clients require you should set up that level of security.

Oracle recommends that for production implementations you fully secure Web services using the instruction in one of these sections of the Oracle Communications Services Gatekeeper System Administrator's Guide, depending on the Web interface you use:

• Securing SOAP-Based Web Services with WS-Security

• Securing RESTful Web Services with SSL

• "Securing Network-Facing Servers With Keystores"

You probably want to secure client (outbound) traffic and require digest authentication (encrypted credentials) for all traffic. Applying a security policy (WS-Security) to a Web Service establishes, both inbound and outbound security policies. If you wish to secure the link by which Oracle Communications Services Gatekeeper returns notifications, you should use Secure Sockets Layer (SSL).

Understanding OAM MBean Security

MBean security controls who is authorized to modify the runtime MBean Server within your WebLogic Server installation, the mechanism that allows OAM procedures to be performed.

Oracle recommends that you secure the OAM MBeans using the instructions in "Securing the Oracle Access Manager MBeans".

Securing SOAP-Based Web Services with WS-Security

SOAP-based security provides end-to-end message-level security for Web services through an implementation of the WS-Security standard.

WS-Security defines a mechanism that offers three levels of security to SOAP messages:

• Authentication tokens (username token). The digest authentication version of authentication tokens is the default SOAP-based communication security setting. WS-Security authentication tokens let an application provide a user name and password or X509 certificate for the purpose of authentication headers. With additional setup, Security Assertion Markup Language (SAML) can also be used for authentication.

  SOAP-based communication with the Partner Relationship Manager uses this security by default. However you need to configure other web services to use this strategy. See "Setting up UsernameToken with Password Digest" of the Oracle Communications Services Gatekeeper System Administrator's Guide for instructions.

• XML encryption (SAML tokens). WS-Security's use of W3C's XML encryption standard enables the XML body or portion of it to be encrypted to ensure message confidentiality.

  To set up SAML token security, configure the WebLogic SAML Identity Assertion Provider, which authenticates users based on SAML assertions and SAML credential mapping provider. The SAML Identity Assertion Provider is required only if you are using SAML assertions. See Oracle Fusion Middleware Security and Administrator's Guide for Web Services for details at: http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/weblogic.htm

• XML digital signatures (X.509 certificate tokens). WS-Security's use of W3C's XML digital signatures lets the message be digitally signed to ensure message integrity. The signature is based on the content of the message itself (by applying the hash function and public key), so if the message is altered en route, the signature becomes invalid. See "Setting up UsernameToken with X.509" of the Oracle Communications Services Gatekeeper System Administrator's Guide for instructions.

Services Gatekeeper uses a WebLogic Server mechanism for Web Services Security - WSSE (Web Services Security Environment) policies:

• “Securing and Administering WebLogic Web Services” in Oracle Fusion Middleware Security and Administrator's Guide for Web Services at: http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/weblogic.htm

• “Understanding Oracle WSM Policy Framework” in Oracle Fusion Middleware Security and Administrator's Guide for Web Services at: http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/toc.htm

• Web Services Security specifications http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss

Authentication is handled transparently by WS-Security and subsequently by the configured authentication providers and login modules of the WebLogic Security framework. WS-Security also supports signing and encrypting a message by providing a security token hierarchy associated with the keys used for signing and encryption (for message integrity and confidentiality).

Setting up UsernameToken with Password Digest

To apply a WSSE policy of the type UsernameToken with Digest to a Web Service endpoint in Oracle Communications Services Gatekeeper from the Administration Console:

1. Start the Administration Console

2. Enable digest authentication:

   1. Click Providers.

   2. Click Authentication.

   3. Select the WLNG Application Identity Asserter checkbox.

   4. Click the WLNG Application Identity Asserter link.

      The Settings for WLNG Application Identity Asserter window appears.

   5. Under Active Types: move wssePasswordDigest from Available: to Chosen: using the left arrow icon.

   6. Click Save.

3. Create a custom ws-policy.xml file for the password digest. See Example 16-1 for an example.

4. For every Web Service:

   1. Put a copy of the custom ws-policy.xml file in the WEB-INF/policies directory of the WAR file for the Web Service.

   2. Edit the WEB-INF/policies/weblogic-webservices-policy.xml file replacing the old wsl-policy file with policy:UsernameTokenDigestPolicy.xml.

   3. Repackage and redeploy these files.

   4. Edit the deployment plan, plan.xml, to indicate inbound only for entry WsPolicy_policy: UsernameTokenDigestPolicy.xml in plan.xml.

Example 16-1 Username Token with digest custom policy example (UsernameTokenDigestPolicy.xml)

<?xml version="1.0"?>
<!-- WS-SecurityPolicy -->
<wsp:Policy
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wssp="http://www.bea.com/wls90/security/policy"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
  xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
  >
  <!-- Identity Assertion -->
  <wssp:Identity>
    <wssp:SupportedTokens>
      <!-- Use UsernameToken for authentication --> 
      <wssp:SecurityToken IncludeInMessage="true" 
        TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken">
        <wssp:UsePassword 
         Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"/>
      </wssp:SecurityToken>
    </wssp:SupportedTokens>
  </wssp:Identity>
</wsp:Policy>

Setting up UsernameToken with X.509

This section outlines how to set up WSSE with X.509, configure the default identity asserter, and configure the keystore.

To set up UsernameToken with X.509 from the Administration Console:

1. Select Security Realms from the Domain Structure menu for the domain you want to configure.

2. Select myrealm.

   The settings for myrealm appear.

3. Click the Providers tab.

   The list of authentication providers appears.

4. Click the DefaultIdentityAsserter provider in the table.

   The settings for DefaultIdentityAsserter appear.

5. Click the Common tab.

6. Under Active types, move X.509 from the Available list to the Chosen list if it is not there already.

7. Click the Provider Specific tab.

8. Set the Default User Name Mapper Attribute Type is to CN if it is not set to CN already.

To configure the keystore:

1. Select Environment from the Domain Structure menu.

   A summary of the environment appears.

2. Select Servers.

   A summary of servers appears.

3. Click AdminServer.

   The settings for the AdminServer appear.

4. Click the Keystores tab. The keystore settings appear.

5. Configure the Identity and Trust sections of the keystore form. See “Configuring Identity and Trust“ in Oracle Fusion Middleware Securing Oracle WebLogic Server at

   http://download.oracle.com/docs/cd/E15523_01/web.1111/e13707/toc.htm

   for information about setting the keystore values.

6. Click Save to save your configuration.

Removing Outbound Web Security

To turn off outbound security associated with a particular WS-Policy file, you must edit the plan.xml file that is created when you attach Policy to a Web Service, as in step 8 above. The default location is: /domain_home/wlng-access-network-domain/servers/AT1/stage/wlng_at/plan/Plan.xml, but your location may be different. Make sure the value element is set to inbound as in the following example:

<variable>
      <name>WsPolicy_policy:Auth.xml_Direction_11745107731400</name>
      <value>inbound</value>
</variable>

Removing WS-Policy from a Web Service

Services Gatekeeper 2.2 and earlier use a different mode of authentication than the WS-Security model. Oracle Communications Services Gatekeeper can be configured to support applications designed to work using the older model, but the WS-Policy that is configured by default must be removed.

Note:

The easiest way to do this is to make these changes before you start Oracle Communications Services Gatekeeper for the first time. Certain configuration values are cached on start up. So, for example, if you started Oracle Communications Services Gatekeeper during the post-install phase to set up additional JMS Servers, you need to redeploy the wlng_at.ear file after you have made your changes.

To remove the policy files from a Web Service:

1. Expand the EAR file for the Access Tier part of the communication service.

2. Expand the war file for the Web Service in question.

3. Modify the weblogic-webservices-policy.xml file for that Web Service to remove the policy entries. In the following example, this would involve deleting the <port-policy> element.

   Note:

   See Example 16-2 and Example 16-3 for before and after snippets.

Example 16-2 weblogic-webservices-policy.xml with policy entries

<?xml version='1.0' encoding='UTF-8'?>
<webservice-policy-ref xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<port-policy>
  <port-name>AudioCall</port-name>
  <ws-policy>
   <uri>policy:Auth.xml</uri>
   <direction>inbound</direction>
  </ws-policy>
</port-policy>
</webservice-policy-ref>

Example 16-3 weblogic-webservices-policy.xml with policy entries removed

<?xml version='1.0' encoding='UTF-8'?>
<webservice-policy-ref xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></webservice-policy-ref>

1. Re-package the war file with the modified weblogic-webservices-policy.xml file

2. Re-package the ear file.

3. Copy the modified ear file to the domain directory of the Administration Server.

4. If you have previously run Oracle Communications Services Gatekeeper, you should now re-deploy the EAR file using the Administration Console.

Create and use a custom WS-Policy

For information about creating and using a custom policy file for message-level security, the discussion on securing Web services in Oracle® Fusion Middleware Security and Administrator's Guide for Web Services at:

http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/toc.htm

There is also information about this in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at:

http://download.oracle.com/docs/cd/E15523_01/apirefs.1111/e13952/core/index.html

Available default WS-Policies

WS-Policy files can be used to require applications clients to authenticate, digitally encrypt, or digitally sign SOAP messages. By default, Oracle Communications Services Gatekeeper supplies these policy files: auth.xml, encrypt.xml, sign.xml, and UsernameTokenDigestPolicy.xml. If the built-in WS-Policy files do not meet your security needs, you can build custom policies.

WS-Policy assertions are used to specify a Web Service requirement for digital signatures and encryption, along with the security algorithms and authentication mechanisms that it requires; for example, Policy for SAML.

Securing RESTful Web Services with SSL

Services Gatekeeper uses SSL authentication to secure REST-based Web services. You have the options listed in Table 16-1 for security levels.

Table 16-1 SSL Security Options

SSL Level	Client Response Setting	Notes
One-Way	Client certificates not required	Essentially no security. Only use in a test and evaluation implementation.
Two-Way	Client certificates requested but not enforced.	The default setting. Appropriate for a test and evaluation system. A client certificate is requested but if one is not returned, the session continues normally.
Two-Way	Client certificates requested and enforced.	The most secure setting; appropriate for most production implementations. A client certificate is requested and if one is not returned the session is terminated.

Table 16-2 lists the default keystore and truststore name and locations. If you are configuring a test and evaluation implementation it is acceptable to use these values. If you are configuring a production implementation, replace these values with settings that you create.

Table 16-2 Default SSL Truststore and Keystore Values

Default Credential	Default Value
Demo identity keystore location	Oracle_home/Middleware/wlserver_10.3/server/lib/DemoIdentity.jks
Demo identity keystore password	DemoIdentityKeyStorePassPhrase
Demo identity keystore (private key) password	DemoIdentityKeyStorePassPhrase
Default trust keystore location	Oracle_home/Middleware/wlserver_10.3/server/lib/DemoTrust.jks
Default trust keystore password	DemoTrustKeyStorePassPhrase

The following section explain how to configure SSL security for the REST-based Web services.

Configuring Application-Facing Servers for SSL

Follow the instructions in the following sections of the Oracle Communications Services Gatekeeper System Administrator's Guide to set up and configure SSL security for RESTful communication between Services Gatekeeper and external applications:

• Enable and Configure SSL for Each Application Tier Server

• Add Certificates to the Application Tier Servers and Applications

Enable and Configure SSL for Each Application Tier Server

To enable SSL, perform these steps on each of your application tiers that use RESTful communication:

1. Open the WebLogic Server Administration Console.

2. Click Lock and Edit.

3. Navigate to Environment, then Servers, then AT_server_name, then the Configuration tap, then the General subtab.

4. Check the SSL Listen Port Enabled checkbox.

5. Set the SSL Listen Port: number to 7002.

6. Navigate to the Keystores subtab.

7. If you are setting up a production environment, change these settings to values that you create. You can use the default values (listed in Table 16-2 for test and evaluation implementations:

   1. Keystores; Click Change.

   2. Demo Identity Keystore: - Change this to different location that you have created.

   3. Demo Identity Keystore Passphrase: - Change this to a secure password that you create.

   4. Demo Trust Keystore: - Change this to a location that you have created.

   5. Demo Trust KeyStore Pass phrase: - Change this to a secure password the you create.

8. Navigate to the SSL

9. If you are setting up a production environment, change these settings to values that you create. You can use the default values (listed in Table 16-2 for test and evaluation implementations:

   1. Identity and Trust Location:; Click Change.

   2. Private key Passphrase - Change this to a secure password that you choose.

   3. Two Way Client Cert Behavior: - See Table 16-1 for the possible values. Select the value appropriate for your implementation.

10. Click Release Configuration.

Add Certificates to the Application Tier Servers and Applications

Once you have configured SSL and key- and truststores for each application-facing server, you need to create a file of trust certificates to import into the client keystore and truststore locations.

1. Open a shell on the Services Gatekeeper server.

2. Change directory to the location of your trust store. You set this with the directions in the "Enable and Configure SSL for Each Application Tier Server" section of the Oracle Communications Services Gatekeeper System Administrator's Guide. The default directory is Oracle_home/Middleware/wlserver_10.3/server/lib

3. (Optional) List the credentials to confirm that they are correct with the following command. The default values for keystore_name and:

   keytool -list -v -storetype JKS -keystore keystore_name.jks -storepass keystore_password
   

4. Export the certificates from the Services Gatekeeper keystore into a file with this command:

   keytool -exportcert -v -storetype JKS -keystore keystore_file.jks -storepass keystore_password -alias nt1-cacert -rfc -file SG_trust_cacert_file.cer
   

   Where:

   keystore_file.jks is the Services Gatekeeper keystore file you set in "Enable and Configure SSL for Each Application Tier Server" of the Oracle Communications Services Gatekeeper System Administrator's Guide.

   keystore_password is the keystore password you created in "Enable and Configure SSL for Each Application Tier Server" of the Oracle Communications Services Gatekeeper System Administrator's Guide.

   SG_trust_cacert_file.cer is the Services Gatekeeper truststore certificate file.

   This command exports the keystores into a file called export_file.cer that you use to import certificates into the Services Gatekeeper trust store.

5. Import SG_trust_cacert_file.cer into the client application's keystore. See your application product documentation for details. Do this for each server communicating with Services Gatekeeper.

6. Obtain your client application's truststore certificate file. See your client application or client server documentation for details. You need the truststore certificate file with the .cer file extension.

7. Change directory to the location of your keystore. You set this with in the Oracle Communications Services Gatekeeper System Administrator's Guide section "Enable and Configure SSL for Each Application Tier Server" tasks. The default directory is Oracle_home/Middleware/wlserver_10.3/server/lib

8. Import your client application's certificates into the Service Gatekeeper truststore with this command:

   keytool -importcert -v -alias client-cacert -file client_cacert_file.cer -storetype JKS -keystore truststore_file.jks  -storepass truststore_password 
   

   Where:

   client_cacert_file.cer is the client truststore certificates file.

   truststore_file.jks is the Services Gatekeeper truststore file you set in "Enable and Configure SSL for Each Application Tier Server" of the Oracle Communications Services Gatekeeper System Administrator's Guide.

   truststore_password is the truststore password you created in "Enable and Configure SSL for Each Application Tier Server" of the Oracle Communications Services Gatekeeper System Administrator's Guide.

Securing Network-Facing Servers With Keystores

To secure RESTful Web service traffic with network-facing servers, you need to:

• Import the network node server certificates into Services Gatekeeper keystore as trusted entries,

• Export your Services Gatekeeper keystores into the network node server.

To secure RESTful traffic, you must first know the location of the network server certificate file (keystore_cacert_file.cer) that you created in "Add Certificates to the Application Tier Servers and Applications" of the Oracle Communications Services Gatekeeper System Administrator's Guide.

To secure network-facing traffic:

1. Open a shell on the Services Gatekeeper server.

2. Change directory to the location of your Services Gatekeeper keystore. You set this in the Oracle Communications Services Gatekeeper System Administrator's Guide section "Enable and Configure SSL for Each Application Tier Server" tasks. The default directory is Oracle_home/Middleware/wlserver_10.3/server/lib.

3. Import the network server keystore credentials, generate a public/private key pair, and create a keystore file with this command:

   keytool -genkeypair -v -alias key_pair -keyalg RSA -storetype JKS 
   -validity 3650 -keystore keystore_file.jks -dname "domain_name"  -storepass public_key_password -keypass private_key_password
   

   Where:

   key_pair is the name of the public/private key pair.

   public_key_password is the public key for the public/private key pair.

   keystore_file.jks is the Services Gatekeeper Java keystore file accepting the keystore credentials that is created with this command.

   domain_name is the distinguished name of the network node credential key, for example: “CN=oracle-wac-gw-nt1,OU=CGBU,O=Oracle,L=ANY,C=US”.

   private_key_password is the private key of the public/private key pair.

4. Import the Services Gatekeeper keystore credentials into the network node server with this command:

   keytool -exportcert -v -alias key_pair -keystore keystore_file.jks
   -storetype JKS -storepass public_key_password -rfc -file cacert_file.cer
   

   Where:

   key_pair is the name of the public/private key pair.

   keystore_file.jks is the Services Gatekeeper keystore file to import.

   public_key_password is the public key password for the certificates.

   cacert_file.cer is the certificate file that is created by this command.

5. Start the Administration Console (or another MBean browser) and navigate to the MBeans tab.

6. Click Lock and Edit.

7. Check the Display: tree checkbox.

8. Navigate to wlng, then RESTfulClientSSL.

9. Edit these fields to direct Services Gatekeeper to use the keystores you have imported:

   • KeyStoreFile: - The location of the keystore_file.jks file you imported in step 3.

   • KeyStorePassPhrase: - The publk_key_password you used in step 3.

   • KeyStoreType: - Enter JKS.

   • PrivateKeyPhrase: - the private_key_password that you created in step 3.

10. Click Save.

11. Click Activate Changes.

Securing the Oracle Access Manager MBeans

The Java Management Extension (JMX) OAM MBeans control access to the Services Gatekeeper OAM functionality. You can change these MBean settings using the Administration Console or through an external mechanism. Access to these MBeans are controlled by JMX Policy, which associates administrative user groups with access privilege levels. By default any administrative user can access and change the Services Gatekeeper OAM MBeans. You may want use the instructions in this section to add more restrictive access control to prevent inadvertent or malicious changes to these MBeans. However, the decision should be based on your implementation's security policies.

Administrative Groups

Administrative users and groups are set up as described in the Oracle Communications Services Gatekeeper System Administrator's Guide section "Managing Management Users and Management User Groups". To control how these users have access to MBeans, and thus OAM functionality, you must assign JMX Policy to these user groups. You use WebLogic Server Administration Console to do this. For details see the discussion on create JMX policies in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at:

http://download.oracle.com/docs/cd/E15523_01/apirefs.1111/e13952/core/index.html

Each policy can do the following:

• Control read access for all an MBean's attributes or for specific attributes that you select.

• Control write access for all an MBean's attributes or for specific attributes that you select.

• Control invoke access for all an MBean's operations or for specific operations that you select.

For example, to give a user complete access to an MBean, select the WLNG_Administrator's Group in the policy condition.

Administrative Service Groups

In addition to controlling access to OAM functionality in a general way – ReadOnly, ReadWrite, and so on – you may also wish to control access by Service group. So, for example, if you have users whose job is limited to setting up and managing Application Service Providers through a system using the Partner Relationship Management interfaces, you might want to give them, and only them, ReadWrite privileges, but only to a subset of the available MBeans, those having to do with the operator part of those transactions. To do this, you have to create custom XACML policies to attach to these subsets. Oracle Communications Services Gatekeeper uses the standard WebLogic Server mechanisms for this purpose. For the basic process you must:

• Determine the special identifier (called the resourceId) for each MBean.

• Create an XACML policy for a security role.

• Specify one or more Rule elements that define which users, groups, or roles belong to the new security role.

• Attach this role to the MBean by way of the resourceId.

For details on using XACML documents to secure WebLogic resources, see “Using XACML Documents to Secure WebLogic Resources” in Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server at:

http://download.oracle.com/docs/cd/E15523_01/web.1111/e13747/xacmlref.htm

For a reference for XACML on WebLogic Server, see “A Reference for XACML on WebLogic Server” in Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server at:

http://download.oracle.com/docs/cd/E15523_01/web.1111/e13747/xacmlref.htm