Policies

Policies are defined in JSON format and specify the access permissions for a service.

A policy file has the following structure:

{
  "policies": [],         (1)
  "fallbackPolicies": [], (2)
  "restrictions": {},     (3)
  "properties": {}        (4)
}

1	List of policies for a service
2	optional: Policies that are used when no matching policy is found for a role assigned to a person
3	optional: Uniquely named restrictions that can be referenced in policies
4	optional: Uniquely named properties that can be referenced in policies

Auto-complete and syntax validation

The JSON format for policies definition as described here is also defined as JSON Schema. With this schema you can verify that the JSON file you write is valid. Furthermore, editors like Visual Studio Code can use that schema to provide examples, descriptions, and auto-completion when editing elements.

In the JSON file add the property "$schema" like this to enable auto-complete:

{
    "$schema": "https://raw.githubusercontent.com/conterra/secman-open-resources/1.0.0/schema/policies.schema.json",
    "policies": []
}

A copy of the JSON Schema is included in the security.manager for OGC distribution and available under [SECMAN_DIST]/resources/policies.schema.json. With this copy you can still use auto-complete and syntax validation even if you are working in an environment that doesn’t have access to https://raw.githubusercontent.com/conterra/secman-open-resources/…. To use this copy, change the value of $schema as follows:

{
    "$schema": "[SECMAN_DIST]/resources/policies.schema.json",
    "policies": []
}

Replace [SECMAN_DIST] by the directory’s actual path.

`policies`

List of all policies that apply when accessing a service.

Each policy is a combination of layers, roles, and optional restrictions:

"policies":[
  {
    "layers": ["layerA", "layerB"],                   (1)
    "roles": ["roleA", "roleB"],                      (2)
    "restrictions": ["restrictionA", "restrictionB"]  (3)
  }
]

1	Layers to which access is to be granted
2	Roles to which the policies applies
3	optional: Further restrictions on the layers for the given roles

`layers`

List of layer names or feature type names that a role should have access to.

Each entry must be a unique name of a layer or feature type. The expression “layers”: [“*”] includes all layers and feature types of a service.

For Web Feature Services (WFS), the name of a feature type is used. This must be specified without a namespace prefix. Refer to the limitations for feature types for WFS.

For Web Map Services (WMS), the name of a layer is used.

`roles`

List of roles to which the policy applies.

In addition to the roles of the identity provider, there are three predefined roles:

enhancedSecurity_any: This role applies to all persons.
enhancedSecurity_anonymous: This role applies to all not authenticated persons.
enhancedSecurity_authenticated: This role applies to all authenticated persons.

`restrictions`

References to additional restrictions that should be enforced when accessing a layer.

Using restrictions is optional. In restrictions, IDs of restrictions that apply to the policy can be referenced. The restrictions themselves are defined in the restrictions object at the top level of the JSON file.

The restrictions referenced in a policy always apply to all layers specified in this policy. If you want to define different restrictions for different layers, you must create separate policies for this purpose.

`fallbackPolicies`

List of fallback policies that are applied when no other policy can be found for the roles of a person.

Fallback policies are optional. By default, security.manager for OGC does not allow access if no policy can be found for a user’s roles. With fallback policies, you can change this behavior and allow this user group to access certain data.

Each entry within the fallbackPolicies defines a fallback policy. Within this fallback policy, the properties layers and restrictions known from policies can be used. The property roles must not be used.

"fallbackPolicies":[{
  "layers": ["layerA"],
  "restrictions": ["restrictionB"]
}]

Do not use fallbackPolicies together with policies for the enhancedSecurity_any role. The policies for enhancedSecurity_any apply to every user, so the fallbackPolicies are never applied.

`restrictions`

List of Uniquely named restrictions that can be referenced in policies and fallback policies.

A policy can restrict access to layers by assigning restrictions to them. It is defined as a key-value pair consisting of the name of the restriction (key) and an object that defines the restriction (value). The name of a restriction may only consist of the characters a-z, A-Z, 0-9, '_' (underscore), and '-' (hyphen). It must begin with a letter.

{
  "policies": [
    {
      "layers": ["layerA", "layerB"],
      "roles": ["roleA"],
      "restrictions": ["restrictionA"] (1)
    }
  ],
  "restrictions": { (2)
    "restrictionA": (3)
    {
      "type": "spatial", (4)
      // ...
    }
  }
}

1	Reference to a restriction within a policy
2	Object in which all restrictions are defined
3	Key of a restriction
4	Type of the restriction. Accepted values are `"spatial"` and `"readonly"`.

You can define the following types of restrictions:

Spatial: Restrict access to a spatial area
Editing: Prohibit editing of geometries and attributes

Spatial restriction

Spatial restrictions limit access to a spatial area. This area is defined in a GeoJSON file.

A spatial restriction contains the following properties:

"restrictions": {
  "europe-only": {               (1)
    "type": "spatial",           (2)
    "source": "europe.geojson",  (3)
    "spatialOperation": "within" (4)
  }
}

1	ID of the restriction.
2	Type of the restriction.
3	Name of the GeoJSON file containing the geometries for the spatial restriction.
4	WFS only, optional: Spatial operation for comparing the geometries with the features of a feature type.

type

Type of the restriction.

For spatial restrictions, the value must be "spatial".

source

Name of the GeoJSON file.

The geometries of the GeoJSON files define the allowed area of the spatial restriction. The file must be located in the same directory as the policy file and meet these requirements for geometries.

spatialOperation

Spatial operation that defines how the spatial restriction is applied to the features of a feature type.

Following operations are supported:

intersect: All features that intersect the geometry are returned. This is the default value.
within: Only features that lie completely within the geometry are returned.

Editing restrictions

Editing of Transactional Web Feature Services (WFS-T) can be allowed by granting full access to a role. This means that this role must be allowed access to all layers without restrictions.

If editing is to be prohibited for these roles, an editing restriction can be added:

{
  "policies": [
    {
      "layers": ["*"],
      "roles": ["roleA"],
      "restrictions": ["no-edit"] (1)
    }
  ],
  "restrictions": {
    "no-edit": { (2)
      "type": "readonly" (3)
    }
  }
}

1	full access for `roleA` is restricted by the editing restriction
2	id of the restriction
3	editing restrictions are of type `readonly`

This property only affects WFS-T with full access rights.

`properties`

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["${propertyA}"] (1)
        }
    ],
    "properties": { (2)
        "propertyA": "41477fa98f444444855e1e0b7b132b45" (3)
    }
}

1	Reference to a property within a policy
2	Object in which all properties are defined
3	A property consisting of a key-value pair

The properties element consists of key-value pairs that allow you to define values that you can reference by key elsewhere in this file. The values must be strings. The keys must begin with a letter and may only consist of the characters a-z, A-Z, 0-9, '_' (underscore), and '-' (hyphen). You can use the values in other elements by referencing them with ${key_name}. This way, you can give values descriptive names.