System Administrator’s Guide

Setting up WS-Policy and JMX Policy

The following section 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’s 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 done.

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 lets an application provide a user name and password or X509 certificate for the purpose of authentication headers. With additional setup, SAML can also be used for authentication.

Note:

Out of the box, Oracle Communications Services Gatekeeper is pre-configured 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 policies:

Oracle WebLogic Server Securing WebLogic Web Services http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_sec/index.html
Oracle WebLogic Server Understanding WebLogic Security http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secintro/index.html
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 pre-configured to use the 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.

Starting in WebLogic Console:

In the Domain Structure pane, select Deployments, and Summary of Deployments tab.
Expand the Access Tier part of the communication service, for example wlng_at_audio_call_px30
Click on 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.

This shows the page Settings for <Web Service>

Click the Configuration tab.
Click WS-Policy sub-tab.
Click Service endpoint <Web Service>.
Choose which security policy to apply to the endpoint:

Select the appropriate WS-Policy file in Available Endpoint Policies, see Available default WS-Policies.
Move it to the list in Chosen Endpoint Policies by clicking on the arrow button.
When the WS-Policy files have been chosen, click OK.

In the Save Deployment Plan Assistant you have the choice of where to store the deployment plan. You should choose $DOMAIN_HOME/servers/AT1/stage/wlng_at/plan/Plan.xml (For a single instance development machine, substitute your server name for AT1)
Apply the changes.

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 SSL.

Note: 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 stanza:

Listing 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 setting up WSSE with X.509.

Starting in WebLogic Console:

Configure the credential provider for X.509:

Selecting wlng-domain Web Service Security tab

Configure the default identity asserter:.

Select Security Realms myrealm Providers DefaultIdentityAsserter
Select the Common tab. Make sure that X.509 is selected under the Chosen list in Active types.
Select the Provider Specific tab. Make sure Default User Name Mapper Attribute Type is set to CN.

Configure the keystore:

Select Environment Servers <AdminServer>.
Select Configuration Keystores
Decide which type of keystore to use, and configure identity and trust accordingly. See Oracle WebLogic Server Securing WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secmanage/identity_trust.html.

Setting up UsernameToken with Password Digest: Quick reference

This section outlines how to apply a WSSE policy of the type UsernameToken with Digest to a Web Service endpoint in Oracle Communications Services Gatekeeper.

Starting in the Administrative Console:

Configure Default Identity Asserter.

Select Security realms my realmproviderDefault IdentityAsserter
Add wsse.PasswordDigest as the active token type.
Modify the data source Name (if not wlng.datasource)

Configure digest authentication. See the Oracle WebLogic management console on-line help at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/core/index.html for instructions on how to use a password digest in SOAP messages.
Create a custom ws-policy xml file for the password digest. See example Listing 16-2 for an example.
For every Web Service:

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

Listing 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

Network Gatekeeper 2.2 and earlier used 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 out of the box 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 in order to set up additional JMS Servers, you will need to redeploy the wlng_at.ear file after you have made your changes.

To remove the policy files from a Web Service:

Explode the EAR file for the Access Tier part of the communication service.
Unjar 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.

Note:

See Listing 16-3 and Listing 16-4 for before and after snippets.

Listing 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>

Listing 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 Management Console.

Create and use custom a custom WS-Policy

For information about creating and using a custom policy file for message-level security, see Oracle WebLogic Server Securing WebLogic Web Services at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_sec.

There is also information about this in the on-line help for Weblogic Server Management Console at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/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. Out-of-the-box 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 Services’ requirements 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 on-line help for the Administration Console at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/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 doing this. 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.

WebLogic Server Securing WebLogic Resources Using Roles and Policies at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secwlres/index.html contains details on how to use XACML documents to secure WebLogic resources and a reference for XACML on WebLogic Server.