LDSTechForumProjects

SSO Simulator Condition Syntax

Background

In the original SSO solution based upon OpenSSO a custom condition evaluator was created enabling an XML based custom syntax to be used to craft policies based upon user attributes specific to the needs of the applications being protected and enabled by SSO. When the SSO Environment Simulator was created the syntax engine was rolled in enabling identical policy conditions to be crafted as would be used in the real SSO environment making porting of policies from the simulator to the real environment straightforward. Now it is used to simulate the conditions evaluated in the Oracle Entitlement Server and Oracle Access Manager and as discrepancies arise changes may be made to more closely model the features of these tools. The current form of the syntax is outlined in this page.

The Syntax

The syntax is a String of well-formed XML text. This XML text requires a single top level element (TLE). Which elements can be TLEs is outlined below. Not all defined elements can act as a TLE. Some elements are logical operation elements (LOEs) that only provide logical combination of operations on nested elements. Others are user aspect evaluators (UAEs) that evaluate aspects of a user for answering policy questions. Still others are aspect value injectors (AVIs) that must be the immediate children of specific UAEs and server to inject additional aspect values into their parent elements for evaluation effectively creating an implicit OR condition but decreasing processing time over an explicit OR. This feature allows some UAEs to support an alternate syntax as noted below. All element names are case sensitive and all elements ignore any number of additional attributes. XML comments and character data between elements is also ignored so white space has no effect on processing. Therefore there is ample provision for documentation to be nested within the syntax if needed.

  • TLE = top level element: the element can be a standalone or top level element in the syntax for the condition.
  • UAE = user aspect evaluator: used to evaluate some aspect(s) or a list of the such aspects for a user.
  • LOE = logical operation element: used only to perform logical combination of nested elements.
  • AVI = aspect value injector: used to inject additional aspect values into a parent element to create lists of aspect values to be evaluated by that parent.


<AND>

Element Type Description and Use
TLE, LOE Attributes: none

Use: Supports an unlimited number of nested elements and evaluates to true if all nested elements evaluate to true. Must contain at least one nested UAE at some depth.

Example: Require a user to be a bishop and have an lds application attribute with a value of 1234567.

<AND>
 <HasPosition id='4' desc='bishop'/>
 <HasLdsApplication value='1234567'/>
</AND>

<OR>

Element Type Description and Use
TLE, LOE Attributes: none

Use: Supports an unlimited number of nested elements and evaluates to true if any nested elements evaluate to true. Must contain at least one nested UAE at some depth.

Example: Require a user to be a bishop OR have an lds account id of 1234567.

<OR>
 <HasPosition id='4' desc='bishop'/>
 <HasLdsAccountId id='1234567'/>
</OR>

<NOT>

Element Type Description and Use
TLE, LOE Attributes: none

Use: Supports a single nested element and evaluates to true if the single nested element evaluate to false. Must contain at least one nested element.

Example: Require a user NOT be an employee of the church.

<NOT>
 <IsEmployee/>
</NOT>


<Attribute>

Element Type Description and Use
TLE, UAE Evaluates a single user attribute providing ldap simple-filter functionality. Does not support complex filter syntax with parens. Used to enable more straightforward migration to policies in the real WAM SSO environment where policy conditions are based upon attributes beyond those for which custom condition syntax directives exist. Only evaluates user attributes defined via the <att> directive including attributes with more than one value.

Availability: version 5.44 of the wamulator.

Attributes:

name = Required. The user attribute being evaluated including objectclass.

operation = Required. One of exists or equals. For exists the value attribute is ignored effectively mapping to a simple ldap filter of "(attribute=*)". For equals uses case insensitive comparison of strings and, where wildcarding is used, for substrings. See examples.

value = Required only for an operation of equals. Ignored for an operation of exists. Specifies the evaluation criteria and includes the wildcard character, '*'. To include special characters as actual characters to be searched, use the escaping mechanism of "\code" where code is a two digit hexadecimal value for the character. Only "*" and "\" must be escaped. Since this directive represents a simple LDAP filter without parens, the parens '(' and ')', exclamation mark (!), ampersand (&), and pipe (|) used in complex LDAP filters do NOT need to be escaped. They will be treated as regular characters.

Use: Supports no nested elements. For exists answers true if the user has an attribute with the specified name. For equals with no wildcard answers true if the attribute value matches the specified value ignoring case. For equals with one or more wildcards answers true if the attribute value contains the corresponding non-wildcard characters in the same order evaluated case insensitively but with zero or more characters where each wildcard character is located. False otherwise.

Example: answers true of a user has an <att> directive with a name of 'test' and a value of either 'AAA' or 'BBB'.

<OR>
 <Attribute name='test' operation='equals' value='AAA'/>
 <Attribute name='test' operation='equals' value='BBB'/>
</OR>

<HasLdsApplication>

Element Type Description and Use
TLE, UAE Attributes: value = Required. the ldsApplications attribute value that a user must have.

Availability: simulator version 5.16+ (see SSO Simulator Revisions.)

Use: Supports no nested elements. Answers true if the user has an attribute of ldsApplications with a value matching that of the value attribute.

Example: answers true of a user has an ldsApplications attribute with a value of either 'aaa' or 'bbb'.

<OR>
 <HasLdsApplication value='aaa'/>
 <HasLdsApplication value='bbb'/>
</OR>

<HasLdsAccountId>

Element Type Description and Use
TLE, UAE Attributes: id = the lds account id for a user as specified in the policy-ldsaccountid header.

Availability: Although the policy-ldsaccountid header is still available, this syntax elment was removed in simulator version 5.16 so that grouping is not done by lds account id but by ldsapplication assignments using existing tools. Use HasLdsApplication instead. A conversion tool is available in 5.16+ that will indicate how to modify your files to replace HasLdsAccountId usages with HasLdsApplication as the grouping mechanism for policies. In place of the org.lds.sso.appwrap.Service as shown on SSO Simulator Getting Started specify a main java class of org.lds.sso.appwrap.ConvertToNoLdsAccountId and follow the instructions that appear on the console output.

Use: Supports zero to many nested LdsAccount element enabling creation of a list of values to be looked for by this element. This has runtime performance improvement implications since each UAE results in an object in the resulting object graph created for evaluating the syntax. Using the nested element results in a single evaluator in the object tree and that evaluator has a list of lds account ids to perform comparison and return true if the user's lds account id matches any in the list creating an implicit OR construct.

The element must have the id attribute or at least one nested LdsAccount element.

Generic form: creates an object tree consisting of three objects.

<OR>
 <HasLdsAccountId id='aaa'/>
 <HasLdsAccountId id='bbb'/>
</OR>

Alternate syntax (1): creates a single object in the object tree and hence is faster at runtime.

<HasLdsAccountId id='aaa'>
 <LdsAccount id='bbb'/>
</HasLdsAccountId>

Alternate syntax (2): same object tree as alternate (1) and hence has the same speed.

<HasLdsAccountId>
 <LdsAccount id='aaa'/>
 <LdsAccount id='bbb'/>
</HasLdsAccountId>

<LdsAccount>

Element Type Description and Use
AVI Attributes: id = the lds account id being looked for in a user.

Availability: Removed in simulator version 5.16. See HasLdsAccountId for more information.

Use: Must be nested within a <HasLdsAccountId> element.

Example: see <HasLdsAccountId>.

<MemberOfUnit>

Element Type Description and Use
TLE, UAE Attributes: id = the integer unit identifier looked for to see if a user is a member of that unit.

Use: Evaluates if the user is a member of the specified unit by testing for the existence of the specified unit in the user's policy-ldsunits header if it is defined for the user. The unit specified can be the direct unit in which the member lives or any of its containing units. Supports zero to many nested Unit elements enabling creation of a list of values to be looked for by this element. This has runtime performance improvement implications since each UAE results in an object in the resulting object graph created for evaluating the syntax. Using the nested element results in a single evaluator in the object tree and that evaluator has a list of composite unit identifiers to perform comparison and return true if the user is a member of any of the specified identifiers in the list creating an implicit OR construct.

The element must have the id attribute or at least one nested Unit element.

Generic form: creates an object tree consisting of three objects.

<OR>
 <MemberOfUnit id='aaa'/>
 <MemberOfUnit id='bbb'/>
</OR>

Alternate syntax (1): creates a single object in the object tree and hence is faster at runtime.

<MemberOfUnit id='aaa'>
 <Unit id='bbb'/>
</MemberOfUnit>

Alternate syntax (2): same object tree as alternate (1) and hence has the same speed.

<MemberOfUnit>
 <Unit id='aaa'/>
 <Unit id='bbb'/>
</MemberOfUnit>

<Unit>

Element Type Description and Use
AVI Attributes: id = the integer unit identifier being checked for to see if a user is a member of that unit.

Use: Must be nested within a <MemberOfUnit> or <CtxMatches> element.

Example: see <MemberOfUnit>.

<HasPosition>

Element Type Description and Use
TLE, UAE Attributes: id = the numeric position identifier being looked for to see if the user has that position in their policy-ldspositions header.

Use: Supports zero to many nested Position elements enabling creation of a list of values to be looked for by this element. This has runtime performance improvement implications since each TLE and UAE results in an object in the resulting object graph created for evaluating the syntax. Using the nested element results in a single evaluator in the object tree and that evaluator has a list of positions to perform comparison and return true if the user has any of those positions creating an implicit OR construct.

The element must have the id attribute or at least one nested Position element.

Generic form: creates an object tree consisting of three objects. Note additional descriptive attributes that get ignored.

<OR>
 <HasPosition id='4' type='bishop'/>
 <HasPosition id='1' type='stake pres.'/>
</OR>

Alternate syntax (1): creates a single object in the object tree and hence is faster at runtime.

<HasPosition id='4' type='bishop'>
 <Position id='1' type='stake pres.'/>
</HasPosition>

Alternate syntax (2): same object tree as alternate (1) and hence has the same speed.

<HasPosition>
 <Position id='4' type='bishop'/>
 <Position id='1' type='stake pres.'/>
</HasPosition> 

<Position>

Element Type Description and Use
AVI Attributes: id = the numeric position identifier being looked for to see if the user has that position.

Use: Must be nested within a <HasPosition> or <CtxMatches> element.

Example: see <HasPosition>.

<IsMember>

Element Type Description and Use
TLE, UAE Attributes: none

Use: Used to determine if the user is a member by checking to see if the have a policy-ldsmrn header with a value other than a single dash character. Does not support nested elements. Can be wrapped in the NOT element to determine if the user is not a member of the church.

Example: Is the user a member or has lds account id 1234567?

<OR>
 <IsMember/>
 <HasLdsAccountId id='1234567'/>
</OR>

<IsEmployee>

Element Type Description and Use
TLE, UAE Attributes: none

Use: Used to determine if the user is an employee of the church by testing for the existence of "ou-int" in the policy-dn header for a user. Does not support nested elements. Can be wrapped in a NOT element to determine if the user is not an employee of the church.

Example: Is the user an employee or has lds account id 1234567?

<OR>
 <IsEmployee/>
 <HasLdsAccountId id='1234567'/>
</OR>

<HasAssignment>

Element Type Description and Use
TLE, UAE Attributes: position = the numeric position identifier being looked for to see if the user has that position in the user's policy-ldspositions header.

unit = the unit identifier of the same header indicating in which unit or containing units the position is held by the user.

Use: Supports zero to many nested Assignment elements enabling creation of a list of values to be looked for by this element. This has runtime performance improvement implications since each TLE and UAE results in an object in the resulting object graph created for evaluating the syntax. Using the nested element results in a single evaluator in the object tree and that evaluator has a list of position and unit combinations to perform comparison and return true if the user has any of those assignments in the list creating an implicit OR construct.

The element must have the position and unit attributes or at least one nested Assignment element. Assignments of nested elements can be tested for using containing elements. For example, if a user M has the assignment of bishop in ward xxx in stake yyy in area zzz and this element were configured to test for position 1 (bishop) in unit zzz, the user would match that criteria and the evaluation would be true.

Generic form: creates an object tree consisting of three objects. Note additional descriptive attributes that get ignored.

<OR>
 <HasAssignment position='4' type='bishop' unit='aaa'/>
 <HasAssignment position='1' type='stake pres.' unit='bbb'/>
</OR>

Alternate syntax (1): creates a single object in the object tree and hence is faster at runtime.

<HasAssignment position='4' type='bishop' unit='aaa'>
 <Assignment position='1' type='stake pres.' unit='bbb'/>
</HasAssignment>

Alternate syntax (2): same object tree as alternate (1) and hence has the same speed.

<HasAssignment>
 <Assignment position='4' type='bishop' unit='aaa'/>
 <Assignment position='1' type='stake pres.' unit='bbb'/>
</HasAssignment>

<Assignment>

Element Type Description and Use
AVI Attributes: position = the numeric position identifier being looked for to see if the user has that position. Please see <HasAssignment>.

unit = the composite unit identifier (see <MemberOfUnit>) in which the position is held by the user.

Must be nested within a <HasAssignment> or <CtxMatches> elements.

Example: see <HasAssignment>.

<CtxMatches>

Element Type Description and Use
TLE, UAE, LOE Attributes:

regex = the regular expression (follows Java regular expression semantics) that will be used to evaluate a particular piece of context information.

header = the HTTP header against which the regex attribute's expression will be evaluated.

Use: Provides policy evaluation with consideration of context. For example, this allows us to go beyond asking, "Is this person a bishop?" With context included we can craft a policy that allows us to ask, "Is this person the bishop of the unit being viewed?" The unit being viewed in this case must be passed in via a contextual parameter and is separate and distinct from information available for the specific user such as the unit in which they are a member.

This directive currently enables us to only evaluate context against the user's Units, Assignments, and Positions. It accomplishes this by choosing which header to evaluate against, either policy-ldsunits or policy-ldspositions, and by specifying a regular expression to evaluate against that header. Furthermore, that regular expression can contain custom expression language constructs for embedding contextual parameter and header specific configuration values like the specific units, assignments, or positions.

The contextual parameters values are passed into the condition via a contextual name/value map as part of the evaluation query via the specific version of clientlib being used. The configuration values for units, assignments, or positions are declared via AVI elements <Position>, <Assignment>, or <Unit> nested within the CtxMatches element. For each such AVI the CtxMatches element will evaluate the regular expression once and perform an implicit OR across the result set of all such evaluations and return that result for its value.

Light-weight run-time expression language: AVI and context parameters are indicated in the regular expression by {$ + <parameter identifier> + $}. The parameter identifier for context parameters passed in via the name/value map with the rule evaluation request is crafted by prepending the name of the parameter with the character sequence ctx.. For example, if a request is received that passes context values: unit=1234 and time=12:00, then these values would be accessed in the regex with the expression language tokens of: "{$ctx.unit$}" and "{$ctx.time$}".

The parameter identifiers for each of the AVI elements is crafted by indicating the name of the AVI element followed by the specific attribute name. The complete set of parameter identifiers for the supported AVI types is listed below. If the AVI element type were the <Position> element then the Position value would be referenced in the regular expression with the token "{$Positionid$}". For the Assignment AVI type two such tokens can be used to reference both its position and unit.

Position: id via token "{$Position.id$}"

Unit: id via token "{$Unit.id$}"

Assignment: position via token "{$Assignment.position$}" and unit via token "{$Assignment.unit$}".

Example: Is the user the bishop of the currently-viewed ward?

<CtxMatches header="policy-positions" regex=".*p{$Position.id$}/[^:]*u{$ctx.unit$}/.*" debug="true">
  <Position id="4"/>
</CtxMatches>

As can be seen, the regex replaces {$Position.id$} with the id attribute of the nested Position element. It then replaces {$ctx.unit$} with the unit context value. Further, this element will evaluate the value found in the policy-positions header which has the form:

p4/7u12345/5u923492/1u234098/:p1/5u923492/1u234098/

against the resulting regex string. If unit=12345 is passed-in as context information in the rule evaluation request, then the regex string will look like this: .*p4/[^:]*u12345/.* which will evaluate to true which means that the user is the bishop of the currently-viewed ward. (See the ClientLib4J IPolicyClient Interface's isPermitted() method that accepts a Map<String,String> context parameter for how to pass context information.)

This page was last modified on 11 May 2011, at 07:18.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.