The Discovery attribute based access control language is presented as a pragmatic JSON based profile of the XACML language, modified to use the information model query language (SPARQL) to define policy rules. ABAC attributes are defined in the semantic ontology in the same way as all other classes and properties.
The language is used to support some of the data access authorisation processes as described in the specification - Identity, authentication and authorisation .
This article specifies the scope of the language , the grammar and the syntax, together with examples. Whilst presented as a JSON syntax, in line with other components of the information modelling language, the syntax can also be accessed via the ABAC xml schema which includes the baseline Information model XSD schemaon the Endeavour GitHub, and example content viewed in the information manager data files folder
Scope of ABAC language and approach
The language is designed to support a conversation between a client application and a policy decision point, with an intermediary; the policy enforcement point, brokering the exchange. The purpose of the conversation is to ascertain whether the client has permission to access a function and resource.
The conversations are constrained, consisting of a request, an assessment followed by a decision, and a response.
The flow is as follows:
- The application makes a request to it's policy enforcement point (PEP).
- The PEP packages the request and passes it to the Policy decision point (PDP).
- The PDP examines the request and looks for policies relevant to the request and decides whether the request can be granted.
- The PDP passes the response back to the PEP. If the request is granted the PDP may also oblige the PEP to perform some other activity as part of the action.
- The PEP returns the response to the application. The application may also need to understand the obligations in respect of the access, although this could be delegated to the PEP.
Requests are also constrained. ABAC specialises in requests for access to some function or some data in order to perform some action. Requests are assessed in the context of the characteristics of the request, the requester, and a policy which is stored in the Policy information point (PIP). Responses are simply permit, deny, not relevant or indeterminate, with perhaps some obligations or advice associated with the response.
There is no assumption within the language as to the infrastructure or the physical separation of concerns between the client, the PEP, or the PDP. In practice, a PEP may be a component within an application and a PDP may be implemented in process also, although it is recommended that a PDP is implemented as a server accessed via REST API.
It is strongly recommended that readers of this specification familiarise themselves with ABAC and have an overall understanding of the main concepts in XACML.
In line with the rest of the information language, the ABAC language consists of a small number of tokens (reserved words), referencing the vocabulary of attributes and value types via the ontology. Much of the ABAC rule language is dispensed with as being replaced by SPARQL ASK clauses which are in effect Graph matching clauses consistent with all other IM query.
Language tokens
A set of classes represent the language of policies. Each class name is also a token in the language. Some of the classes are modelled as concept structures and thus inherit the main concept property of IRI, name description.
Each business related property of each class is also a token.
Attributes identifiers and value identifiers are pragmatically modelled as IRIs in the semantic ontology and are used in the objects at run time, therefore are not inherently tokens.
The main classes are illustrated in the diagram on the right.
Syntax as a language
The language is represented here in BNF notation with terminals in ' '. non terminals in bold face,zero or more as { }, zero or one as [ ], alternatives as '|' and descriptions in italics
A JSON representation conforming to an XML schema directly follows the syntax with the tokens or values in their relevant name value JSON space
iri := an iri either as a full iri or an abbreviated iri where namespace prefixes are declared by the PIP
Literal : a finite sequence of characters in which " (U+22) and \ (U+5C) occur only in pairs of the form \" (U+5C, U+22) and \\ (U+5C, U+5C), enclosed in a pair of " (U+22) characters. The data type of the literal is determined by the range of the data type property as defined in the ontology, optionally specified at instance level
DataType: 'DataType' iri
PolicySet := 'PolicySet' iri name [description] CombiningAlgorithm {PolicySet} {Target} {Policy}
CombiningAlgorithm := 'CombiningAlgorithm' 'deny-overrides' | 'permit-overrides'
Target:= 'Target' MatchUnion|MatchIntersection|{Match}
MatchUnion :='Union' MatchUnion|MatchIntersection|{Match}
MatchIntersection :='Intersection' MatchUnion|MatchIntersection|{Match}
Match:= 'Match' 'Subject' | 'Resource' | 'Action' | 'Environment' [Mandatory] Attribute
Mandatory := 'Mandatory' 'true|false'
Attribute := AttributeType AttributeValue [DataType]
AttributeType: Any object property or data property from the semantic ontology
DataType:= 'DataType' Any data type from the semantic ontology
AttributeValue:= Literal | {Attribute}
Policy := 'Policy' iri name [description] Effect [CombiningAlgorithm] {Target} {Rule} {Obligation}
Effect:= 'Effect' 'Permit' | 'Deny'
Rule:= 'Rule' SPARQL where/ filter clause assuming ?Subject ?Resource etc as parameters where abbreviated iris mus have namespace prefixes declared
Obligation:= 'Obligation' Function
Function:= iri {Argument|Parameter}
Argument:= Literal
Parameter:=Literal
Request:= 'Request' {AccessSubject} {AccessResource}
AccessSubject: 'AccessSubject' Attribute
AccessResource:= 'AccessResource' Attribute
Response := 'Response' Result {Obligation}
Result:= 'Result' 'Permit'|'Deny'|'Indeterminate'|'Not applicable'
Documentation of tokens
The following table documents the tokens
| Token | Description | ||
|---|---|---|---|
| PolicySet | A set of policies brought together to resolve policy combinations or to maintain common outcomes. A policy set may contain other policy sets as well as policies. A policy set may contain a target and will have a combining rule | ||
| Policy | A set of rules with a (combining algorithm if more than one) that deals with a type of request. A policy may contain a target | ||
| Rule - | A query definition of the decision that will be taken. A rule may contain a target or condition type rule. | ||
| Target | An index consisting of a set of matches of attributes and values used to indicates that a policy set or policy or rule is the target of a request. The target is itself is a rule in that if the attributes and values match, and no other condition is placed up it, then the policy can make a decision at that point.
Target attributes are evaluated as single attributes, union of attributes or intersection of attributes. A list of matches is considered an intersection (all of) by default |
||
| Union | Indicates an OR against the ensuing match list. The term "Any of" is used in XACML but the term Union is used to align with Owl and set approaches | ||
| Mandatory | indicates whether the attributes being tested must be present in order for the policy to return an indeterminate outcome or simple an empty collection | ||
| CombiningAlgorithm | Type of logical resolution where rules or policies product conflicting results. | ||
| Subject | Describes the subject that is requesting access, or describes the attributes of subjects required to grant or refuse permission. A typical example of a subject would be a user and their role | ||
| Resource | Describes the module, function or data that the requester is attempting to access, or when used in a policy, the nature of the resource that may determine whether or not permission is granted | ||
| Action | Describes the action that will be performed in relation to the resource, or when used in a policy, the nature of the action that may determine whether or not permission is granted | ||
| Environment | describes environmental conditions that may be tested for, e.g. time of day. | ||
| AccessSubject | Indicates that a subject is requesting access and therefore attributes relate to the subject requesting access e.g. a user in role. | ||
| AccessResource | Indicates that the application is requesting access to a resource. | ||
| Request | Header indicating the object is a request for access | ||
| Response | Header indicating the object is a response to a request | ||
| Result | Result of the request Indeterminate would suggest an error in policy authoring. Unknown or not applicable means that no policy has been found. How the application operates in these circumstances will be a matter of non computable IG policy. | ||
| DataType | Indicates the data type of the literal when used as an attribute value | ||
| Attribute | A property iri together with its value |
Attributes and how they are defined
Attributes are properties and values describing subjects, resources, actions and the environment. Attributes are modelled in the common information model ontology like any other property such as health record property. Consequently, they also share the same semantic definitions. This allows ABAC attributes to be treated like any other e.g. query, subsumption query, data storage.
The conversation that exists between the application and the PDP often involves the exchange of subject attributes e.g. attributes of a user or the user in a role. Obviously there must be a common understanding of the meaning of those attributes. In other words an attribute of a user must mean the same thing as an attribute of a policy that is testing the user's attributes.
To take matter one step further, it is also important that the designers of application functionality understands the attributes that the ABAC policy uses to determine permissions. If an application is going to make a request for access using attributes of the subject or resource then they must match. The information model enables that exchange to take place without the need to map between the application and the PDP attributes. More specifically, it is the PEP context manager that would normally perform this mapping, but in Discovery, the attributes directly match.
JSON ABAC syntax by example
The general approach to the syntax is to de-bloat XACML by
a) Use of some of the elements as language tokens i.e. JSON names. For example PolicySet, Subject,Target.
b) Optimising the use of the graph paradigm to represent run time objects and attributes i.e. triples. e.g. {"abac:AuthenticationLevel" :"TwoFactorAuthentication"}
The ability of JSON to nest triples means that JSON can be used in a conventional manner, but projected as triples for query. Property paths in query can use the SPARQL property path syntax to query the request and policy objects using a standard approach.
A mixed approach can be used. For example the Target class, although used as a rule, can use JSON nested objects rather than SPARQL property paths, which enables simple JSON indexing such as Lucene to find the relevant policies.
The example supports scenario 3 in the working example in the main authorisation topic.
Example 1 - Dashboard access to some but not all providers
User in role attributes
Consider a user, logged on , in role and authenticated with two factors and having accessed Discovery explorer and is currently operating in the context of two projects in the user's session. The user has a role type of GP principal at the Ravenglass Railway medical Centre. The following JSON represents some of the current user in role attributes that will be relevant to the request.
{
":hasRoleType" :{
"iri": ":CM_GeneralPractitionerPrincipal"},
":hasRolename": "General Practioner at Ravenglass Railway medical centre",
":roleOrganisation": {
"id" : "123456"},
":authenticationLevel": {
"iri" : ":CM_TwoFactorAuthenticated"},
":sessionProject" :[ {
"id":"363830"},
{
"id":"789984"}] }
Each of these attributes are object or data property IRIs from the IM ontology. Where the property values are objects, the objects may also have an IRI representing the type of object (class of object) from the information model. In this case for example, the IM Class ":CM_GeneralPractionerPrincipal" is modelled as a subclass.
Properties and class IRIs are shown in their abbreviated form such that the role type attribute would be resolved to
<https://DiscoveryDataService.org/InformationModel/Ontology#hasRoleType>
Access request
The user is logged on to Discovery Explorer and is seeking to access the North East London Dashboards. The NEL dashboards have a resource identifier, which the application knows about. Neither the application nor the user details know whether these dashboards can be accessed by this user or perhaps even the user type. A request is issued, listing some attributes of the user in role and the fact that the NEL dashboard access is requested.
{"Request": {
"AccessSubject":{
"isPerson":{
":hasODSCode":"G12345"},
":hasRoleType" :{
"iri": ":CM_GeneralPractitionerPrincipal"},
":hasRolename": "General Practioner at Ravenglass Railway medical centre",
":roleOrganisation": {
"id" : "123456"},
":authenticationLevel": {
"iri" : ":CM_TwoFactorAuthenticated"},
":sessionProject" :[ {
"id":"363830"},
{
"id":"789984"}] },
"AccessResource":{
":resourceId":"6ae39b72-d6a4-4a94-b519-76cb3f1865a4"}}
Policy
The data controllers have agreed that a senior general practitioner can access NEL dashboards, generally without restriction. However, they are limited to certain practices for practice level data, whereas for the rest of the country they can access only regional level. This is tricky logic requiring a particular query in the reporting database to filter for certain practices being displayed. However, the problem is not the function, it is whether the user MUST use the function in the first place.
A policy is designed to match the dashboard request to a certain functional constraints for Senior clinicians.
{"PolicySet" :{
"iri" : "<http://Discovery/NEL/ABAC/Policies/Reporting/Dashboards>",
"name": "North East London dashboard access policies",
"description": "Set of policies that govern level of granularity in respect of access oto aggregate data for different levels of users",
"CombiningAlgorithm": {
"iri" :"Deny-override"},
"Policy":{
"iri": "<http://Discovery/NEL/ABAC/Policies/Reporting/Dashboards/ProviderLevel>",
"name":"Provider level access to generic dashboards",
"Effect":"Permit",
"Target":[{
"Subject": [{
"roleOrganisation":{
":hasOrganisationType": {
"iri":":CM_HealthCareProvider"}}}]}],
{"Resource":[{
"hasResourceType": {
"iri": ":AggregateReports"}}]}],
"Obligation":[{
"Function" :{
"iri": "IntraRegionalFilter",
"Argument":"STP"}]}}}
This policy set is a set of policies for North East London dashboards. If there is any one of the policies in the set that deny's access then access is denied. One of the policies is for permitting access to Provider level dashboards i.e. provider level access rather than general public.
The target element states that this policy is relevant to any subject that has a role assigning them to a healthcare provider.
It imposes an obligation on the application to make sure that the function "intra regional filter" is applied with an argument of "STP".
It should be noted that the policy refers to health care providers and Aggregate Reports as classes. Furthermore the health care provider class is a value of the "has organisation type" property of the role organisation. Yet the request was specific about the organisation id and the NEL dashboard resource id. This takes advantage of the ontology which can use class definitions to define a set of objects. In the example the GP practice would have had a property of organisation type whose value would be a subclass of healthcare provider (e.g. General Practice). The NEL dashboard resource would have been assigned as an instance of aggregate reports. Thus the use of subsumption testing would result in a positive match.
This example has no complex rule. the example demonstrates that in exchanging request data, the application designer mus have some knowledge of the profile policies and the policy author must have some knowledge of the application functionality. In other words, whilst the ABAC language is a common language it does not in itself preclude the need for a common understanding between the separate concerns.
Response
The response in this case is pretty simple as its a go
{"Response":{
"Result":"Permit",
"Obligation": [{
"Function" :{
"iri": "IntraRegionalFilter",
"Argument":"STP"}]}}}