Module Documentation:
eml-access
| Back to EML Contents |
The eml-access module describes the level of access that is to be granted or denied to a resource (including both metadata and data) for a particular user or group of users. The eml-access module uses references to a particular authentication system to determine the set of principals (users + groups) that can be specified in access rules, and the membership of users in groups. The special principal 'public' can be used to indicate that any user or group has a particular access permission, thereby making it easier to specify that anonymous access is allowed.
The rules specified in this module will determine the level of access to a resource for specific users and groups. There are two mechanisms for including access control information via the eml-access module: 1) Each top-level resource module (eml-dataset, eml-literature, eml-software, and eml-protocol) includes an optional <access> element that is used to define the default access control at the resource level for all metadata and data in the EML package. If this access element is ommitted from the document, then by definition the package submitter should be given full access to the package but all other users should be denied all access. 2) Exceptions for particular data components of the package can be controlled at a finer grain by using an access description in the <additionalMetadata> element that points at a particular <distribution> element by referencing its unique id. An access control document may be defined, or referenced, from this location, and the <describes> element is used to point to the distribution that is to be controlled via its "id" attribute. When access control rules are specified this way, they apply to the data in the distribution element, and not the metadata. Thus, it controls access to the content of the <inline> element, as well as resources that are referenced by the <online/url> and <online/connection> elements. These exceptions to access to particular data resources are applied after the default access rules from (1) are applied, so they effectively override the default rules when they overlap. Any access rules that are specified in locations other than the top-level 'access' element or in 'additionalMetadata' pointing at only a distribution id are completely ignored. For example, rules found in '/eml/dataset/methods/methodStep/citation/access' would be completely ignored.
For describing access to different data entities, one can either provide multiple <describes> elements within a single additionalMetadata element, or provide multiple additionalMetadata elements, each of which describes access exceptions for a particular distribution. Note that each 'additionalMetadata' element can only contain one child element besides the describes tags (e.g., only one <access> element).
The values that can be assigned to the <permission> element are: "read", "write", "changePermission", and "all". Users given read permission can view the resource; write can make changes to the resource excluding changes to access rules; changePermission can change access rules; and all has all of read, write, and changePermission.
An example is given below, with non-critical sections elided:
<eml> <dataset> <access authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org" order="allowFirst"> <allow> <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal> <permission>read</permission> <permission>write</permission> <allow> </access> ... </dataset> <additonalMetadata> <describes>entity123</describes> <describes>entity234</describes> <access authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org" order="allowFirst"> <deny> <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal> <permission>write</permission> </deny> </access> </additionalMetadata> <eml>In this example, the overall default access is for the user alice to be able to read and write all metadata and data, but nobody else has any access beside the submitter. However, for entity123 and entity234, there is an additional rule saying that user alice does not have write permission. The net effect is that alice can read and make changes to the metadata, but can only read the two data entities.
The eml-access module, like other modules, may be "referenced" via the <references> tag. This allows an access control document to be described once, and then used as a reference in other locations within the EML document via its ID.
In summary, access rules can be applied in two places in an eml document, and all other 'access' elements in the document are completely ignored. Default access rules are established in the top 'access' element for the main eml resource (e.g., "/eml/dataset/access"). These default rules can be overridden for particular data entities by providing an additional "access" element in <additionalMetadata> with a <describes> element that points at the id of the distribution for the data entity.
Recommended Usage: | all data where controlling user access to the dataset is an issue |
Stand-alone: | yes |
Imports: | eml-documentation, eml-resource |
Imported By: | |
View an image of the schema: | eml-access image |
Element Definitions: |
|||||||||||||||||||||||||||||||||||||||||||
access | This element has no default value. | ||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The access element contains a list of rules that define the level of access for a given data package, including both metadata and data. Because the access element is declared to be of complex type 'AccessType', an instance must contain the elements defined for accessType. |
||||||||||||||||||||||||||||||||||||||||||
allow | This element has no default value. | ||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The allow element indicates that a particular user or group is granted the defined permission. |
||||||||||||||||||||||||||||||||||||||||||
deny | This element has no default value. | ||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The deny element indicates that a particular user or group is not granted the defined permission. |
||||||||||||||||||||||||||||||||||||||||||
principal | This element has no default value. | ||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The principal element defines the user or group to which the access control rule applies. The users and groups must be defined in the authentication system described in the authSystem element. The special principal 'public' can be used to indicate that any user or group has a particular access permission, thereby making it easier to specify that anonymous access is allowed. |
||||||||||||||||||||||||||||||||||||||||||
permission | This element has no default value. | ||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The permission that is being granted or denied to a particular user or group for a given resource. The list of permissions come from a predetermined list: 'read' (allow/deny viewing of the resource), 'write' (allow/deny modification of the resource excluding access rules), 'changePermission' (ability to modify access rules) and 'all' (allow all of read, write, and changePermission). This element also allows other permission values that may be applicable to some other authentication systems but are not defined in this specification (if these other values are used, access rule enforcement is indeterminate outside of the originating system). |
||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||
Attribute Definitions: |
|||||||||||||||||||||||||||||||||||||||||||
id | |||||||||||||||||||||||||||||||||||||||||||
Type: res:IDType Use: optional |
|||||||||||||||||||||||||||||||||||||||||||
system | |||||||||||||||||||||||||||||||||||||||||||
Type: res:SystemType Use: optional |
|||||||||||||||||||||||||||||||||||||||||||
scope | |||||||||||||||||||||||||||||||||||||||||||
Type: res:ScopeType Use: optional Default value: document |
|||||||||||||||||||||||||||||||||||||||||||
order | |||||||||||||||||||||||||||||||||||||||||||
Use: optional Default value: allowFirst |
|||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||
Derived from: xs:string (by xs:restriction) Allowed values:
|
The order attribute defines which rules should be applied first to obtain the desired access control. The acceptable values are 'allowFirst' and 'denyFirst'. If 'allowFirst' is specified, then all 'allow' rules are processed, and then overridden by all 'deny' rules. If 'denyFirst' is specified, then all 'deny' rules are processed, and then overridden by all 'allow' rules. This allows users to efficiently express their desired rules. |
||||||||||||||||||||||||||||||||||||||||||
authSystem | |||||||||||||||||||||||||||||||||||||||||||
Type: xs:string Use: required |
The authentication system determines the set of principals (users + groups) that can be used in the access control list, and the membership of users in groups. This element is intended to provide a reference to the authentication system that is used to verify the user or group. This reference is typically in the form of a URI, which includes the connection protocol, Internet host, and path to the authentication mechanism. |
||||||||||||||||||||||||||||||||||||||||||
Complex Type Definitions: |
|||||||||||||||||||||||||||||||||||||||||||
AccessType | |||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The access element contains a list of rules that define the level of access for a given data package, including both metadata and data. The access element must contain the elements defined in the AccessType type. |
||||||||||||||||||||||||||||||||||||||||||
AccessRule | |||||||||||||||||||||||||||||||||||||||||||
Content of this field: | Description of this field: | ||||||||||||||||||||||||||||||||||||||||||
|
The AccessRule type defines a list of users that are derived from a particular authentication system (such as an LDAP directory), whether the user or group is allowed or denied access, the extent of their access (read, write , or changePermission access). |
||||||||||||||||||||||||||||||||||||||||||
Simple Type Definitions: |
|||||||||||||||||||||||||||||||||||||||||||
Group Definitions: |
Web Contact: jones@nceas.ucsb.edu