Policy Format
Overview
Policies for a service are defined in JSON.
The JSON file consists of the section "policies" and the optional sections "properties", and "restrictions".
{
"policies": [],
"properties": {}, //optional
"restrictions": {} //optional
}The order of these properties do not matter.
If you don’t need them, you can either omit the optional properties or you assign an empty object {}.
|
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 |
Policies
The "policies" array defines all policies that apply for a service.
A single policy is a combination of layers, roles, and optional restrictions.
To grant access to layers with IDs 0 and 1 for role role_division_42 a policy would look like this:
{
"policies": [
{
"layers": ["0", "1"],
"roles": ["role_division_42"]
}
]
}Layers
The "layers" property of a "policies" item is an array of layer IDs of a particular service like a map service or feature service.
Layer IDs can be listed explicitly, as interval, or as "*" which would grant access to all layers.
The following example defines two policies, one applicable to the layers 0 and 3 through 5, and another policy applicable to all layers present on the given service:
{
"policies": [
{
"layers": ["0", "3-5"],
"roles": ["enhancedSecurity_any"]
},
{
"layers": ["*"],
"roles": ["role_division_42"]
}
]
}Roles
The "roles" property of a policy is an array of role IDs.
A role ID refers to a particular portal group assigned to requesting users.
If a user authenticates via ArcGIS Enterprise, the role IDs defined in a policy are matched against the user’s portal group IDs.
Example: If a user is assigned to portal group "Division 42" and the according group ID in portal is 41477fa98f444444855e1e0b7b132b45, the following policy would grant access to layer 0 of a service:
{
"policies": [
{
"layers": ["0"],
"roles": ["41477fa98f444444855e1e0b7b132b45"]
}
]
}You can use the following role IDs to grant access independent of specific user roles:
-
enhancedSecurity_any -
enhancedSecurity_authenticated
If a policy is bound to the role enhancedSecurity_any it gets applied to any user, no matter what roles she is assigned to or if she was even authenticated by ArcGIS Enterprise.
To make policies work that refer to this role the map service must be made publicly accessible so that anonymous users can connect to it.
If the role enhancedSecurity_authenticated is used, the policy applies to all users who are authenticated at ArcGIS Enterprise.
In the example below, all users are able to access layer 0, but only users authenticated with ArcGIS Enterprise are able to access both, layers 0 and 1.
{
"policies": [
{
"layers": ["0"],
"roles": ["enhancedSecurity_any"]
},
{
"layers": ["1"],
"roles": ["enhancedSecurity_authenticated"]
}
]
}Restrictions
Restrictions limit access to layers.
The "restrictions" array of a policy contains a list of IDs that refer to elements in the top-level "restrictions" object of the JSON file.
In the following example the policy refers to the restriction "california" that is defined further down in the file.
{
"policies": [
{
"layers": ["0"],
"roles": ["${guests}"],
"restrictions": ["california"]
}
],
"restrictions": {
"california": {
"type": "spatial",
"featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/USA/FeatureServer/0",
"featurequery": "state = 'California'",
"operation": "intersect"
}
}
}See the section Restrictions, below, for more details on available restriction types.
Properties
The "properties" array contains key-value-pairs, where the values have to be strings.
The keys must start with a letter and only consist of the characters a-z, A-Z, 0-9 as well as '_' (underscore) and '-' (dash).
By referencing the key of a property as ${property_name} in other properties it can help to reuse values.
Properties can also be used to give values descriptive names.
In the following example the role ID 41477fa98f444444855e1e0b7b132b45 is assigned to the property "guests".
It then can be referenced in a policy:
{
"policies": [
{
"layers": ["0"],
"roles": ["${guests}"]
}
],
"properties": {
"guests": "41477fa98f444444855e1e0b7b132b45"
}
}Restrictions
A policy may only give limited access to layers by adding restrictions to it.
In the following example the policy refers to the restriction "california" defined in the top-level "restrictions" property.
{
"policies": [
{
"layers": ["0"],
"roles": ["${guests}"],
"restrictions": ["california"]
}
],
"restrictions": {
"california": {
"type": "spatial",
"featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/USA/FeatureServer/0",
"featurequery": "state = 'California'",
"operation": "intersect"
}
}
}Names used for a restriction (california in the example above) must only consist of the letters a-z, A-Z, 0-9 as well as '_' (underscore) and '-' (dash).
They must start with a letter.
You can define the following types of restrictions:
- Spatial
-
Limit access to a certain geographical region
- Field
-
Limit access to certain fields of a layer
- Feature
-
Limit access to certain features of a layer
|
Restrictions always apply to all layers referenced in a policy element. When you want to apply different restrictions to different layers, you have to use multiple policy elements. |
Spatial restrictions
Spatial restrictions define a geographical region that a user is allowed to get data for. When a spatial restriction is applied to a service request the response will only contain data for the specified region. A spatial restriction defines which part of a map image will be visible. If the user requests feature data like in a query operation, the resulting feature set is limited to the features that lie within (or intersect) the definied region.
You can define the spatial restriction by referencing a geometry provided by an ArcGIS feature service. The reference consists of the following information:
type-
Restriction type, must be
"spatial". featuretypeurl-
URL referencing a feature service layer.
Besides an absolute URL, you can also use relative URLs, matching the pattern/<folder>/<service>/FeatureServer/<layerid>.
When using relative URLs, also non-public feature services can be used. featurequery-
Definition expression (or "WHERE clause") to query features which defined the permitted area.
operation-
Either
"intersect"or"within".
Defines whether features intersecting the permitted area will also be part of the result (intersect) or only those features that lie completely inside the region (within).
This setting has no effect for map services, since for those the map images are always clipped along the permitted region.
The following example defines a policy granting access to all data of layer 1 that lies inside or intersects the features of https://gis.example.com:6443/arcgis/rest/services/RestricionAreas/FeatureServer/0 where area_name matches 51.
{
"policies": [
{
"layers": ["1"],
"roles": ["${guests}"],
"restrictions": ["area51"]
}
],
"restrictions": {
"area51": {
"type": "spatial",
"featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/RestricionAreas/FeatureServer/0",
"featurequery": "area_name = '51'",
"operation": "intersect"
}
}
}A spatial restriction defined for one layer of a map service will be applied to all layers of this service. For feature services, the spatial restriction can be applied for a layer individually.
Field restrictions
Using field restrictions you can hide certain fields of layers or tables from the user. The actual fields to hide need to be specified as a list of field names.
Create a field restriction by adding a new entry to the top-level "restrictions" property of the JSON file.
It must have the following properties:
type-
Restriction type, must be
"field". hiddenfields-
An array of field names that should not be accessible for users.
The following policy defines a restriction for the fields of layer 42.
The fields named DIVISION_SIZE and DIVISION_REVENUE will not be accessible for anonymous users.
{
"restrictions": {
"secret_division_data": {
"type": "field",
"hiddenfields": ["DIVISION_SIZE", "DIVISION_REVENUE"]
}
},
"policies": [
{
"layers": ["42"],
"roles": ["enhancedSecurity_any"],
"restrictions": ["secret_division_data"]
}
]
}Feature restrictions
If only a subset features of a layer or table should be accessible for a user, you can use feature restrictions. Feature restrictions are defined as a query expression ("definition query") that defines the features that a person can access.
Create a feature restriction by adding a new entry to the top-level "restrictions" property of the JSON file.
It must have the following properties:
type-
Restriction type, must be
"feature". query-
A query expression in the SQL syntax supported by ArcGIS Server, like in the layer restrictions in ArcMap or ArcGIS Pro.
The following policy defines a restriction for the features of layer 42.
Any authenticated user is granted to access features only, where the value of the field DIVISION_NAME equals North.
{
"restrictions": {
"northern_division": {
"type": "feature",
"query": "DIVISION_NAME = 'North'"
}
},
"policies": [
{
"layers": ["42"],
"roles": ["enhancedSecurity_authenticated"],
"restrictions": ["northern_division"]
}
]
}|
When a user is assigned to more than one group, and for several of these groups access to a certain layer is permitted, then access is granted but enforces the union of all associated restrictions. This means:
|