From 1a6cf58b6175935ce46c7e978ce3b8d235da1c52 Mon Sep 17 00:00:00 2001 From: Robert von Burg Date: Tue, 10 Jul 2018 17:11:19 +0200 Subject: [PATCH] [Project] writing privilege documentation --- .../documentation-privileges.html | 209 ++++++++++++++++++ .../www.strolch.li/documentation-runtime.html | 13 +- .../www.strolch.li/documentation.html | 4 +- 3 files changed, 223 insertions(+), 3 deletions(-) create mode 100644 li.strolch.website/www.strolch.li/documentation-privileges.html diff --git a/li.strolch.website/www.strolch.li/documentation-privileges.html b/li.strolch.website/www.strolch.li/documentation-privileges.html new file mode 100644 index 000000000..875780ecd --- /dev/null +++ b/li.strolch.website/www.strolch.li/documentation-privileges.html @@ -0,0 +1,209 @@ + + + + + + + + + + + + Strolch: Privileges + + + + + + + + + + + + +
+ +
+

Documentation: Privileges

+ +

This page discusses Privilege management in Strolch.

+
+ +
+ + +

No framework is complete without user management and privilege validation. The basic form would be Users and + Roles, and then validating that an authenticated user has a given role. In Strolch we go a step further: A + User has roles assigned, and each role has a set of Privileges. The privileges can overlap, a validation is + performed to make sure that the one role doesn't deny and another role allows a specific action.

+ +

As explained in the Privilege Configuration section, + users are defined in the PrivilegeUsers.xml file, and roles are defined in the PrivilegeRoles.xml + file.

+ +

Let's assume the following user and role definition:

+ + 
+<Users>
+  <User userId="1" username="jill" password="$PBKDF2WithHmacSHA512,10000,256$61646d696e$cb69962946617da006a2f95776d78b49e5ec7941d2bdb2d25cdb05f957f64344">
+    <Firstname>Jill</Firstname>
+    <Lastname>Someone</Lastname>
+    <State>ENABLED</State>
+    <Locale>en_GB</Locale>
+    <Roles>
+      <Role>AppUser</Role>
+    </Roles>
+    <Properties>
+      <Property name="realm" value="execution" />
+    </Properties>
+  </User>
+</Users>
+
+<Roles>
+  <Role name="AppUser">
+    <Privilege name="li.strolch.service.api.Service" policy="DefaultPrivilege">
+      <AllAllowed>true</AllAllowed>
+    </Privilege>
+    <Privilege name="li.strolch.model.query.StrolchQuery" policy="DefaultPrivilege">
+      <AllAllowed>true</AllAllowed>
+    </Privilege>
+    <Privilege name="li.strolch.search.StrolchSearch" policy="DefaultPrivilege">
+      <AllAllowed>true</AllAllowed>
+    </Privilege>
+  <Role>
+<Roles>
+
+ +

This configuration contains one user and one role. The user jill has the role + AppUser and the role AppUser has three privileges assigned.

+ +

Note how the user's password is configured similar to a unix password definition: Using the dollar sign + & first the hashing algorithm is configured (algorithm, iterations, key length), then the + salt, followed by the password hash.

+ +

Note: The password can also still be saved using two separate fields: a salt and password field. + This configuration will be immediately changed to the unix form, so won't be described + further here.

+ +

Further a user always has a firstname and last name. Optionally a locale can be set, otherwise the system + locale is used. The user's state must be defined as one of NEW, ENABLED, DISABLED, + EXPIRED or SYSTEM. A user can only authenticate/login with the state + ENABLED. A user can have any number of properties, which can then be used at runtime. A user + can also reference any number of roles, the assigned privilege can overlap, a global configuration mode + defines how duplicate privileges are handled.

+ +

Roles have a name and any number of Privilege definitions. A Privilege has a name, which in many + cases is the name of Java class/interface on which an action is being invoked. The policy value + defines which policy to use when evaluating the privilege access. The privilege definition is defined in the + PrivilegeConfig.xml and is the name of a class to call for privilege validation.

+ +

Further the privilege definitions can have a AllAllowed boolean flag, or any number of Allow + or Deny values. How these values are interpreted is defined in the policy implementation. A + policy takes three input parameters:

+
    +
  • PrivilegeContext → supplied by privilege and gives access to the + Certificate, thus identifying the user for which privilege access is to be validated. +
    • +
  • IPrivilege → Contains the privilege values: AllAllowed, + Allow and Deny
    • +
  • Restrictable → An interface from which the privilege name is retrieved, and the + associated value. The value is an object, and is cast to the relevant input in + the concrete privilege policy. +
    • +
+ +

The following privilege policies are already implemented:

+
    + +
  • DefaultPrivilege → simple policy where the passed Restrictable is expected to return a + String value, which is compared with allow and deny values. +
    • + + +
  • Internal: RoleAccessPrivilege → policy used for the internal privileges PrivilegeGetRole, + PrivilegeAddRole, PrivilegeModifyRole or PrivilegeModifyRole
    • +
  • Internal: UserAccessPrivilege → policy used for the internal privileges PrivilegeGetUser, + PrivilegeAddUser, PrivilegeRemoveUser, PrivilegeModifyUser, + PrivilegeAddRoleToUser, PrivilegeRemoveRoleFromUser, PrivilegeSetUserState, + PrivilegeSetUserLocale or PrivilegeSetUserPassword
    • +
  • Internal: UserAccessWithSameOrganisationPrivilege → Same as the + UserAccessPrivilege but expects the authenticated user to have a property organisation + and validates that the user being modified is in the same organisation. +
    • +
  • Internal: UsernameFromCertificatePrivilege → This policy expects a Restrictable + to return the certificate of another authenticated user and is used when modifying an + authenticated user, i.e. killing a session, or modifying its current state, e.g. locale + etc. +
    • +
  • Internal: UsernameFromCertificateWithSameOrganisationPrivilege → Same as UsernameFromCertificatePrivilege + but expects the authenticated user to have a property organisation and + validates that the user being modified is in the same organisation. +
    • +
+ +

Note: As a rule, the sequence is AllAllowed → Allow → + Deny → default deny

+ +

+ +
+ + + + +
+ + + + + + + + + + + + + + diff --git a/li.strolch.website/www.strolch.li/documentation-runtime.html b/li.strolch.website/www.strolch.li/documentation-runtime.html index 23a072f1c..23a5df6ea 100644 --- a/li.strolch.website/www.strolch.li/documentation-runtime.html +++ b/li.strolch.website/www.strolch.li/documentation-runtime.html @@ -144,7 +144,7 @@ moment to read the JavaDoc (or source code) for the component in question to see how it is configured.

-

Privilege Configuration

+

Privilege Configuration

In Strolch authentication and authorization is baked in. To open a transaction, and thus access the Strolch model, a Certificate object is required, which means the user has been authenticated and possibly @@ -163,6 +163,17 @@

  • <PersistenceHandler> configures the persistence of the roles and users
    • +
  • <UserChallengeHandler> configures a challenge handler so that a user + can reset their password. The default + challenge handler is the li.strolch.privilege.handler.MailUserChallengeHandler + which sends a challenge to the user's defined + e-mail address. +
    • +
  • <SsoHandler> the SSO Handler is used to implement a SingleSignOn and + can be used to start a session using a LDAP token, etc. + There is no default implementation as this is project + specific. +
  • <Policies> configures the available privilege policies at runtime, the name diff --git a/li.strolch.website/www.strolch.li/documentation.html b/li.strolch.website/www.strolch.li/documentation.html index e4a8c2f0a..1a0ab897a 100644 --- a/li.strolch.website/www.strolch.li/documentation.html +++ b/li.strolch.website/www.strolch.li/documentation.html @@ -70,9 +70,9 @@
  • Strolch Observers
  • Strolch Versioning
  • Strolch Reports
    • +
  • Strolch Privileges