i2scim

i2scim Access Control

Introduction

i2scim uses a JSON configuration file to specify access control policy in the form of access control instructions or ACIs. The ACI format used is inspired by LDAP access control models but has been altered to support HTTP and SCIM. See LDAP Access Control Model for LDAPv3. The model has been adapted to JSON format and removes the “compare” right which does not translate to HTTP.

Example JSON ACIs:

[
  {
    "path": "/Users",
    "name": "Users can read self except userType",
    "targetAttrs": "*,-userType,-ims",
    "rights": "read,search",
    "actors": [
      "self"
    ]
  },
  {
    "path": "/Users",
    "name": "Allow default access to names and email addresses of Users",
    "targetFilter": "meta.resourceType eq User",
    "targetAttrs": "username,displayName,emails,name,phoneNumbers",
    "rights": "read",
    "actors": [
      "any"
    ]
  }
]

An ACI is an Access Control Instruction expressed as a JSON object that has the following attributes:

Notes on rights:

ACI Evaluation Processing:

  1. When multiple ACIs apply to a SCIM entity, acis are applied in order of longest path first. The operation proceeds on the first aci that permits the operation. The attributes permitted in the operation are the merged targetAttrs list from all matched ACIs.
  2. An aci specified at a certain path applies to the path and any potential child nodes. For example / applies to the entire server whereas /Users applies to all user resources, and /Users/<id> applies to a specific resource.
  3. If targetfilter and targetattrs specified, both must be satisfied
  4. For read, create, modify (PUT or PATCH), targetAttr clauses may silently limit what may be changed or added with the targetattrs parameter. In such cases, the unauthorized attributes are ignored and the operation may proceed assuming the result matches resource schema restrictions (e.g. has values for required attributes). Note that for PATCH requests, a specific modify will return ‘Unauthorized’ if the modified attribute is not allowed.
  5. targetFilter processing: For a SCIM Create, targetFilter is applied to the new resource to be created. For all other operations, the filter is applied to the existing resource before the operation. When no objects match the targetFilter, a NotFound error is thrown.
  6. When a SCIM filter parameter is specified and no search right is allowed for the path, the server will return ‘Unauthorized’ or HTTP Status 404.

The server reads ACI configuration from a JSON file specified by the system property scim.security.acis.path. The default location is schema/acis.json.

Example acis.json:

{
  "acis": [
    {
      "path": "/Users",
      "name": "Self and employee access to read information",
      "targetAttrs": "*,-password",
      "rights": "read, search, compare",
      "actors": [
        "self",
        "filter=employeeNumber pr"
      ]
    },
    {
      "path": "/",
      "name": "Administrators can read, search, compare all records",
      "targetAttrs": "*",
      "rights": "read, search, compare",
      "actors": [
        "filter=groups eq TeamLeaderGroup",
        "role=admin"
      ]
    },
    {
      "name": "Allow unauthenticated access to names and email addresses of Users",
      "targetFilter": "meta.resourceType eq User",
      "targetAttrs": "username,displayName,emails,name,phoneNumbers",
      "rights": "read, search, compare",
      "actors": [
        "any"
      ]
    }
  ]
}
Notes performence (using filters and groups):

To use a group defined in the local SCIM server, use a filter with the groups attribute associated with the subjects local User resource. In general, for improved performance populate externally authorized entities (e.g. OpenID Connect, OAuth) with roles calculated by an Identity Provider. In general having an Identity Provider calculate group memberships once at authorization time is an order of magnitude faster than calculating group membership on a per API access basis.