Access Control and Capability Grant Language
Access rules, capability grants, and obligations are explained in Data Access Conditions, this document specifies the precise syntax and values that can be used.
An access rule contains:
- Zero or more conditions for access
- One or more capability grants to the data consumer if access is granted
- Zero or more obligations falling on the data consumer if access is granted
They are applied to properties of a Data Consumer while processing a request for data from a Data Provider. These properties can be modelled as a map of names to values; some values may be inferred by joining on the ID of the data consumer, some may be directly provided in the Token introspection response.
Syntax
Names
Names consist of a namespace ([a-z0-9_]+
), a :
character, and a suffix ([a-z0-9_.]+
). For example, ib1:some_value
. Values asserted by Icebreaker One will always have a namespace ib1
. The suffix may contain .
characters, the namespace may not.
Rule syntax
An access rule is represented as a single line string containing a comma separated list of zero or more Conditions, the literal string grants
, and then a comma separated list of one or more Capabilities. Optionally, this may
be followed by the literal requires
and one or more Obligations in a comma separated list.
[CONDITION]? ["," CONDITION]* "grants" CAPABILITY ["," CAPABILITY]* ["requires" OBLIGATION+ ["," OBLIGATION]
NOTE: * A rule with no conditions is valid, and is satisfied by all requests * All rules must grant at least one capability * Rules may have zero or more obligations
See the following sections for specification of conditions and capabilities.
Conditions
Conditions are unary or binary clauses.
All conditions must be satisfied within a rule for that rule to be applied. There are no explicit boolean operators such as or
or similar. For cases where alternative sets of rules could be applied the expectation is that data
providers will specify multiple, potentially overlapping, rules to express this.
Unary clauses
Unary clauses consist of a single named condition. The clause is satisfied if that condition is true
. This is typically used to denote a particular property such as Icebreaker One Trust Framework membership or similar where the existence of the property is sufficient to accept the data consumer.
{"ib1:member" : true}
Binary clauses
Binary clauses consist of a name on the left hand side, an operator, and a value on the right hand side. The valid operators are shown in the table below. LHS, operator, and RHS are separated with at least one space character.
Values can be numerals, dates, quoted strings, or homogeneous lists of these three types. Dates are specified as dd/mm/yyyy
, we do not need a higher level of precision in any of our envisaged use cases, but if this is needed
a datetime must be specified as a string compliant with RFC3339. To simplify expression in JSON, quoted strings should be enclosed in single quote '
characters. Lists are written as a comma separated list of strings surrounded by [
and ]
characters. Lists are only valid RHS values for the
in
operator.
Operators
Operator |
Range |
Description |
---|---|---|
|
Any |
The condition passes if the value of the property on the LHS is exactly equal to the value in the RHS |
|
date or datetime |
The condition passes if the value of the property on the LHS is before the date or datetime specifed as the RHS. Where a date needs to be coerced to a datetime, it is done by setting it to 00:00.00 with the same date |
|
date or datetime |
As above, but passes if the value of the property on the LHS is after the date or datetime specified on the RHS. |
|
date or datetime |
The condition passes if the value on the LHS corresponds to a date at most X days in the past compared to the current date, where X is integer numeral specified as the RHS |
|
number |
Conditions pass if the LHS is, respectively, less than, less than or
equal, greater than or equal, greater than, or strictly equal, to the
number on the RHS. Note that |
|
number or string |
Conditions pass if there is at least one item in the list specified in
the RHS which would match the |
Example conditions
NOTE: The conditions shown below are examples, and should not be taken as indicative of standard properties of data consumers in the final system.
Example condition clauses
Condition |
Interpretation |
---|---|
|
passes if the value of |
|
passes if the value of |
|
passes if the value of |
|
passes if the value of |
|
passes if the value of |
|
passes if the value of |
Specifying multiple conditions
Multiple conditions are separated with ,
characters. All conditions must be satisfied for the rule to pass, there are no sub-clauses or boolean operators. Any number of space characters are allowed before and after the ,
in a
condition list.
For example, ib1:status is 'active', some_group:membership_level >=2
is the union of those two example conditions from the previous section and will only be satisfied if both conditions are individually satisfiable.
Capabilities
Capability grants for a given set of access conditions are specified as a comma (,
) separated list of names. There MUST be at least one name in this list, an empty capability grant list is not considered valid.
Standard capabilities
These are capabilities where the namespace part of the name is ib1
, indicating that they are defined as part of the Icebreaker One Trust Framework. Data providers SHOULD NOT, create their own capabilities unless absolutely necessary as doing so acts against the aim of easy interoperability and comprehension of access and licensing rules.
Any additional capabilities designed MUST be prefixed with the organisation ID of the data provider responsible for their definition, and any such data provider MUST publish a clear, legally valid, definition of any such capabilities. In addition, data providers creating custom capabilities MUST inform the TFGS of this, providing links to the aforementioned documentation.
WARNING: This section is provisional, the exact final set of base capabilities has yet to be determined. Those shown below are a plausible first cut but should not be considered definitive.
Category |
Capability name |
Meaning |
---|---|---|
Use |
Use the artefact internally |
|
|
For any purpose |
|
|
For development purposes only (i.e. private or limited development of new works, products or services) |
|
|
For non-commercial purposes only (e.g. education, research, charity work etc.) |
|
Adapt |
Adapt the artefact for internal use |
|
|
For any purpose |
|
|
For development purposes only (i.e. private or limited development of new works, products or services) |
|
|
For non-commercial purposes only (e.g. education, research, charity work etc.) |
|
Combine |
Combine (‘remix’) the artefact |
|
|
With any other artefacts |
|
|
With other external artefacts |
|
|
With the Data Consumer’s own products or services |
|
Redistribute |
Redistribute (‘onward share’ - including to any customers of the Service Provider) |
|
|
The original artefact |
|
|
Derivatives of the original artefact not produced from other data sets, i.e. filtered or cleaned data |
|
|
Derivatives of the artefact produced through artefact combination or use in the Data Consumer’s own products or services |
Expressing Open Data licenses with capabilities
The capabilities defined above in Standard capabilities are intended for shared data, but data providers may also publish open data. An open data set by definition has no access conditions, so any access rules for such data sets MUST have an empty access condition list, and must use one of the following capabilities to declare that the data are licensed under a known OSI approved open license
Rules MUST NOT grant a mix of capabilities in the open
namespace and capabilities in other namespaces, as the semantics of this are not well defined.
Capability name |
Corresponding open data license |
---|---|
|
Creative Commons Attribution (v1.0, v2.0, v2.5, v3.0, v4.0 respectively) |
|
Creative Commons Attribution ShareAlike (v1.0, v2.0, v2.5, v3.0, v4.0 respectively) |
|
|
|
GNU Free Documentation License (v1.1, 1.2, 1.3 respectively) |
|
Free Art License (v1.2, v1.3 respectively) |
Open data sets SHOULD be released under the latest version of any given license.
Obligations
Obligations are constraints on what the data consumer can do with the data, restricting or specialising the capabilities granted. They are specified as a single name.
Standard obligations
WARNING: This set of standard obligations is provisional and may be subject to change
Obligation |
Name |
Explanation |
---|---|---|
Fulltext |
|
Re-users must display the full text of the license every time they use the work |
Attribution |
|
Re-users must attribute the work to the original source when they use it |
ShareAlike |
|
Re-users who create derivatives of the work must release the derivatives under the same license as the original work, if they choose to distribute the derivatives |
NOTE: Two additional common constraints in existing (mostly open) licenses are NonCommercial and NoDerivatives. These are explicitly not included here as it is possible to express this through the access conditions (i.e. rather than declaring that a data set is only available for non-commercial usage it is better to say that only non-commercial entities may access it). This is not quite equivalent, but simpler and better defined than the relative minefield of defining ‘non commercial use’.