Using XACML Documents to Secure WebLogic Resources

7 Using XACML Documents to Secure WebLogic Resources

Learn how to use the eXtensible Access Control Markup Language (XACML), an XML language for expressing authorization policies and role assignments, to secure WebLogic resources. You can create roles and policies in an XACML document and then use the WebLogic Scripting Tool (WLST) to add them to your security realm. This is useful if you need to create security roles or policies that are more complex than can be created with the , or if you are required to use a standard language. You can also export your realm's roles and policies to a XACML document and then import the document in other WebLogic Server realms.

This chapter includes the following sections:

Note:

Always create a backup of a domain before you load XACML documents into a security realm. If you make a typographical or other type of error in an attribute description, you can cause the XACML provider to evaluate your realm's roles and policies as indeterminate, which locks all users (including the administrative user) out of the domain. See Caution: Indeterminate Results Can Lock Out All Users.

The WebLogic Server XACML Authorization Provider and the WebLogic Server XACML Role Mapping Provider implement the XACML 2.0 Core Specification, available at http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf.

Prerequisites

Note the following prerequisites for using XACML documents to secure WebLogic resources:

To add XACML authorization policies to a security realm, the realm must use either the WebLogic Server XACML Authorization Provider or a third party authorization provider that implements the weblogic.management.security.authorization.PolicyStoreMBean interface.
To add XACML role assignments to a security realm, the realm must use either the WebLogic Server XACML Role Mapping Provider or a third party authorization provider that implements the weblogic.management.security.authorization.PolicyStoreMBean interface.
To secure a resource with a XACML authorization or role policy, you need the resource identifier (ID). Because WebLogic Server creates an immutable, unique ID when you deploy or create a resource, you must deploy the resource before creating a policy for it.
To secure an EJB or Web application, you must deploy using the Custom Roles or Custom Roles and Policies security model. You cannot use a XACML document to create roles and policies for an EJB or Web application that you have deployed using the Deployment Descriptor Only security model. See xacmlusing.html.

Adding a XACML Role or Policy to a Realm: Main Steps

You can create a XACML document that describes roles and policies and then use the WebLogic Scripting Tool to add the policy or role to your security realm.

The main steps for this process are as follows:

Caution: Indeterminate Results Can Lock Out All Users

The XACML specification requires that if the decision engine is unable to process a decision point, the engine returns a result of indeterminate. Depending on the combining algorithms that you use for a decision point and its associated decision points, an indeterminate result can propagate to the top of the decision and cause the provider to deny access to all requests.

For example, the following attribute specifies MustBePresent='true' and contains a spelling mistake (ancester instead of ancestor). It will evaluate as indeterminate and will cause the security provider to deny access:

<ResourceAttributeDesignator
    AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-ancester"
    DataType="http://www.w3.org/2001/XMLSchema#string"
    MustBePresent="true"/>

Determine Which Resource to Secure

WebLogic Server organizes its resources into a hierarchy. If you use the or a Jakarta EE deployment descriptor (instead of a XACML document) to secure WebLogic resources, policies that you create on resources that are higher in the hierarchy act as default policies for resources lower in the same hierarchy. Policies lower in a hierarchy always override policies higher in the hierarchy.

Your XACML document can encode this hierarchical protection scheme, though XACML's hierarchical model differs slightly from WebLogic Server. See Comparison of WebLogic Server and XACML Security Models.

Get the ID of the Resource to Secure

WebLogic Server creates an immutable, unique identifier (ID) when you deploy or create a resource, and your XACML document must include a resource identifier that specifies the WebLogic Server ID.

To find the ID that WebLogic Server has assigned to a resource:

Enable security auditing for your realm by configuring an Auditing provider.

See Configure an Auditing Provider in Oracle WebLogic Remote Console Online Help. Take note of the location in which the Auditing provider saves its log files (by default, in the server's logs directory).
Deploy or create the resource.
Send a request from an external client to the resource.

For example, use a Web Service client to invoke a Web Service method that you want to secure.This will trigger an event that causes the Auditing provider to generate a message for the resource.

Note:

The Web Service client needs to authenticate itself before it can be granted access to the Weblogic resource that is secured by the roles and policies specified in the XACML document.

Open the log file for the Auditing provider and find the entry for the event that you triggered.

For example, if you configure the WebLogic Server Default Auditor to generate messages for severity level INFORMATION and higher, when you invoke the sayHello method from a Web Service named SimpleSoapPort, the audit log contains the following entries, one from the Role Mapping provider and the other from the Authorization provider:

#### Audit Record Begin <Mar 30, 2006 9:24:12 AM>  
<Severity =INFORMATION>  
<<<Event Type = RoleManager Audit Event ><Subject: 0>
<<webservices>><type=<webservices>,
application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple,
webService=SimpleSoapPort, method=sayHello,
signature={java.lang.String}><>>> Audit Record End ####
#### Audit Record Begin <Mar 30, 2006 9:24:12 AM>  
<Severity =SUCCESS>  
<<<Event Type = Authorization Audit Event V2 ><Subject: 0>
<ONCE><<webservices>><type=<webservices>,
application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple,
webService=SimpleSoapPort, method=sayHello,
signature={java.lang.String}>>> Audit Record End ####

The resource ID for the sayHello method is:

type=<webservices>,
application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple,
webService=SimpleSoapPort, method=sayHello,
signature={java.lang.String}

Edit the resource ID from the auditing record to specify the resource that you want to protect.
The IDs in the audit log are for resources that are at the bottom of the WebLogic Server resource hierarchy. Typically, instead of creating policies for a specific operation (such as a Web Service or EJB method or an HTTP method on a specific URL), you design policies for resources higher in the hierarchy, such as for a URL pattern or an entire Web Service.

You can derive the following resource IDs from the resource ID from the previous step:
- The ID for the Web Service that contains the sayHello method is:
```
type=<webservices>,
application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple,
webService=SimpleSoapPort
```
- The ID for the application that contains the Web Service is:
```
type=<application>,
application=webservicesJwsSimpleEar
```
  Note that resource ID for an application specifies type=<application>.
- The ID for the Web Service type, which you would use to create a root-level policy for all Web Services is:
```
type=<webservices>
```
For information about root-level policies and the hierarchy of resources, see Using Policies to Protect Multiple Resources.

Create XACML Documents

If you want to create role assignments and authorization policies, create two XACML documents: one that describes your roles and another that describes your policies. You load one of the documents into the Role Mapping provider's store and the other into the Authorization provider's store.

For information about using XACML to describe WebLogic Server resources, see Chunk1028650589.html#GUID-06679802-4445-4B55-BAE2-B5D24B66A068.

Example: Defining Role Assignments

The syntax for describing role assignments in a XACML document is specified in the OASIS RBAC Profile specification, available at http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-rbac-profile1-spec-os.pdf. (WebLogic Server supports only a subset of this specification.)

The syntax requires the following elements:

A Policy parent element.
Under Policy, a Target element.
- Under Target, at least one Resource element that contains the following ResourceMatch elements:
  
  (Optional) One ResourceMatch element to identify the name of the role. If you do not include this ResourceMatch element, then the role policy applies to all roles in the realm. The MatchId attribute may specify function identifiers and, thus, wildcard role names. The DataType attribute must specify the string type.
  
  (Optional) Another ResourceMatch element to identify the WebLogic resource to which the role applies. If you do not include this ResourceMatch element, the role applies to all WebLogic resources.
- Under Target, an Action element that indicates that the policy applies to a role instead of some other type of resource.
Under Policy, one or more Rule elements that define which users, groups, or roles are in the role.

The XACML document in Example 7-1 specifies that a role named MyRole role can be used with the SimpleSoapPort Web Service. It also specifies that the webServiceGroup group is in the role.

Note:

When specifying values in the <AttributeValue> element, you must not include extraneous space characters. In particular:

Do not precede the first value with more than a single space character.
When specifying multiple values, do not separate each value by more than a single space character.
Make sure there are no space characters that follow the last value.

For example:

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">value1, value2, value3</AttributeValue>

Example 7-1 XACML Policy for a Role

<?xml version="1.0" encoding="UTF-8"?>
<Policy xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicyId="urn:mycompany:myapplication:myRolePolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable">
   <Description>Grp(group1)</Description>
   <Target>
    <Resources>
     <Resource>
      <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">type=&lt;webservices&gt;, application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple, webService=SimpleSoapPort</AttributeValue>
        <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-ancestor-or-self" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
      </ResourceMatch>
      <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">MyRole</AttributeValue>
        <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
      </ResourceMatch>
     </Resource>
    </Resources>
    <Actions>
     <Action>
       <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:anyURI-equal">
         <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:names:tc:xacml:2.0:actions:enableRole</AttributeValue>
         <ActionAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI" MustBePresent="true"/>
       </ActionMatch>
     </Action>
    </Actions>
   </Target>
   <Rule RuleId="primary-rule" Effect="Permit">
    <Condition>
      <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-is-in">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">webServiceGroup</AttributeValue>
        <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:group" DataType="http://www.w3.org/2001/XMLSchema#string"/>
      </Apply>
    </Condition>
   </Rule>
   <Rule RuleId="deny-rule" Effect="Deny"/>
</Policy>

Example: Defining Authorization Policies

The XACML document in Example 7-2 specifies that only the MyRole role can access the SimpleSoapPort Web Service.

Example 7-2 XACML Policy for a Web Service

<?xml version="1.0" encoding="UTF-8"?>
<Policy xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicyId="urn:mycompany:myapplication:myPolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable">
   <Description>Rol(MyRole)</Description>
   <Target>
    <Resources>
     <Resource>
      <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">type=&lt;webservices&gt;, application=webservicesJwsSimpleEar, contextPath=/jws_basic_simple, webService=SimpleSoapPort</AttributeValue>
        <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-ancestor-or-self" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
      </ResourceMatch>
     </Resource>
    </Resources>
   </Target>
   <Rule RuleId="primary-rule" Effect="Permit">
    <Condition>
     <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-is-in">
       <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">MyRole</AttributeValue>
       <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#string"/>
     </Apply>
    </Condition>
   </Rule>
   <Rule RuleId="deny-rule" Effect="Deny"/>
</Policy>

Configuring Transport-Level Security Through Policy: Main Steps

To configure transport-level web services security via one or more policy files:

As outlined in Prerequisite: Configure SSL, configure SSL for the core WebLogic Server security subsystem.

You can configure one-way SSL where WebLogic Server is required to present a certificate to the client application, or two-way SSL where both the client applications and WebLogic Server present certificates to each other.

To configure two-way or one-way SSL for the core WebLogic Server security subsystem, see Configuring SSL in Administering Security for Oracle WebLogic Server.
Use @Policy or @Policies JWS annotations in your JWS file, or associate policy files only at runtime using , or specify some policy files using the annotations and then associate additional ones at runtime.
See **INTERNAL XREF ERROR** for a description of the available transport-level policies.

Note:

If you specify a transport-level security policy for your web service, it must be at the class level.

In addition, the transport-level security policy must apply to both the inbound and outbound directions. That is, you cannot have HTTPS for inbound and HTTP for outbound.

The following example attaches the policy at the class level:
```
@Policy(uri="policy:Wssp1.2-2007-Saml2.0-Bearer-Https.xml")
public class EchoService {
   ....
```
If you added @Policy or @Policies JWS annotations in your JWS file, compile and redeploy your web service as part of the normal iterative development process.
When you run the client application that invokes the web service, specify certain properties to indicate the SSL implementation that your application should use. In particular:
- To specify the Sun SSL implementation, use the following properties:
```
-Djavax.net.ssl.trustStore=trustStore  
```
  where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate).
  
  Keep certificate-path and hostname verification enabled. The server certificate must chain to a certificate trusted by the client, and its subject alternative name must match the hostname in the HTTPS endpoint. Correct the certificate, truststore, or endpoint hostname instead of disabling either check.
  
  See Configuring Two-Way SSL for a Client Application for additional details about two-way SSL.

Verify That Your Roles and Policies Are in the Realm

The does not display roles and policies that you add from a XACML document.

Instead, to verify that your roles and policies were added to the realm, see Exporting Roles and Policies to XACML Documents.

Creating Roles and Policies for Custom MBeans

A Managed Bean (MBean) is a standard for exposing management data and operations for a resource. Your application developers can greatly reduce the cost of operating and maintaining your applications by creating MBeans (custom MBeans) to monitor and manage your applications. See Developing Manageable Applications Using JMX for Oracle WebLogic Server.

If you register custom MBeans in a WebLogic Server MBean server, you can create a XACML document that defines who can access your MBeans. In addition to the prerequisites described in Prerequisites, note that your MBean's object name must include a Type=valuekey property.

The main steps for creating roles and policies for custom MBeans are:

Determine the Resource IDs for a Custom MBean

When you register a custom MBean with a WebLogic MBean server, the WebLogic security service creates two resource IDs for each attribute in the MBean: one for the attribute's getter method and another for the setter. It creates one resource ID for each MBean operation.

The IDs use the following pattern:

type=<jmx>, operation=type-of-access, application=, mbeanType=type-name, target=attribute-or-operation

In the preceding pattern:

type-of-access specifies the type of access that the policy secures. Use one of the following values:
- get
  
  Indicates that the policy controls who can read one or more MBean attributes.
- set
  
  Indicates that the policy controls who can write one or more MBean attributes.
- invoke
  
  Indicates that the policy controls who can invoke one or more MBean operations.
- create
  
  Indicates that the policy controls who can use the MBean-server's create method to create an instance of an MBean.
- unregister
  
  Indicates that the policy controls who can use the MBean-server's unregister method to unregister an instance of an MBean.
type-name is the value of the MBean object name's Type key property.
attribute-or-operation is the name of an MBean attribute or operation.

For example, if you create an MBean that contains a single attribute named NewUserCount and an operation named clearNewUserCount, and if you register the MBean under the object name medrec:Name=AdminReportMBean,Type=CustomMBeanType, then the security service creates the following resource IDs:

type=<jmx>, operation=get, application=, mbeanType=CustomMBeanType,
target=NewUserCount 

type=<jmx>, operation=set, application=, mbeanType=CustomMBeanType,
target=NewUserCount 

type=<jmx>, operation=invoke, application=, mbeanType=CustomMBeanType, 
target=clearNewUserCount

Exporting Roles and Policies to XACML Documents

To see a XACML representation of all roles and policies that are in your security realm, you can export the data from the Authorization and Role Mapping providers.

Note:

Do not attempt round-trip editing of roles and policies. That is, do not export roles and policies, modify the XACML documents, and then import the modified documents. Editing exported files might result in an unusable WebLogic Server configuration and is not supported.