Securing WebLogic Resources Using Roles and Policies

Using XACML Documents to Secure WebLogic Resources

The eXtensible Access Control Markup Language (XACML) is an XML language for expressing authorization policies and role assignments. The WebLogic Server XACML Authorization Provider and the WebLogic Server XACML Role Mapping Provider implement the XACML 2.0 Core Specification (see XACML 2.0 Core Specification).

If you need to create security roles or policies that are more complex than can be created with the WebLogic Server Administration Console, or if you are required to express your security roles and policies in a standard language, you can create roles and policies in a XACML document and then use WebLogic Scripting Tool to add them to your security realm. You can also export your realm's roles and policies to a XACML document and then import the document in other WebLogic Server realms. For example, you can export from a realm in a development environment and then import into a production realm.

The following sections describe how to use XACML documents to secure WebLogic resources:

Caution:

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 polices as indeterminate, which locks all users (including the administrative user) out of the domain. See Caution: Indeterminate Results Can Lock Out All Users.

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 polices for an EJB or Web application that you have deployed using the Deployment Descriptor Only security model. See Comparison of Security Models for Web Applications and EJBs.

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:

Determine Which Resource to Secure

WebLogic Server organizes its resources into a hierarchy. If you use the Administration Console or a J2EE 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 in Configure Auditing Providers the Administration 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.

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 Reference for XACML on WebLogic Server.

Example: Defining Role Assignments

The syntax for describing role assignments in a XACML document is specified in the RBAC Profile specification. (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 Listing 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.

Listing 7-1 XACML Policy for a Role

<Policy xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
   PolicyId="urn:sample:xacml:2.0:myRolePolicy"
   RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:
   first-applicable">

<Description>My Role Policy</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"
            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 Listing 7-2 specifies that only the MyRole role can access the SimpleSoapPort Web Service.

Listing 7-2 XACML Policy for a Web Service

<Policy PolicyId="urn:sample:xacml:2.0:myID"
   RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:
   first-applicable">

   <Description>My XACML Authorization Policy</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"
         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">
           don
        </AttributeValue>
        <SubjectAttributeDesignator
           AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id"
           DataType="http://www.w3.org/2001/XMLSchema#string"
           SubjectCategory="urn:oasis:names:tc:xacml:1.0:subject-category:
            access-subject"/>
        </Apply>
     </Condition>
   </Rule>
   <Rule RuleId="deny-rule" Effect="Deny"/>
</Policy>

Use WebLogic Scripting Tool to Add the Role or Policy to the Realm

The WebLogic Scripting Tool (WLST) is a command-line scripting interface that you can use to load your XACML document into a WebLogic security realm.

You can use WLST in interactive mode or script mode. You cannot use WLST in offline mode; the Authentication provider and Role Mapping provider can update their policy stores only when the Administration Server is running.

For information about using script mode, see Using the WebLogic Scripting Tool in WebLogic Scripting Tool.

The following steps describe using the WLST interactive mode:

Start the WebLogic Server instance that contains the realm you want to configure.
Open a command prompt and set up the environment for running WLST.

One way to set up the environment is as follows:

Change to the root directory of the domain.
Invoke the setWLSenv script (the Domain Configuration Wizard creates this script for you when you create the domain).

Change to the directory that contains your XACML document.
To start WLST and connect to a WebLogic Server instance that is listening at localhost:7001, enter the following commands:

java weblogic.WLST

This command returns a WLST prompt.

connect(`username','password','localhost:7001')

where username and password are credentials for an administrative user.

To load a XACML document into a Java String object, enter the following commands:

xacmlFile = open(`myfile','r')

where myfile is the name of your XACML document.

xacmlDoc = xacmlFile.read()
(Optional) To verify that you have loaded your document into a String, enter:
print(xacmlDoc)

The command prints the value of the xacmlDoc variable to standard out.

To load role assignments into the WebLogic XACML Role Mapper, enter the following commands:

cd (`SecurityConfiguration/mydomain/Realms/myrealm/ RoleMappers/XACMLRoleMapper')

where
mydomain is the name of your WebLogic Server domain
myrealm is the name of your domain's security realm

cmo.addPolicy(xacmlDoc) or cmo.addPolicySet(xacmlDoc), depending on whether your XACML document contains a Policy or PolicySet.

To load authorization policies into the WebLogic XACML Authorizer, repeat step 5 to load your XACML policies document, Then enter the following commands:

cd (`SecurityConfiguration/mydomain/Realms/myrealm/ Authorizers/XACMLAuthorizer')

where
mydomain is the name of your WebLogic Server domain
myrealm is the name of your domain's security realm

cmo.addPolicy(xacmlDoc) or cmo.addPolicySet(xacmlDoc), depending on whether your XACML document contains a Policy or PolicySet.

To see a full list of operations that you can use to add, modify, or delete policies, see XACMLAuthorizerMBean in WebLogic Server MBean Reference.

Verify That Your Roles and Policies Are in the Realm

The WebLogic Server Administration Console 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 Polices 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 with JMX.

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=value" key 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

where:

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=clearNewUserCount, application=, mbeanType=CustomMBeanType,target=

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.

Caution:

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.

For information on how to export security data, see Export Data from Security Providers in the Administration Console Help.