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

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.

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.

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

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.

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.

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