Request / Response Interface based on JSON and HTTP for ...



Request / Response Interface based on JSON and HTTP for

XACML 3.0 Version 1.0

Working Draft 01

13 December 2011

Abstract:

The aim of this profile is to propose a standardized interface between a policy enforcement point and a policy decision point. The decision request and authorization decision are both specified in the core XACML specification

Status:

This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

Copyright © OASIS Open 2011. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

Table of Contents

1 Introduction 2

1.1 Terminology 2

1.2 Normative References 2

1.3 Non-Normative References 2

2 The XACML request & response 2

2.1 Requirements 2

2.2 Assumed default values 2

2.2.1 The Request element representation 2

2.2.2 The RequestDefaults representation 2

2.2.3 The Attributes representation 2

3 # Conformance 2

A. Acknowledgements 2

B. Non-Normative Text 2

C. Revision History 2

1. Introduction

{Non-normative}

The XACML architecture promotes a loose coupling between the component that enforces decisions, the policy enforcement point (PEP) and the component that decides based on XACML policies, the policy decision point (PDP).

The XACML standard defines the format of the request and the response between the PEP and the PDP. As the default representation of XACML is XML and is backed by a schema, the request and response are typically expressed as XML elements or documents. Depending on the PDP implementation, the request and response could be embedded inside a SOAP message or even a SAML assertion as described in the SAML profile of XACML.

With the rise in popularity of APIs and its consumerization, it becomes important for XACML to be easily understood in order to increase the likelihood it will be adopted. In particular, XML is often considered to be too verbose. Developers increasingly prefer a lighter representation using JSON, the JavaScript object notation.

This profile aims at defining a JSON format for the XACML request and response. It also defines the transport between client (PEP) and service (PDP).

1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

2 Normative References

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, , IETF RFC 2119, March 1997.

3 Non-Normative References

Vocabulary

XML introduces the notion of elements. The equivalent notion in JSON is an object. XML introduces the notion of attributes. The equivalent notion in JSON is a key-value pair.

The XACML request & response

1 Requirements

1. Equivalence: a XACML request and response expressed in XML need not be strictly equivalent in structure to a XACML request expressed in JSON so long as the meaning remains the same and so long as the JSON and XML requests would lead to the same response (decision, obligation, and advice).

2. Lossless behavior: It must be possible to translate requests and responses from XML to JSON and back from JSON to XML without semantic loss

3. Transport-agnostic: the JSON representation will contain all the information the XACML request and / or response contains: this means the transport layer cannot convert XACML decisions into HTTP codes e.g. HTTP 401 for a Deny decision.

2 Overview of the translation mechanisms

1 Assumed default values

To avoid bloating the JSON request and response, certain elements of a request and response will have default values which can then be omitted. As an example, the default value for the datatype of an attribute value will be string.

The user should refer to the XACML 3.0 specification document for a normative definition of the request and response elements

2 Object names

Unless otherwise stated, the name of an object in the JSON representation will be the same as the element name in XML.

3 Object cardinality

When in the XACML specification, an object (XML element) can occur more than once (e.g. 0..* or 1..*), the JSON equivalent will use an array of objects.

4 Datatypes

This section defines how datatypes are represented and handled in the JSON representation. Chapter 10, section 10.2.7 in the XACML 3.0 specification as well as section A.2 list the datatypes that are defined in XACML. These are listed in the table below. The JSON shorthand list the value to be used when creating a XACML attribute in the JSON representation.

It is also possible to omit for certain datatypes the JSON property DataType when it can safely be inferred from the value of the attribute.

|XACML identifier |JSON shorthand |Javascript datatype |

| |#string | |

| |#boolean | |

| |#integer | |

| |#double | |

| |#time | |

| |#date | |

| |#dateTime | |

| |#dayTimeDuration | |

| |#yearMonthDuration | |

| |#anyURI | |

| |#hexBinary | |

| |#base64Binary | |

|urn:oasis:names:tc:xacml:1.0:data-type:rfc822Name |rfc822Name | |

|urn:oasis:names:tc:xacml:1.0:data-type:x500Name |x500Name | |

|urn:oasis:names:tc:xacml:3.0:data-type:xpathExpression |xpathExpression | |

|urn:oasis:names:tc:xacml:2.0:data-type:ipAddress |ipAddress | |

|urn:oasis:names:tc:xacml:2.0:data-type:dnsName |dnsName | |

The example below illustrates possible notations and the behavior of the JSON interpretor:

"Attribute": {

"Id" : "document-id"

"DataType" : "#integer"

      "value" : 123

}

This is equivalent to

"Attribute": {

"Id" : "document-id"

      "value" : 123

}

In the latter example where the DataType property is omitted, the JSON translation must use the closest datatype, in this case integer.

Where there are ambiguities, the datatype #string shall be used.

3 Representation of the XACML request in JSON

The JSON representation of a XACML request will always be semantically equal to its XML representation although its structure might differ.

1 The Request object representation

The Request element is defined on lines 2736 to 2745 of section 5.42 in XXX. In JSON, it will be represented as an object called “Request”.

The Request element contains the following XML attributes:

• ReturnPolicyIdList of type boolean

• CombinedDecision of type boolean

These attributes will be represented as key-value pairs. The JSON representation will assume the following default values

|Attribute |Type |Default value |

|ReturnPolicyIdList |boolean |False. The ReturnPolicyIdList can be omitted in the JSON representation.|

|CombinedDecision |boolean |False. The ReturnPolicyIdList can be omitted in the JSON representation.|

In addition to these XML attributes, the Request element also contains the following XML elements:

• RequestDefaults: this is an optional object.

• Attributes: this will be represented as a JSON array of Attributes objects.

• MultiRequests: this is an optional object.

The representation for these elements are elicited in the following relevant sections.

1 Non-normative example

2 The RequestDefaults object representation

The RequestDefaults element in its XML representation contains a single XML element, XPathVersion which only contains a value. The possible values are defined in the XACML 3.0 specification.

In the JSON representation, instead of using nested objects, the parent object RequestDefaults will be omitted. The XPathVersion element becomes a property of the JSON Request object. Its representation is therefore a property followed by a value:

“XPathVersion” : “”

The property is optional as is the element in the XML representation. The default value for the property if it is needed and not present is .

1 Non-normative example

{

    "Request": {

       “XPathVersion” : “”

    }

}

3 The Attributes object representation

The Attributes element is defined on lines xxx to xxx of section xxx in XXX. It contains the following XML attributes:

• Category of type anyURI

• Id of type string

|Attribute |Type |Default value |

|Category |anyURI |None – the identifier used in the XML representation shall be used in |

| | |its JSON representation |

|Id |String |The Id attribute is optional in the XML representation. It shall also be|

| | |optional in the JSON representation. There is no default, assumed, value|

| | |for the Id in JSON. If there is a value specified in the XML |

| | |representation, it must also be specified in the JSON representation. |

In addition to these XML attributes, the Attributes XML element contains

• Content: this is an optional object.

• Attribute: this is an array of objects

The structure and default values for these elements are elicited in the following relevant sections.

The Attributes element in XML will be represented as an object in JSON.

1 Default Attributes objects

To simplify the JSON representation, this profile also defines four optional default objects that are semantically equivalent to the Attributes object. These default objects assume a default value for the Category property so that it need not be explicitly written. The following table summarizes these four objects and the default values

|Name |Default value for the child Category property |

|Subject |urn:oasis:names:tc:xacml:1.0:subject-category:access-subject |

|Action |urn:oasis:names:tc:xacml:3.0:attribute-category:action |

|Resource |urn:oasis:names:tc:xacml:3.0:attribute-category:resource |

|Environment |urn:oasis:names:tc:xacml:3.0:attribute-category:environment |

2 Non-normative example

{

    "Request": {

        "Attributes": [{

            "Category": "custom-category",

            "Attribute": […]

        },

        {

            "Category": "another-custom-cat",

            "Attribute": {…}

            }

        }]

       "Subject":{

            "Attribute": […]

       }

    }

}

4 The Content Object representation

5 The Attribute Object representation

In the XML representation of a XACML request, the Attributes element contains Attribute elements which in turn contain AttributeValue elements. The Attribute element contains the following XML attributes:

|Attribute |Type |Default value |

|AttributeId |URI |None – the identifier used in the XML representation of a XACML |

| | |attribute shall be used in its JSON representation |

|Issuer |String |The issuer value can omitted in the JSON representation. Its default |

| | |value will be a null value. |

|IncludeInResult |Boolean |False. |

In addition the AttributeValue element contains the following XML attributes:

|Attribute |Type |Default value |

|Datatype |URI |The datatype value can be omitted in the JSON representation. Its |

| | |default value will be |

To simplify the structural representation of a JSON attribute, the AttributeValue element will not have any JSON object equivalent. Consequently, the JSON Attribute object will carry an additional DataType property.

1 Non-normative example

            "Attribute": [{

                "Id": "user-role"

                "value" : ["manager","administrator"]

            }]

Transport

Example

The following is a non-normative sample XACML request expressed in JSON

{

    "Request": {

        "Attributes": [{

            "Category": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",

            "Attribute": [{

                "Id": "user-role"

                "value" : ["manager","administrator"]

            }]

        },

        {

            "Category": "urn:oasis:names:tc:xacml:3.0:attribute-category:resource",

            "Attribute": {

                "Id": "document-id"

                " DataType ": ""

                   "value" : ["123"]

                }

            }

        }]

    }

}

# Conformance

The last numbered section in the specification must be the Conformance section. Conformance Statements/Clauses go here.

A. Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

[Participant Name, Affiliation | Individual Member]

[Participant Name, Affiliation | Individual Member]

B. Non-Normative Text

C. Revision History

|Revision |Date |Editor |Changes Made |

|[Rev number] |[Rev Date] |[Modified By] |[Summary of Changes] |

Notes

“key” : false

“key” : 12

A JSON request is made up of:

• An optional XPath version key key-value pair

•

-----------------------

NOTE: The proper format for citation of technical work produced by an OASIS TC (whether Standards Track or Non-Standards Track) is:

[Citation Label]

Work Product title (italicized). Approval date (DD Month YYYY). Stage Identifier and Revision Number (e.g., Committee Specification Draft 01). Principal URI (version-specific URI, e.g., with filename component: somespec-v1.0-csd01.html).

For example:

[OpenDocument-1.2]

Open Document Format for Office Applications (OpenDocument) Version 1.2. 19 January 2011. OASIS Committee Specification Draft 07. .

[CAP-1.2]

Common Alerting Protocol Version 1.2. 01 July 2010. OASIS Standard. .

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download