Overview
The Expansion Service and its corresponding expansion-related commands, provides an easy way for developers to add expansion capabilities to DDF during user attributes and metadata card processing. In addition to these two defined uses of the expansion service, developers are free to utilize the service in their own implementations.
Each instance of the expansion service consists of a collection of rule sets. Each rule set consists of a key value and its associated set of rules. Callers of the expansion service provide a key and an original value to be expanded. The expansion service then looks up the set of rules for the specified key. The expansion service then cumulatively applies each of the rules in the set starting with the original value, with the resulting set of values being returned to the caller.
| Key (Attribute) | Rules (original->new) | |
|---|---|---|
| key1 | value1 | replacement1 |
| value2 | replacement2 | |
| value3 | replacement3 | |
| key2 | value1 | replacement1 |
| value2 | replacement2 | |
The examples below use the following collection of rule sets:
| Key (Attribute) | Rules (original -> new) | |
|---|---|---|
| Location | Goodyear | Goodyear AZ |
| AZ | AZ USA | |
| CA | CA USA | |
| Title | VP-Sales | VP-Sales VP Sales |
| VP-Engineering | VP-Engineering VP Engineering | |
Note that the rules listed for each key are processed in order, so they may build upon each other, i.e., a new value from the new replacement string may be expanded by a subsequent rule.
Instances and Configuration
It is expected that multiple instances of the expansion service will be running at the same time. Each instance of the service defines a unique property useful for retrieving specific instances of the expansion service. The following table lists the two pre-defined instances used by DDF for expanding user attributes and metacard attributes respectively.
| Property Name | Value | Description |
|---|---|---|
| mapping | security.user.attribute.mapping | This instance is configured with rules that expand user's attribute values for security checking. |
| mapping | security.metacard.attribute.mapping | This instance is configured with rules that expand the metacard's security attributes before comparing with the user's attributes. |
Each instance of the expansion service can be configured using a configuration file. The configuration file can have three different types of lines:
- comments - any line prefixed with the '#' character is ignored as a comment (for readability, blank lines are also ignored)
- attribute separator - a line starting with 'separator=' defines the attribute separator string.
- rule - all other lines are assumed to be rules defined in a string format <key>:<original value>:<new value>
The following configuration file defines the rules shown above in the example table (using the space as a separator):
# This defines the separator that will be used when the expansion string contains multiple # values - each will be separated by this string. The expanded string will be split at the # separator string and each resulting attributed added to the attribute set (duplicates are # suppressed). No value indicates the defualt value of ' ' (space). separator= # The following rules define the attribute expansion to be performed. The rules are of the # form: # <attribute name>:<original value>:<expanded value> # The rules are ordered, so replacements from the first rules may be found in the original # values of subsequent rules. Location:Goodyear:Goodyear AZ Location:AZ:AZ USA Location:CA:CA USA Title:VP-Sales:VP-Sales VP Sales Title:VP-Engineering:VP-Engineering VP Engineering
Expansion Commands
| Title | Namespace | Description |
|---|---|---|
| DDF::Security::Expansion::Commands | security | The expansion commands provide detailed information about the expansion rules in place and the ability to see the results of expanding specific values against the active rule set. |
Expansion Commands
security:expand security:expansions
Command Descriptions
| Command | Description |
|---|---|
| expand | Runs the expansion service on the provided data returning the expanded value |
| expansions | Dumps the ruleset for each active expansion service. |
Expansion Command Examples and Explanation
security:expansions
The security:expansions command dumps the ruleset for each active expansion service. It takes no arguments and displays each rule on a separate line in the form: <attribute name> : <original string> : <expanded string>. The following example shows the results of executing the expansions command with no active expansion service.
ddf@local>security:expansions No expansion services currently available.
After installing the expansions service and configuring it with an appropriate set of rules, the expansions command will provide output similar to the following:
ddf@local>security:expansions Location : Goodyear : Goodyear AZ Location : AZ : AZ USA Location : CA : CA USA Title : VP-Sales : VP-Sales VP Sales Title : VP-Engineering : VP-Engineering VP Engineering
security:expand
The security:expand command runs the expansion service on the provided data. It takes an attribute and an original value, expands the original value using the current expansion service and rule set and dumps the results. For the rule set shown above, the expand command produces the following results:
ddf@local>security:expand Location Goodyear [Goodyear, USA, AZ] ddf@local>security:expand Title VP-Engineering [VP-Engineering, Engineering, VP] ddf@local>expand Title "VP-Engineering Manager" [VP-Engineering, Engineering, VP, Manager]