SeedDms OIDC Extension

This is a SeedDms extension that add support for OIDC to SeedDms.

Install

Copy the oidc folder in ext folder of SeedDms. Open extensions settings and refresh extensions via button. Activate the extension with help of checkbox within extension's config and set the configuration properties.

Properties which show's a placeholder in textfield as well as role/group's mapping field are not required. The placeholder values are the default values which will be choosen as far as nothing else is set.

The "OIDC Endpoint" is intended to be configured with a trailing "/" and without the ".well-known/openid-configuration" suffix which is automatically added by this extension.

If you want to update this extension from a previous version (especially to get new configuration fields), one must take care to clear the related section within "<install_directory>/seeddms60x/data/cache/extensions.php".</install_directory>

Main Configuration

SeedDms 6.0.25 + Apache + Keycloak 23.0.3

• Apache setup must have following configuration :

  RewriteEngine on
  RewriteRule "/.well-known/callback" "/index.php" [L,QSA]
  

• Keycloak setup must have especially the following non-default points :

  "Valid redirect URIs" must be set with above mentioned "/.well-known/callback"
  "Valid post logout redirect URIs" is more evident as standard to SeedDMS, "/op/op.Logout.php"
  

• SeedDMS setup may have the following setup :

  If you want to have users being automatically created in SeedDMS upon sucessful Keycloak authentication ; you must disable "Restricted Access" setting from either UI's System configuration, or thru settings.xml file
  

Optional Configuration

Misc options

• "Allow to skip OIDC Login" provides a failover solution to connect without OIDC (eg. your OIDC system is down or you administrate SeedDMS with alocal account whereas regular users use OIDC).

  Once enabled, you can use the "https://<your_host>/out/out.Login.php?oidc_skipped=true" URL to go to the default logon page.
  Please note that if you provide wrong credentials, you will be then redirected to the configured OIDC logon.
  

• "Keep UserData Aligned With OIDC" allows to update SeedDMS's user data from the OIDC user logged in.

  This is done just after a successful logon, prior to reach the hosted documents.
  This may be useful if you want to fully manage kind of "authorizations" (see groups & roles sections below) from you OIDC installation.
  Disabled by default to have same behavior for OIDC extension 1.x.x as well rathe keep allowing upgrading your user from SeedDMS with all other possibles options not managed here.
  

• "Auto-Create Groups" allows to automatically create any SeedDMS group not yet existing, whereas requested thru a matching Group Mapping (see below).

  This is mainly useful in combination with "Keep UserData Aligned With OIDC".
  Please note that SeedDMS groups' so-created have to be removed manually if no longer needed.
  Please also note that no counterpart exists for SeedDMS roles' (as this is a more complex object than just a label).

Groups & Roles considerations

Before entering details to configure Groups & Roles, please have in mind the following elements.

• SeedDMS 6.x.x onwards introduced "real" roles' objects, that could be user created. This give extra flexibility to hide some documents in specific status, independently of groups' accesses which is more focus on permanent hiding of documents thru the directory structure. Only a single mandatory role is supported whereas groups are optional and can be multiple for a SeedDMS user.

• On the other side, an OIDC installation may (eg. without full OAuth2) provide some groups and/or roles, but (to my reading) no standard way is defined to achieve it. Using Keycloak here as a reference to have a concrete groups/roles way of working for such installation ; groups are there used to group users together and then assign roles to groups themselves. Thus users' maintenance is reduced by simply adding/removing them from the group(s) reflecting their current attributions within an organization. Despite this Keycloak clearly explained designed, from an external system consuming such OIDC installation you may in some cases achieve the same either thru roles or groups.

Groups & Roles configuration

Both these settings are optional, allowing Administrator to support most of cases according usage he intend to do regarding above considerations.

• "Role Claim" and "Role Mapping" are used together to manage SeedDMS role for an OIDC user.
• "Group Claim" and "Group Mapping" are used together to manage SeedDMS groups for an OIDC user.

For each of them, the Claim element is to select from which OIDC token information the Mapping element will apply on. The chosen OIDC token information must be an array (usually the case though for groups/roles). Taking into account above mentioned considerations, one can choose to use the same token claim to deduce both SeedDMS role and group(s).

Eg. for simple cases, a client scope answering token claim name "groups" (if keeping the default configuration this OIDC-Extension) could be added, mapping "Group membership" and with "Full group path" enabled at mapper level.
In such a configuration, you could produce kind of hierarchical claim entries, useful for Mapping (see below) ; which would allow managing rights in SeedDMS without requiring managing a huge of Keycloak roles if you don't further use OAuth2 possibilities otherwise.

The Mapping element consists of a list of rules, specified the following way :

• Each rule is specified on its own line

• A rule can be prefixed with a "+" character (let's call this additive rule). If so, even if that one matches, it will be applied but following rules will be evaluated as well. Otherwise, any normal rule that matches will stop looking further in the mapping. Consequently, additive rule shall normally be specified before regular ones. Please note that additive rule used with Role Mapping may lead to invalid configuration (as only a single SeedDMS role is possible). additive rule may be used to provide default group(s) on top of other configuration (eg. to identify users from OIDC).

• Despite above mentioned optional prefix, rule have then the following form :
  - pcre_regex as used by PHP
  - the "=" character
  - a "," separated list of the related seeddms_object_result (ID are also possible although less meaningful). If only a single seeddms_object_result is needed, "," must not be present.

• About pcre_regex, any valid expression can be used. But if you intend to map against a Keycloak hierarchical group claim (see example above), an ugly "~" character could be better than usual "/" to avoid escaping requirement. For each of the related Claim entries, if pcre_regex matches, the defining rule is considered to match (as explained above).

• For any matching rule, each of the related seeddms_object_result will be selected as a value to set to the OIDC user. Again, as a single SeedDMS role is possible, having multiple seeddms_object_result for Role Mapping may lead to invalid configuration.

• seeddms_object_result is technically a PHP replacement. Simple SeedDMS object names can be used (see Migration example below) but you can also use capture from pcre_regex. Number of configuration possibilities is de facto huge, and so not intended to be detailed here. However, just to finish covering the simple Keycloak hierachical groups example mentioned above :

  Without managing roles in Keycloak, you can simply nest groups to produce a hierarchy.
  eg. "/internal-people/some-service/manager" where some Keycloak user would be added to group "/internal-people" or "/internal-people/some-service" or "/internal-people/some-service/manager" depending on its attributions.
  Thus, assuming you consistently manage all "services" this way, you have one or many such kind of entries for an OIDC user that could be checked against the following "Group Mapping" :
      +~^.*$~=oidc-users
      +~^/internal-people[^/]*$~=internal-users
      +~^.+/manager$~=all-managers
      ^/internal-people/([^/]*)$~=service-$1
      ^/internal-people/([^/]*)/manager$~=service-$1,manager-of-service-$1
  Result would be, assuming you have all groups already existing, or the "Auto-Create Groups" enabled :
      All users connecting thru OIDC will have group "oidc-users" (eg. let them access specific organization documentation explaining how to change their password)
      In addition, all of them that are part of a so-expressed service will also be part of "internal-users" (eg. let them access a folder with general company information)
      In addition, if the OIDC user is a "manager" of a "service", he will be part of "all-managers" as well (eg. let him/her access the company financial results in a dedicated folder)
      Then, either the user isn't a manager and he will only be part of the related service (eg. "service-sales") with shared documentation for that latter one ; or as a "manager", he will have access the former plus his specific one (eg. to store evaluation of teammates or whatever else sensitive), concretely "service-sales" and "manager-of-service-sales")
  As the rules are evaluated for each of the "Group Claim" elements (the "additive_rule" vs. regular one matching rule is for each entry), one could be part of multiple above expressed "services" and thus gain access too each of them the same way with such an above generic configuration.
  

Compatibility with other extensions

Some other SeedDMS extensions may require to have some SeedDMS's URL isolated from OIDC connection ; eg. "download_link" or "upload_area" which provide download/upload features for anonymous. This can be achieved by excluding some URL patterns from the OIDC scope ; technically evaluating the requested uri path against a pcre_regex as used by PHP.

Here follows a possible compatible configuration for most common SeedDMS's extensions:

• Upload Area / upload_area:

  ~^/upload_area/.*$~
  ~^/ext/upload_area/out/out\.UploadArea\.php\?.*$~
  

• Download Link / download_link:

  ~^/download_link/.*$~
  ~^/ext/download_link/op/op\.DownloadLink.php\?.*$~
  

Migration from 1.x.x

Main endusers' change in 2.x.x is about SeedDMS's role management for OIDC users. Whereas previous version of this extension was looking to a specific group name within groups (mainly because in SeedDMS 4.x.x and 5.x.x roles were hardcoded), eg. admin create the OIDC user as a SeedDMS's Administrator ; the current version now uses a mapping to set one of the new SeedDMS 6.x.x create-able role.

• If you won't bother with having some OIDC user created as SeedDMS's Administrator, no optional configuration is required. Thus, any OIDC user created will be a normal user (using the builtin User role provided).

• If you wan't to reproduce the same behavior as previously, where some of the OIDC create users may be administrators (depicted by element of chosen token claim being admin), set the following Role Mapping (see above for details) :

  ~^admin$~=Admin
  

Derivat

This code is inspired and based on SeedSAML-Extension from Andreas Böhler