Structure of an authentication content store
Some rules must be met for documents that form authentication data that treat hierarchical structure as well as content schema information to choose:
- Single content documents define single users and groups. They must be created in the database's default language.
- Content documents defining users must all belong to the same website area. Data collecting for authentication can work even more effectively when they are all stored under a special branch of the page hierarchy that does not contain (much) other data. In that case you should give one page that in hierarchy is "above" all user documents a special unique name. This will be your "root document" for user definitions.
- The same rules apply for content documents defining groups. They may share the same area and root document as the "user documents" although we recommend storing them on a different branch.
- User and group documents are identified by their items. A user document must have an item for user name, named "UserName" by default. A group document must have an item for group name, named "GroupName" by default. The names of those fields can be customized by options.
All content documents that are stored in a configured area/under a configured root document are tested for the availabilty of mandatory items. Documents that contain these items will be used as user definitions.
The following table describes the items that OpenWGA will use as user data. All item names are defaults and can be reconfigured to other names by special authentication options.
|The E-Mail address of the user|
|Enabled||Determines if the user is enabled, which is the case when the item contents is "true" of it does not exist. Disabled users cannot be used for authentication.|
|Password||X||The hashed password of the user. Use <tml:input type="hashedpassword"> in WebTML or method hashPassword() on WGAPI class de.innovationgate.utils.WGUtils to create the hash.|
|UserAliases||A list of name variants for the user that also can be used for login or specifying authorisations.|
|UserName||X||The fully qualified user name|
All content documents that are stored in a configured area/under a configured root document are tested for the availabilty of mandatory items. Documents that contain these items will be used as group definitions.
The following table describes the items that OpenWGA will use as group data. All item names are defaults and can be reconfigured to other names by special authentication options.
|Enabled||Determines if the group is enabled, which is the case when the item contents is "true" of it does not exist. Disabled groups will not show in the groups list of authenticated users.|
|GroupName||X||The name of the group|
|Members||X||A list of user and group names to be treated as group members. Cascaded groups - groups that are again members of other groups - are possible.|
Optionally a configuration for the authentication content store can be embedded into the design, identifying all the items and root documents to use. If that is not used then everything needs to be entered on configuration of this content store as authentication source in OpenWGA admin client.
The integrated configuration is to be placed as file "csauth.properties" into the system container folder of the design (folder "files/system"). It contains a single configuration setting per line in Java properties file format. Here is an example file which merely sets the root documents and determines a special item for containing user name aliases:
As you see the simple format provides a single key/value pair per line which is divided via equal sign.
See the following table for available configuration keys. You only need to use those keys whose value should not be the default value:
|auth.cs.collect.condition||A condition determining if a database update should trigger the reloading of authentication data. It has a document in context that was recently updated and should return true, if the authentication data needs to be reloaded because of this change.|
|auth.cs.item.aliases||Name of the user document item holding name aliases in a list||UserAliases|
|auth.cs.item.email||Name of the user document item holding the E-Mail address|
|auth.cs.item.enabled||Name of the user document item determining if the user is enabled in a boolean value||Enabled|
|auth.cs.item.groupmembers||Name of the group document item holding the names of group members in a list||Members|
|auth.cs.item.groupname||Name of the group document item holding the name of the group||GroupName|
|auth.cs.item.password||Name of the user document item holding password of the user in hashed form||Password|
|auth.cs.item.username||Name of the user document item holding the fully qualified (i.e. primary) user name||UserName|
|auth.cs.rootdoc.groups||Name of a website area or page which is contains all group documents in the sub hierarchy||authusers|
|auth.cs.rootdoc.users||Name of a website area or page which is contains all user documents in the sub hierarchy||authgroups|
This is no complete list of the available configuration options. You can also review the option keys for other options that are available to content store authentication by:
- Opening OpenWGA admin client and enable expert mode (Checkbox on the top right)
- Go to "Domains" and configure a domain to use authentication type "Content store"
- Click "Show/Hide available options" and lookup options from the list. The option key to be used in "csauth.properties" is shown in brackets after the option title when expert mode is enabled: