XACML Interfaces

OES allows external applications to ask authorization questions using the XACML protocol. This capability is supported only in the Web Services SSM.

The XACML service is implemented as an extension to the existing Authorization Service in the Web Service SSM and uses the same configuration and administration scripts of the Web Service SSM. The XACML service is silently installed together with the Web Service SSM. The XACML service is not viewable or configurable through the Administration Console.

Use Case

The policy enforcement point (PEP) receives an access request from some user (subject).
The PEP makes sure that the user is authenticated, either by authentication or some form of identity of assertion.
The PEP constructs the XACML context request using the user’s identity assertion, the action to be performed, the resource the user is requesting, and the environmental values if applicable.
The PEP sends the request via SOAP to the XACML service (PDP).
The XACML service converts the request to a format understood by OES and calls the Authorization Service’s isAccessAllowed method to authorize the user.
Depending on the authorization result, the XACML service constructs a XACML context response and returns it to the PEP with status, and obligations if any.
The PEP takes actions according to the response.

Sample XACML Client

OES includes a simple XACML client (PEP) application that does authorization to the Web Service SSM using the XACML protocol. The example demonstrates the following concepts:

Authorization with ALESIdentityAssertion as the subject.
Authorization with extra attributes in the subject and/or environment in XACML context.
Get authorization result, response attributes and roles from the XACML response.

The example is located in BEA_HOME\ales32-ssm\webservice-ssm\examples\XACMLClient.

XACML Context

XACML is an OASIS standard language that specifies schemas for authorization policies and for authorization decision requests and responses. It also specifies how to evaluate policies against requests to compute a response. In this release, OES implements the authorization process using XACML context. The XACML context is used to convey an authorization decision request and response.

The XACML context is the protocol used by the PEP to ask the PDP for an authorization decision. It defines a <xacml-context:Request> element to convey the request and a <xacml-context:Response> for the response. The request contains four elements for authorization, including:

The PEP sends the authorization request to the PDP using a XACML context, which contains the subject, action, resource, and environment. The PEP is asking the PDP the following question: “Given such a subject, is it allowed to perform the specified action on the specified resource in the specified environment?”.

The XACML service takes the XACML request, converts the request to a format understood by OES, and calls the Java API (specifically, the Authorization Service’s isAccessAllowed method) to authorize the user.

When a decision has been made, the XACML service wraps the returned values into the XACML response. The XACML service returns a SOAP fault if the PEP sends a malformed request that does not follow the XACML context schema. Otherwise, the XACML service will always return a decision of “Permit”, “Deny”, “Indeterminate” or “NotApplicable”.

The PEP then interprets the result and enforces the decision. For the “Permit” decision, the PEP allows the request, and for the “Deny” decision, the PEP denies the request. For results of “Indeterminate” or “NotApplicable,” it is up to the PEP to interpret them. For “Permit-biased” PEP, the access will be allowed; for “Deny-biased” PEP, access will be denied.

Authentication Token Types

The policy enforcement point (PEP) that sends the authorization request to the XACML service is responsible for authenticating the user and supplying a valid OES token as the subject.

Username/password
Signed Security Assertion Markup Language (SAML) 1.1 assertions
OES cookie

The Extensible Markup Language (XML) structures used by the Authentication Service for transmitting identity assertion tokens and other credential types are defined the WSDL interface.

The XACML service accepts the token supplied by the PEP and tries to assert that token (assertion) in OES.

SOAP Binding of XACML Context

As described in XACML Context, the request contains an <xacml-context:Request> and the response contains an <xacml-context:Response> element. These two elements are directly enclosed in the SOAP body.

There are currently two defined XACML namespaces. Policies are defined using the identifier urn:oasis:names:tc:xacml:2.0:policy:schema:os, and request and response contexts are defined using the identifier urn:oasis:names:tc:xacml:2.0:context:schema:os.

This implementation uses the following identifier to represent the XACML service:http://security.bea.com/ssmws/ssm-ws-1.0.wsdl.

POST /XACMLAuthorization HTTP/1.0
Host: pdp-01
Connection: Keep-Alive
Content-Type: application/soap+xml; charset=utf-8
SOAPAction: ssmws:xacml:authorization
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
      <xacml-context:Subject>…</xacml-context:Subject>
      <xacml-context:Resource>…</xacml-context:Resource>
      <xacml-context:Action>…</xacml-context:Action>
      <xacml-context:Environment>…</xacml-context:Environment>
    </xacml-context:Request>
  </soap:Body>
</soap:Envelope>

If a malformed SOAP request is sent to the server (for example, a non-XML request or an XML request that does not follow the schema definition), a SOAP fault is returned to the client (PEP).

XACML Request

<xs:element name="Request" type="xacml-context:RequestType"/>
 <xs:complexType name="RequestType">
     <xs:sequence>
         <xs:element ref="xacml-context:Subject" maxOccurs="unbounded"/>
         <xs:element ref="xacml-context:Resource" maxOccurs="unbounded"/>
         <xs:element ref="xacml-context:Action"/>
         <xs:element ref="xacml-context:Environment"/>
     </xs:sequence>
 </xs:complexType>

As detailed in the standard, the <Request> element contains <Subject>, <Resource>, <Action> and <Environment> elements. There may be multiple <Subject> elements and, under some conditions, multiple <Resource> elements. Each child element contains a sequence of <xacml-context:Attribute> elements associated with the subject, resource, action, and environment, respectively.

The sections that follow describe how the <Subject>, <Resource>, <Action> and <Environment> elements are interpreted.

Attribute

XACML subject, resource, action, and environment elements usually contain XACML context attributes, <xacml-context:Attribute>.

<xs:element name="Attribute" type="xacml-context:AttributeType"/>
 <xs:complexType name="AttributeType">
     <xs:sequence>
         <xs:element ref="xacml-context:AttributeValue" maxOccurs="unbounded"/>
     </xs:sequence>
     <xs:attribute name="AttributeId" type="xs:anyURI" use="required"/>
     <xs:attribute name="DataType" type="xs:anyURI" use="required"/>
     <xs:attribute name="Issuer" type="xs:string" use="optional"/>
 </xs:complexType>

Different attributes in different elements will have different AttributeId and DataType.

The <AttributeValue>, by definition, can carry anything. It contains any element under any namespace, as well as any attributes. Any valid XML data can be put in. However, it must be meaningful for its parent <Attribute>’s AttributeId and DataType.

There can be multiple <AttributeValue> elements in an <Attribute>; however, the XACML service allows only one of them. If there is more than one, an indeterminate result is returned and a processing-error status is reported.

An <Attribute> without an <AttributeValue> results in a SOAP fault because it does not follow the schema.

If there is an Issuer attribute in <Attribute>, it is currently ignored by the XACML service.

The DataType of the <Attribute> is usually ignored, because the content of the <AttributeValue> is regarded only as a string type.

Subject

The <Subject> consists of a sequence of <xacml-context:Attribute> elements associated with the subject.

<xs:element name="Subject" type="xacml-context:SubjectType"/>
 <xs:complexType name="SubjectType">
     <xs:sequence>
         <xs:element ref="xacml-context:Attribute" minOccurs="0"

maxOccurs="unbounded"/>
     </xs:sequence>
     <xs:attribute name="SubjectCategory" type="xs:anyURI" 
 default="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"/>
 </xs:complexType>

The <Subject> element has an optional attribute, SubjectCategory. This represents the subject’s role of this request. For example, ‘access-subject’, ‘requesting-machine’, ‘code-base’.

Inside a <Subject>, there could be an <Attribute> with AttributeId of “urn:oasis:names:tc:xacml:1.0:subject-category”, and the <AttributeValue> of this <Attribute> also represents the subject category. This is equal to the “SubjectCategory” attribute of the <Subject>.

<Subject>
    <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject-category" DataType="xs:anyURI">
<AttributeValue>urn:oasis:names:tc:xacml:1.0:subject-category:access-subject</AttributeValue>
    </Attribute>
</Subject>
<Subject SubjectCategory=”urn:oasis:names:tc:xacml:1.0:subject-category:access-subject”>
</Subject>

Multiple Subjects

The XACML context specifies that these subjects should be "disjunctive," which is defined in the standard as a sequence of predicates combined using the logical ‘OR’ operation.

For example, one subject may represents the human user who initiates the request, another may represent the code that is doing the request. They are specified by subject categories.

If the two subjects have the same subject categories, the elements inside them are treated as if they are in one <Subject> element.
For one request, there must be at least one <Subject> having the “access-subject” category, which represents the direct accessing subject. For the <Attribute> elements of this category, there should be no more than one <Attribute> element with the following AttributeId, which represents the requester’s identity: urn:oasis:names:tc:xacml:1.0:subject:subject-id.

The subject-id <Attribute> is described in Subject Id <Attribute>.
For other <Subject> elements or other <Attribute> elements that are not a subject-id, they are converted as an OES authorization context (AppContext).

Subject Id <Attribute>

The DataType attribute of the subject-id <Attribute> element indicates the subject type. The type is of “anyURI” type, but in order to be understood, the DataType should be prefixed with the

identifier that represents the XACML service: http://security.bea.com/ssmws/ssm-ws-1.0.wsdl.

In addition, a fragment should be suffixed after this URL indicating the subject type that could be asserted in OES; that is, the first parameter of the assertIdentity() method in the Authentication service API.

For example, if the subject contains ALESIdentityAssertion, it should have the DataType http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#ALESIdentityAssertion, and the <AttributeValue> of this <Attribute> is taken as the subject.

However, if a valid <AttributeValue> is provided and correctly recognized by the Web Service SSM, the DataType may not be checked.

If the <Subject> (which is of ‘access-subject’ category) does not contain an <Attribute> with “subject-id”, this subject will be considered as an anonymous user. The service will construct an anonymous identity and pass it to the authorization service.

Other Subject and Attribute Elements

For other <Subject> elements and <Attribute> elements that are not in the ‘access-subject’ category, or are in the ‘access-subject’ category but without a “subject-id” id, those <Attribute> elements are converted as authorization context (AppContext) of OES.

If there are multiple <Attribute> elements with the same id, a later one will override the previous one.

Also, only text values in <AttributeValue> are acceptable; child XML elements are ignored.

If the AttributeId is a URN (for example, “urn:oasis:names:tc:xacml:1.0: subject:authn-locality:authentication-method”), the last field of the URN, that is, the string after the last colon, is taken as the context key, and the AttributeValue is the context value. For example, if the previous URN has an AttributeValue of “username/password”, the resulting OES context will be “authentication-method” : “username/password”.
If the AttributeId is a URL (for example, “http://security.bea.com/ssmws/ssm-ws-1.0.wsdl/schema#Cache-Control”), the fragment (the string after the ‘#’ character) of the URL is taken as the context key. The example URL is converted as “Cache-Control”.

Note that this is a XACML extension: the XACML standard does not have this type of URL as AttributeId, but the PEP could use this method to pass some context to the OES system.

If none of the above matches, the full URI is used as the context key. The value is always the AttributeValue in this Attribute.

Mapping Resources and the OES Resource

At least one of the resource attributes should have the following AttributeId: urn:oasis:names:tc:xacml:2.0:resource:resource-id.

The AttributeValue of this resource attribute should be the resource that can be understood by OES; that is, the resource under the binding point of the SSM. The example queries the user for the resource name, and suggests a value of "store/book."

The DataType of this attribute should always be the XML schema standard “string” type: http://www.w3.org/2001/XMLSchema#string.

Other attributes in <Resource>, except for the one associated with the naming authority, are converted as authorization context attributes for authorization evaluation in OES, using the same rule as <Subject> attributes.

Mapping Actions and the OES Action

At least one of the attributes in the <Action> element must have the following AttributeId: urn:oasis:names:tc:xacml:1.0:action:action-id.

The attribute value of this attribute is the action performed on the resource. For example: GET, POST. The example queries the user for the action name.

The DataType of this attribute should be the XML schema standard string http://www.w3.org/2001/XMLSchema#string.

Other attributes in <Action> are converted as context attributes for authorization evaluation in OES, using the same rule as <Subject> attributes.

Environment Attributes

The XACML service converts environment attributes to OES application context. The rule to convert environment elements to OES contexts is the same as for the subject. All attributes in <Environment> elements are converted.

<Environment>
    <Attribute AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl
    #DOB" DataType="http://www.w3.org/2001/XMLSchema#dateTime">
        <AttributeValue>1979-03-29</AttributeValue>
    </Attribute>
</Environment>

The fragment (the string after the ‘#’ character) of the URL is taken as the context key and the AttributeValue is the context value, which results in an OES context of DOB:1979-03-29.

Sample Request

<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os">
  <Subject>
    <Attribute     <AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" 
        <DataType=" http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#
        <ALESIdentityAssertion">
        <AttributeValue>
            <ALESIdentityAssertion xmlns=”…”>……</ALESIdentityAssertion>
        </AttributeValue>
    </Attribute>
  </Subject>
  <Resource>
    <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-id" 
DataType="http://www.w3.org/2001/XMLSchema#string">
        <AttributeValue>/cgi-bin/j_security_check</AttributeValue>
    </Attribute>
  </Resource>
  <Action>
    <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
        DataType="http://www.w3.org/2001/XMLSchema#string">
        <AttributeValue>POST</AttributeValue>
    </Attribute>
  </Action>
<Environment/>
</Request>

OES XACML Response

The <Response> element is the root element of a response. It contains one or more <Result> elements, which contain authorization decision results. The XACML service supports only one <Result> element.

<xs:element name="Result" type="xacml-context:ResultType"/>
<xs:complexType name="ResultType">
    <xs:sequence>
        <xs:element ref="xacml-context:Decision"/>
        <xs:element ref="xacml-context:Status" minOccurs="0"/>
        <xs:element ref="xacml:Obligations" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="ResourceId" type="xs:string" use="optional"/>
</xs:complexType>

The <Result> element has a ResourceId attribute that indicates the identifier of the request resource element. This implementation does not use this value.

Mapping Decision

Decision is the evaluation result. It contains a string value of “Permit”, “Deny”, “Indeterminate”, or “NotApplicable”. “Permit” or “Deny” are typically returned. For example: <Decision>Permit</Decision>.

If some required attribute is required, “Indeterminate” is returned, with the “missing-attribute” status.

Mapping Status

The <Status> element is an optional element of <Result>. It contains the following elements:

<StatusCode>

<StatusCode> has an attribute named “Value,” which can be one of the following values:

— urn:oasis:names:tc:xacml:1.0:status:ok
— urn:oasis:names:tc:xacml:1.0:status:missing-attribute
— urn:oasis:names:tc:xacml:1.0:status:syntax-error
— urn:oasis:names:tc:xacml:1.0:status:processing-error

If any exception occurred during the authorization process, processing-error is returned.

If some attribute is required for evaluating the policy, missing-attribute is returned.

Otherwise, “ok” is returned.

“syntax-error” is never returned.

<StatusMessage>(Optional)

<StatusMessage> is simply a string to show the message accompanying the status. If an exception occurs, the exception will be in the <StatusMessage> for information purpose.

<StatusDetail>(Optional)

<StatusDetail> is an extension point and it can contain anything. This implementation puts a <MissingAttributeDetail> value in it if the status is “missing-attribute”. In that case, the AttributeId is the missing attribute key, prefixed with the XACML service namespace (http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#) and there is no <AttributeValue> in the <MissingAttributeDetail> element.

Mapping Obligations

A XACML obligation is an operation specified in a policy or policy set that should be performed by the PEP in conjunction with the enforcement of an authorization decision.

This implementation places the returned evaluation values, such as roles or the report_as values, in an obligation. Obligations are used only when the authorization result is “Permit.”

<xs:element name="Obligations" type="xacml:ObligationsType"/>
  <xs:complexType name="ObligationsType">
    <xs:sequence>
        <xs:element ref="xacml:Obligation" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
<xs:element name="Obligation" type="xacml:ObligationType"/>
  <xs:complexType name="ObligationType">
    <xs:sequence>
      <xs:element ref="xacml:AttributeAssignment" minOccurs="0"
          maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="ObligationId" type="xs:anyURI" use="required"/>
    <xs:attribute name="FulfillOn" type="xacml:EffectType"use="required"/>
  </xs:complexType>

<xs:element name="AttributeAssignment" type="xacml:AttributeAssignmentType"/>
  <xs:complexType name="AttributeAssignmentType" mixed="true">
    <xs:complexContent mixed="true">
      <xs:extension base="xacml:AttributeValueType">
        <xs:attribute name="AttributeId" type="xs:anyURI" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

Obligations consist of one or more <Obligation> elements. An <Obligation> has the following attributes:

FulfillOn: could be “Permit” or “Deny.” This obligation should be fulfilled if the effect (result) is permit or deny. This implementation always puts “Permit” in this attribute.
ObligationId: the identifier of this obligation. Two types of obligation id are available in this implementation:

http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#ResponseAttributes represents a set of response attributes.
http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#Roles represents the roles when performing authorization.

The <Obligation> element has zero or more <AttributeAssignment> elements. <AttributeAssignment> has an AttributeId and text content. The AttributeId is the returned attribute key, prefixed with the namespace http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#, and the content is the attribute value.

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os">
  <Result> 
    <Decision>Deny</Decision>
    <Status>
      <StatusCode Value="urn:oasis:names:tc:1.0:status:processing-error"/>
      <StatusMessage>Authentication required</StatusMessage>
    </Status>
    <Obligations>
      <Obligation FulfillOn="Permit"        <ObligationId="http://security.be.com/ssmws/ssm-ws-1.0.wsdl#Roles">
        <AttributeAssignment DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl#role">Admin
        </AttributeAssignment>
      </Obligation>
    </Obligations>
  </Result>
</Response>

WSDL Definition of the XACML Service

<?xml version="1.0" encoding="UTF-8"?>
<definitions
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os"
    xmlns:ssm="http://security.bea.com/ssmws/ssm-soap-types-1.0.xsd"
    xmlns:tns="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl"
    targetNamespace="http://security.bea.com/ssmws/ssm-ws-1.0.wsdl">
<types>
<!-- note this policy schema is stripped for the XACML runtime only -->
  <xs:import namespace="urn:oasis:names:tc:xacml:2.0:policy:schema:os" schemaLocation="access_control-xacml-2.0-policy-schema-os.xsd"/>
    <xs:import namespace="urn:oasis:names:tc:xacml:2.0:context:schema:os" schemaLocation="access_control-xacml-2.0-context-schema-os.xsd"/>
    <!-- for fault types -->
    <xs:import namespace="http://security.bea.com/ssmws/ssm-soap-types-1.0.xsd" schemaLocation="ssm-soap-types.xsd"/>
</types>
<message name="XACMLAtzDecisionRequest">
    <part name="param" element="xacml-context:Request"/>
</message>
<message name="XACMLAtzDecisionResponse">
    <part name="param" element="xacml-context:Response"/>
</message>
<message name="XACMLFault">
    <part name="fault" element="ssm:xacmlFailure"/>
</message>
<message name="serviceFault">
    <part name="fault" element="ssm:serviceFailure"/>
</message>
<portType name="XACMLPort">
    <operation name="authorize">
        <input message="tns:XACMLAtzDecisionRequest"/>
        <output message="tns:XACMLAtzDecisionResponse"/>
        <fault name="serviceFault" message="tns:serviceFault" />
        <fault name="xacmlFault" message="tns:XACMLFault"/>
    </operation>
</portType>
<binding name="XACMLBinding" type="tns:XACMLPort">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <!-- Axis has problem support this style, use document instead. -->
    <operation name="authorize">
      <soap:operation soapAction="ssmws:xacml:authorization" style="document"/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="serviceFault">
        <soap:fault use="literal"/>
      </fault>
      <fault name="xacmlFault">
        <soap:fault use="literal"/>
      </fault>
    </operation>
  </binding>
<service name="XACMLService">
    <port name="XACMLAuthorization" binding="tns:XACMLBinding">
      <soap:address location="http://localhost/XACMLAuthorization"/>
    </port>
  </service>
</definitions>

Programming Security for Web Services