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.

Introduction

One of the first things you must do in setting up your Network 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 Network Gatekeeper’s interactions with Application Service Providers. MBean security controls who can have access to the Runtime MBean Server within your WLS 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, Network 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.

Network Gatekeeper uses a WebLogic Server mechanism for Web Services Security -WSSE policies:

WebLogic Web Services: Security
http://download.oracle.com/docs/cd/E13222_01/wls/docs100/webserv_sec/index.html
Understanding WebLogic Security http://download.oracle.com/docs/cd/E13222_01/wls/docs100/secintro/concepts.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 Network Gatekeeper.

Note:

By default, Network 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 http://download.oracle.com/docs/cd/E13222_01/wls/docs100/ConsoleHelp/taskhelp/webservices/ConfigureWSPolicyFile.html for a full desccription.

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 <beahome>/domains/<wlng-domain>/./servers/WLNG_AT1/stage/wlng_at/plan/Plan.xml (For a single instance development machine, substitute your server name for WLNG_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 Network 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 Network 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/WLNG_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 13-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 follow the instructions in http://download.oracle.com/docs/cd/E13222_01/wls/docs100/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 Network 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 by following the instructions in http://download.oracle.com/docs/cd/E13222_01/wls/docs100/ConsoleHelp/taskhelp/webservices/webservicesecurity/UsePasswordDigest.html.
Create a custom ws-policy xml file for the password digest. See example Listing 13-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 13-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. Network 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 Network Gatekeeper up the first time. Certain configuration values are cached on start up. So, for example, if you started Network 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 13-3 and Listing 13-4 for before and after snippets.

Listing 13-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 13-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 Network Gatekeeper, you should now re-deploy the EAR file using the Management Console.

Create and use custom a custom WS-Policy

Section Creating and Using a Custom WS-Policy File in http://download.oracle.com/docs/cd/E13222_01/wls/docs100/webserv_sec/message.html describes how to create and use a custom WS-Policy file. Also see http://download.oracle.com/docs/cd/E13222_01/wls/docs100/ConsoleHelp/taskhelp/webservices/ConfigureWSPolicyFile.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 Network 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.

See http://download.oracle.com/docs/cd/E13222_01/wls/docs100/webserv_sec/message.html for a description.

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 WebLogic Network 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 Network 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 the WLS Console to do this, as described in Create JMX Policies. 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. Network Gatekeeper uses the standard WebLogic Server mechanisms for doing this.See Securing WebLogic Resources Using Roles and Policies, particularly the chapters “Using XACML Documents to Secure WebLogic Resources” and “Reference for XACML on WebLogic Server” for a detailed description of the process. 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.