16 Setting up WS-Policy and JMX Policy

This chapter describes enabling security settings for Web Services and for OAM MBeans in Oracle Communications Services Gatekeeper.

Introduction

One of the first things you must do in setting up your Oracle Communications Services Gatekeeper installation is to make decisions about two key forms of security for your installation: Web Services security and MBean security. Web Services security controls Oracle Communications Services Gatekeeper interactions with applications. MBean security controls who can have access to the Runtime MBean Server within your WebLogic Server installation, the mechanism that allows OAM procedures to be performed.

Web Services Security
JMX Policy

Web Services Security

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

WS-Security defines a mechanism for adding three levels of security to SOAP messages:

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

Note:
By default, Oracle Communications Services Gatekeeper is preconfigured to use user name/password authentication.
XML encryption. 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.
XML digital signatures. 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.

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

The following steps outline the general WebLogic security configurations that can be performed, either automatically using a script or manually from the Administration Console.

For SAML tokens only: configure 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.
Configure Policies for WS-Security as described below.

Configuration workflow: WS-Policy

This section outlines how to apply an existing WS-Policy and where to find more information on creating and using custom WS-Policies.

Apply WS-Policy to a Web Service: Quick start

This section outlines how to apply a WSSE policy to a Web Service endpoint in Oracle Communications Services Gatekeeper.

Note:

By default, Oracle Communications Services Gatekeeper is preconfigured to use WS-Security with UsernameToken. It is also set up to require this authentication only for inbound traffic. The following description is provided in case this particular mechanism does not cover the needs of your installation.

Standard WebLogic Server mechanisms are used. See the on-line help for the WebLogic Server administration console for a full description of how to associate a WS-Policy file with a Web Service.

To apply WS Policy to a web service from the Administration console:

In the Domain Structure pane, select Deployments.

The Summary of Deployments pane appears.
Expand the Access Tier part of the communication service; for example, wlng_at_audio_call_px30
Select a Web Service on which you wish to apply Web Services security: for example, com.bea.wlcp.wlng.px30.jws.AudioCallPlayMediaWsImpl. All Web Services are named according to the interface they implement.

The Settings for Web Service pane appears.
Click the Configuration tab.

The WS-Policy Files Associated With This Web Service list appears.
Click the WS-Policy sub-tab.
Select a policy file from the list.

The Configure a WS-Policy File for a Web Service Endpoint pane appears.
Select which security policy to apply to the endpoint:
1. Select the appropriate WS-Policy file in Available Endpoint Policies: see "Available default WS-Policies".
2. Move it to the Chosen Endpoint Policies list by clicking the arrow button.
3. After choosing the WS-Policy files, click OK.
  
  The Save Deployment Plan Assistant pane appears.
Enter the following path for the location at which to store the deployment plan: Domain_Home/servers/AT1/stage/wlng_at/plan/Plan.xml (For a single-instance development machine, substitute your server name for AT1.)
Click OK.

Note:
Applying a security policy to a Web Service establishes, by default, both inbound and outbound security policies. Because there is no way for Oracle Communications Services Gatekeeper to know what security policies may be required by a client to which it is returning a notification, outbound security must be turned off. If you wish to secure the link by which Oracle Communications Services Gatekeeper returns notifications, you should use Secure Sockets Layer (SSL).
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: /domains/wlng-access-network-domain/servers/AT1/stage/wlng_at/plan/Plan.xml, but your location may vary. Make sure the value element is set to inbound as in the following example:

Example 16-1 Plan.xml snippet to be edited

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

Setting up UsernameToken with X.509: Quick reference

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:

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

The settings for myrealm appear.
Click the Providers tab.

The list of authentication providers appears.
Click the DefaultIdentityAsserter provider in the table.

The settings for DefaultIdentityAsserter appear.
Click the Common tab.
Under Active types, move X.509 from the Available list to the Chosen list if it is not there already.
Click the Provider Specific tab.
Set the Default User Name Mapper Attribute Type is to CN if it is not set to CN already.

To configure the keystore:

Select Environment from the Domain Structure menu.

A summary of the environment appears.
Select Servers.

A summary of servers appears.
Click AdminServer.

The settings for the AdminServer appear.
Click the Keystores tab. The keystore settings appear.
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.
Click Save to save your configuration.

Setting up UsernameToken with Password Digest: Quick reference

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:

Configure the Default Identity Asserter:
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 wsse.PasswordDigest from the Available list to the Chosen list if it is not there already.
7. Modify the data source Name if it is not wlng.datasource.
  
  You can view the data source Name from the Home Page of the Domain by selecting JDBC > Data Sources. You can modify the data source name by clicking it and entering a Name in the JNDI Name text field.
Configure digest authentication. For details on how to use a password digest in SOAP, see "Use a Password Digest in SOAP" 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
Create a custom ws-policy xml file for the password digest. See Example 16-2 for an example.
For every Web Service:
1. Put the custom ws-policy.xml file in the WEB-INF/policies directory of the WAR file for the Web Service. Repackage it and redeploy it.
2. Add the custom policy for password digest by following the instructions in "Apply WS-Policy to a Web Service: Quick start":
  
  Use the WS-Policy file WsPolicy:UsernameTokenDigestPolicy.xml
  
  Edit the deployment plan, plan.xml, to indicate inbound only for entry WsPolicy_policy: UsernameTokenDigestPolicy.xml in plan.xml

Example 16-2 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>

Remove 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:

Expand the EAR file for the Access Tier part of the communication service.
Expand the war file for the Web Service in question.
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-3 and Example 16-4 for before and after snippets.

Example 16-3 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-4 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>

Re-package the war file with the modified weblogic-webservices-policy.xml file
Re-package the ear file.
Copy the modified ear file to the domain directory of the Administration Server.
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, see "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 files to do those three things, respectively: auth.xml, encrypt.xml, and sign.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.

JMX Policy

Access to the OAM functionality of Oracle Communications Services Gatekeeper, both through the Console and through external mechanisms, is made using Java Management Extension (JMX) MBeans. Access to these MBeans is controlled by JMX Policy, which associates administrative user groups with access privilege levels. When Oracle Communications Services Gatekeeper is installed, there are no controls established by default on access to the OAM MBeans. Each installation must make decisions about access based on its own needs.

Administrative Groups

Administrative users and groups are set up as described in "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, as described in the "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 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, etc. – 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 on how to use 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