# Module Documentation: eml-access | Back to EML Contents

### The eml-access module - Access control rules for resources

The eml-access module describes the level of access that is to be allowed or denied to a resource for a particular user or group of users, and can be described independently for metadata and data. The eml-access module uses a reference to a particular authentication system to determine the set of principals (users or groups) that can be specified in the access rules. The special principal 'public' can be used to indicate that any user or group has access permission, thereby making it easier to specify that anonymous access is allowed.

There are two mechanisms for including access control via the eml-access module:

The top-level "eml" element may have an optional <access> element that is used to establish the default access control for the entire EML package. If this access element is omitted from the document, then the package submitter should be given full access to the package but all other users should be denied all access. To allow the package to be publicly viewable, the EML author must explicitly include a rule stating so. Barring the existence of a distribution-level <access> element (see below), access to data entities will be controlled by the package-level <access> element in the <eml> element.

Exceptions for particular entity-level components of the package can be controlled at a finer grain by using an access description in that entity's physical/distribution tree. When access control rules are specified at this level, they apply only to the data in the parent distribution element, and not to the metadata. Thus, it will control access to the content of the <inline> element, as well as resources that are referenced by the <online/url> and <online/connection> paths. These exceptions to access for particular data resources are applied after the default access rules at the package-level have been applied, so they effectively override the default rules when they overlap.

In previous versions of EML access rules for entity-level distribution were contained in <additionalMetadata> sections and referenced via the <describes> tag. Although in theory these could have referenced any node, in application such node-level access control is problematic. Since the most common uses of access control rules were to limit access to specific data entities, the access tree has been placed there explicitly in EML 2.1.0.

Access is specified with a choice of child elements, either <allow> or <deny>. Within these rules, values can be assigned for each <principal> using the <permission> element. Users given "read" permission can view the resource; "write" allows changes to the resource excluding changes to the access rules; "changePermission" includes "write" plus the changing of access rules. Users allowed "all" permissions; may do all of the above. Access to data and metadata is affected by the order attribute of the <access> element. It is possible for a deny rule to override an allow rule, and vice versa. In the case where the order attribute is set to "allowFirst", and there are rules similar to the following (with non-critical sections deleted):

      <deny>
        <principal>public</principal>
        <permission>read</permission>
      </deny>
      <allow>
        <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal>
        <permission>read</permission>
      </allow>

the principal "uid=alice ..." will be denied access, because it is a member of the special "public" principal, and the deny rule is processed second. For this allow rule to truly allow access to that principal, the order attribute should be set to "denyFirst", and the allow rule will override the deny rule when it is processed second.

An example is given below, with non-critical sections deleted:

      <eml>
          <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>
          ...
          ...
          <dataTable id="entity123">
          ...
            <physical>
            ...
              <distribution>
              ...
                <access id="access123"
                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>
             </distribution>
           </physical>
          </dataTable>
          <dataTable id="entity234">
            ...
            <physical>
            ...
              <distribution>
                ...
                <access>
                  <references>access123</references>
                </access>
              </distribution>
            </physical>
          </dataTable>
          ...
        </dataset>
      <eml>

In this example, the overall default access is to allow the user=alice (but no one else) to read and write all metadata and data. However, under "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 cannot make changes to the two data entities. In addition, Alice cannot change these access rules; although the submitter can.

This example also shows how 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. Default access rules are established in the top <access> element for the main eml document (e.g., "/eml/access"). These default rules can be overridden for particular data entities by adding additional <access> elements in the physical/distribution trees of those entities.

## Module details

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:
Type: AccessType
| The access element contains a list of rules defining permissions for this resource. For descriptions of the individual elements, see the AccessType.The permission rules defined here can be overridden by rules added to an access tree in the PhysicalDistributionType at the entity level. Example(s): See the description of the AccessType.
#### allow | This element has no default value.
Content of this field: | Description of this field:
Type: AccessRule
| The allow element indicates that a particular user or group is granted the defined permission. Example(s): allow
#### deny | This element has no default value.
Content of this field: | Description of this field:
Type: AccessRule
| The deny element indicates that a particular user or group is not granted the defined permission. Example(s): deny
#### principal | This element has no default value.
Content of this field: | Description of this field:
Type: res:NonEmptyStringType
| 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. Example(s): public uid=alice,o=LTER,dc=ecoinformatics,dc=org
#### 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 or deny viewing of the resource, 'write' - allow or deny modification of the resource (except for access rules), 'changePermission' - modifications including access rules, and 'all' - all of the above. 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). Example(s): read
## 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: allowFirst denyFirst
| To obtain the desired access control, use the order attribute to define which rules should be applied first. 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. Example(s): allowFirst
#### 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. Example(s): ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org
## Complex Type Definitions:
#### AccessType |
Content of this field: | Description of this field:
Elements: | Use: | How many:
A choice of (
A choice of (
allow | required |
OR
deny | required |
)
res:ReferencesGroup |  |
)
Attributes: | Use: | Default Value:
id | optional
system | optional
scope | optional | document
order | optional | allowFirst
authSystem | required
| The access element contains a list of rules that define the level of access for a resource. There are two uses of access trees: to control access to either metadata or data. To control access to metadata use the eml/access tree. By default, these rules will also apply to the contained data. To override the default controls for specific data entities, use the access element available in the entity's physical/distribution tree. A combination of access trees and their "order rules" (see description of the "order" attribute) allows EML authors to have fine control over permissions for individuals and groups.
#### AccessRule |
Content of this field: | Description of this field:
Elements: | Use: | How many:
A sequence of (
principal | required | unbounded
permission | required | unbounded
)
| 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