Introduction

In use.id, access to resources is determined based on Solid identity tokens and access control rules.

Solid identity tokens

A Solid identity token can contain identifiers for the following aspects. These aspects can be used what access is allowed.

sub The subject in the token. For example, https://use.id/tom or https://webid.karamel.career/
azp The authorized party in the token (i.e. the app for which the user got the token). For example, https://webid.karamel.career/ . If it is a M2M token, the azp claim equals the sub claim.
iss The issuer of the token. For example, https://idp.use.id

Access allow control rules

In use.id, nothing is allowed unless an access rule says it is allowed.

In general, access allow rules generally consist of three parts:

What resource(s) the rule applies to (e.g. all resources for “Tom” of the “Project” type)
What conditions should be met (e.g. the sub claim in the token must be https://use.id/tom)
What kind of access modes should be allowed (e.g. read)

A detailed explanation of access allow rules in Distri

Scoping resources

In Distri, access can be allowed on two levels:

A piece of data
A combination of data type and data subject

In case there are access rules defined on both levels for a given data piece, the access rules are added to eachother.

For example, suppose you have the following registrations:

file-karamel   Type: Project   Subject: Tom
file-linckr    Type: Project   Subject: Tom

And the following rules:

Rule type           | Data Type  |    Data Subject    |  Piece      |  sub           |  allowed modes
-----------------------------------------------------------------------------------------------------
subject_type_combo  | Project    |    Tom             |             |  use.id/john   |  read
piece               |            |                    | file-linckr |  use.id/john   |  write

Then the following access is allowed:

John can read file-karamel

John can read and write file-linckr

Conditions logic

Conditions can be made using relevant claims in a Solid identity token: sub, azp and iss.

A combination of these claims should be considered as a logical AND. If a claim should not be checked, the value must be NULL for that claim (i.e. NULL is the wildcard).

For the sub field, you cannot have a wildcard.

For example, suppose you have the following registrations:

file-karamel    Type: Project   Subject: Tom
file-linckr     Type: Project   Subject: Tom
file-useid      Type: Project   Subject: Tom
file-athumi     Type: Project   Subject: Tom

And the following access rules:

Piece         |  sub            |  azp              | iss         | allowed modes
-------------------------------------------------------------------------------
file-karamel  | use.id/john     | NULL              | NULL        | read
file-linckr   | use.id/john     | webid.linckr.com  | NULL        | read
file-useid    | use.id/john     | webid.use.id      | idp.use.id  | read
file-athumi   | webid.athumi.be | NULL              | idp.use.id  | read
file-athumi   | NULL            | webid.athumi.be   | idp.use.id  | read ---> not possible, sub may not be wildcarded!!!

Behaviour if multiple rules for the same level and same scope

If multiple rules are defined for the same resource, access should work additive.

For example, suppose you have the following registrations:

file-karamel    Type: Project   Subject: Tom

and the following rules

Piece         |  sub            |  azp              | iss         | allowed modes
-------------------------------------------------------------------------------
file-karamel  | use.id/john     | NULL              | NULL        | read
file-karamel  | use.id/john     | webid.linckr.com  | NULL        | write

And suppose the token is for sub:use.id/john and azp:webid.linckr.com

In this case, the token grants both read and write access to file-karamel

Access modes and meaningfulness

There are three access modes that can be applied to two levels.

read can read data
write can write data
create can create new resources for a given type and subject

Not all combinations of modes and levels are meaningful. Please refer to the table below

Modes/levels  | piece           | subject_type_combo
----------------------------------------------------
Read          | meaningful      | meaningful
Write         | meaningful      | meaningful
Create        | not meaningful  | meaningful

Algorithm

The following algorithm is applied to evaluate access to a resource:

Input: parameter_solid_token + parameter_resource_id + parameter_operation

Get all access rules relevant to the data piece
  Query:
  SELECT *
  FROM allowed_access_rule LEFT JOIN data_type LEFT JOIN data_subject LEFT JOIN data_piece
  WHERE 
    data_piece.external_id = parameter_resource_id 
    AND 
    allowed_access_rule.allowed_url_encoded_subject_identifier = parameter_solid_token.sub
    AND
    allowed_access_rule.allowed_access_mode = parameter_operation

For each rule:
  If format of rule is sub, NULL, NULL
    If match with sub in token
     Log, grant access, end
     
  If format is sub, azp, NULL
    If match with sub and azp in token
     Log, grant access, end
     
  If format is sub, NULL, iss
    If match with sub and iss in token
      Log, grant access, end
      
  If format is sub, azp, iss
    If match with sub, azp and iss
      Log, grant access, end
  
If no rules could be matched: end, error and log