Federated roles

[dbauszus-glx]

Roles need to be federated in a tree structure for fine grained access to resources.

Regions may be nested. A locale for London could be based on a locale for the UK which in turn could be based on a locale for Europe.

Roles need to reflect the depth of access to these nested regions.

Different brands / themes may accessible on these nested regions.

For example demographics or financial information could be two themes which are available on the different nested geographic locales.

Functionality can be limited by further roles, like viewer or editor.

This can not work by combining roles eg. europe-uk-london-demographics-editor as there would be an exponential number of possible combinations.

This can only work in a object structure.

"europe": {
  "demographics": true,
  "editor": true,
  "viewer": true,
  "UK": {
    "financial": true
    "London": true
  }
}

Roles apply to the same level or down the tree from siblings.

[RobAndrewHurst]

Roles

Here is a current breakdown of how we could use the tree structure to expand the roles.

The tree structure can be used to break up roles to more manageable levels. This can help both the config developer as well as the
admin users that will manage a system at scale.
It also provides a more clear break down of what a user's roles will look like per layer.

Possible configuration:

At the very top level of the workspace we could define the different level{n}'s of roles.
After that level2 can exist in layers in parts of a layer potentially.

• level1 - Should be a unique value that is not assigned in more than one place.
  • ie: A locale should only have 1 level1 role.
• level2 - A unique value that can be in multiple level1's
• level 3 - tbc

Note

Workspace Config

{
  "templates": [],
  "locales": {},
  "roles": {
    "level1": {
      "name": "country",
      "values": ["South Africa", "UK", "Germany"]
    },
    "level2": {
      "name": "brand",
      "values": ["KFC", "YUM", "BK"]
    }
  }
}

Note

locales (w/layers) Config

{
  "South Africa": {
    "roles": {
      "level1": {
        "South Africa": true
      }
    },
    "layers": {
      "shoppertowns": {
        "roles": {
          "level2": {
            "YUM": true,
            "BK": {
              "edit": true
            }
          }
        }
      }
    }
  },
  "UK": {
    "roles": {
      "level1": {
        "UK": true
      }
    },
    "layers": {
      "shoppertowns": {
        "roles": {
          "level2": {
            "YUM": false,
            "BK": {
              "dataset": "reduced"
            },
            "KFC": {
              "dataset": "full"
            }
          }
        }
      }
    }
  },
  "Germany": {
    "roles": {
      "level1": {
        "Germany": true
      }
    },
    "layers": {
      "shoppertowns": {
        "roles": {
          "level2": {
            "YUM": false,
            "BK": {
              "dataset": "full"
            },
            "KFC": {
              "dataset": "reduced"
            }
          }
        }
      }
    }
  }
}

  User (Rob👨)
    ├── South Africa <-- level1
    │   └── BK <-- level2
    ├── UK
    │   └── KFC
    └── Germany
        ├── YUM
        └── BK

const role = {
  South Africa: {
    BK: true
  },
  UK: {
    KFC: true
  },
  Germany: {
    YUM: true,
    BK: true
  }
};

This is a table breaking down what Rob will have access to.

Country	Brand	Access	Notes
South Africa	YUM	Yes ✅	Regular access
South Africa	Burger King	Yes ✅	Edit permissions
South Africa	KFC	No ❌	No access defined
UK	YUM	No ❌	Explicitly set to false
UK	Burger King	Yes ✅	Reduced dataset access
UK	KFC	Yes ✅	Full dataset access
Germany	YUM	No ❌	Explicitly set to false
Germany	Burger King	Yes ✅	Full dataset access
Germany	KFC	Yes ✅	Reduced dataset access

Caution

There are things to consider with the tree structure.
How do we deal with conflicting roles?

User with conflicting permissions:

  User
    └── Germany
        ├── YUM
        ├── KFC
        └── BK

{
  "Germany": {
    "roles": {
      "level1": {
        "Germany": true
      }
    },
    "layers": {
      "shoppertowns": {
        "roles": {
          "level2": {
            "YUM": {
              "edit": true
            },
            "KFC": {
              "edit": false
            },
            "BK": {
              "edit": true
            }
          }
        }
      }
    }
  }
}

The above is a problem because how can we know what property to apply if a user has all three.

• I would say that we would need to keep the roles properties to be quite basic in nature. ie just providing access.
  • This however does provide some technical challenges.

[jfitzpatrick17]

The requirements for this are as followed:

There is an umbrella company who has 3 brands - Brand A, Brand B and Brand C. These brands operate across the world in lots of different countries. Some users only need to see the data for one brand and one country. However there are also a number of users who need to be able to see multiple brands (switch between them) and multiple countries. There is also an edit/read access to one data layer, only users with the edit role can change information on this layer.

As an example:

• User 1 needs to be able to switch between Brand A and B in Country D and Country E. They can edit the stores layer
• User 2 needs to be able to switch between brands A, B and C in country F and G. They can't edit the stores layer

[dbauszus-glx]

Any solution must be backwards compatible and should be build on the core concept of [template] object merging.

A locale can defined as literal in the workspace.locales or through templates. The workspace.locale is the base for any locale in the workspace.locales.

It is not feasible to create combination locales [ie europe-brand_a]. With multiple tiers and multiple options on each tier the number of possible combinations would quickly become unmaintanable.

Nesting must not be limited to a tier. Nesting of locales can be achieved by providing a locales[] array in a locale. Any of the locales defined in the array are available to be merged. eg The brand_a and b locales are available for the us regional locale. The layers in the brand locales will be merged into the mapview locale in the mapp library. Brand locales will be accessible in accordance to their roles configuration. A locale may also have an extent which will be merged into the locale requesting an additional local configuration. For example the Europe locale has access to the UK locale which in turn has access to a set of brand locales.

  "locale": {
    "layers": {
      "common_layer": {}
    }
  },
  "locales": {
    "us": {
      "roles": {
        "us": {}
      },
      "extent": {},
      "layers": {},
      "locales": [
        "brand_a_locale",
        "brand_b_locale"
      ]
    },
    "europe": {
      "roles": {
        "europe": {}
      },
      "extent": {},
      "layers": {},
      "locales": [
        "UK_locale",
        "brand_b_locale",
        "brand_c_locale"
      ]
    }
  }

The templates object to support the locales[] array would look like this.

  "templates": {
    "query": {
      "roles": {}
    },
    "common_layer": {},
    "finance_layer": {
      "roles": {}
    },
    "brand_a_layer": {
      "roles": {}
    },
    "brand_b_layer": {
      "roles": {}
    },
    "brand_c_layer": {
      "roles": {}
    },
    "brand_a_locale": {
      "roles": {
        "brand_a": {}
      },
      "layers": {
        "brand_a_layer": {}
      }
    },
    "brand_b_locale": {
      "roles": {
        "brand_b": {}
      },
      "layers": {
        "brand_b_layer": {}
      }
    },
    "brand_c_locale": {
      "roles": {
        "brand_c": {}
      },
      "layers": {
        "brand_c_layer": {}
      }
    },
    "UK_locale": {
      "roles": {
        "UK": {}
      },
      "extent": {},
      "layers": {
        "brand_c_layer": {}
      }
    }
  }

Roles may be defined in literals or templates. However a role structure may only be retrieved from literals. Loading every nested template from source would put too much stress on the workspace API. This can be enabled on a flag as file system [locale] templates are directly accessible and should never be cached.

A literal role structure can also be provided as workspace.roles. This provides backwards compatibility as the roles config would only be used if available with the lookup for roles as fallback.

  "roles": {
    "us": {
      "brand_a": {},
      "brand_b": {}
    },
    "europe": {
      "brand_b": {},
      "brand_c": {},
      "uk": {
        "brand_c": {}
      }
    },
    "brand_a": {},
    "brand_b": {},
    "brand_c": {}
  }

[dbauszus-glx]

This first task from this is to enable reload of the mapview. https://github.com/GEOLYTIX/xyz/issues/1921

[dbauszus-glx]

This is the second task to be addressed after we are able to reload the mapview. #1922

[jfitzpatrick17]

Requirement 2 - role management:

An umbrella company operates across multiple different countries and regions - individual users can be assigned to a country (locale) to see data about a single country or a region, allowing them to see data for multiple countries (locales).
Each region operates as a separate subsidiary of the umbrella company, and a 'power' regional user is responsible for managing user approvals and setting roles for any new users who belong to the corresponding region. A super admin sees everything and can assign a regional admin role and view all users and roles, but a regional admin can only grant user access for users in their region.

As an example:

• User A belonging to region 1 registers. Upon registration they should be able to specify that they belong to region 1. The power user for region 1 receives the email notification about user A's registration, can approve the new user and assign them a role(s). The power user for region 1 should only see the users for region 1 in the admin console.
• The power user for region 2 does not receive a notification, nor can they manage approvals for new region 1 users
• A super admin would see new registrations for both region 1 and region 2 users

[dbauszus-glx]

The check for nested roles has been implemented in the PR linked to this ticket. #2099

@jfitzpatrick17 This will allow us to build an interface in a custom admin view.

[dbauszus-glx]

@RobAndrewHurst Role profiles can already be implemented in a custom view interface.

You can add a roles array to the workspace.roles. If selected in a custom interface any roles in the roles array will be appended to the User.roles array.