From 01d37bde6b7f2b040daa8e16c1af72da152613fc Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Tue, 24 Feb 2026 17:33:29 -0500 Subject: [PATCH 1/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- .../DESDL-Mods/ESDLauth_feature.xml | 266 +++++++++++++++--- 1 file changed, 225 insertions(+), 41 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index 3b511c33b4e..adc79ca0721 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,48 +1,232 @@ - - auth_feature - - + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + + ESDL auth_feature: Semantics and Syntax + + auth_feature - The auth_feature attribute (valid only for an ESPService or - ESPMethod) allows you to specify a means to verify a user's permission to - execute a method. - - In order to enable this feature, your system must be configured to use - a form of security that supports feature level authentication, such as LDAP - security included in the Community edition of the platform. Once LDAP is - configured, you would add the tag name provided as the value for the - authFeature attribute to the feature level - authentication list in the Security section of ECL Watch. Then you would set - permissions for users and/or groups. - - If you are using a third-party Security Manager plugin, consult their - documentation for details on adding the tag name to their security - configuration. + + The auth_feature attribute configures feature-level security in ESDL by associating features and access levels to ESPservice and ESPmethod elements. This provides fine-grained, declarative access control for ESDL services and methods. + - The auth_feature attribute is required for every method, but can be - specified at the ESPService level to apply to all methods within a service. - You can override for an individual method by setting the attribute at a - method level. + + Overview and Precedence + + An auth_feature string is a comma-delimited list of tokens, interpreted in order from service (lowest precedence) to method (highest precedence), and processed in reverse order. + + + ESPservice values take effect at the EsdlService scope, while ESPmethod values are in the EsdlMethod scope and override service scope requirements. If auth_feature is set on both service and method, the resulting security requirement is the union, with method-level tokens taking precedence where conflicts arise. + + + See formal BNF specification and parsing details below for precise semantics. + + - Setting auth_feature("NONE") means no authentication is needed. - Setting auth_feature("DEFERRED") defers the authentication to the business - logic in the ESP developer's method implementation logic. + + Token Semantics and Categories + + Each auth_feature may include universal tokens and feature-specific tokens, each with well-defined semantics and support. + + + Feature-Independent Tokens + The following tokens are universally supported and do not reference any specific feature: + + + + + + None + No feature access required. Standalone: disables access checks; combined: ignored. Supported by esdllib and hidl. + + + Deferred + Equivalent to None; security may be enforced dynamically by the method handler. Supported by esdllib and hidl. + + + !X (where X is any value) + Reserved for future semantics; constraints on X to be defined. New syntax. + + + + + + + Permitted Feature-Specific Tokens + For a feature named MyFeature, permitted tokens include: + + + + + + + Token + SecAccess Required + Supported By + + + MyFeature + SecAccess_Read + esdllib + + + MyFeature:Access + SecAccess_Access + esdllib, hidl + + + MyFeature:Read + SecAccess_Read + esdllib, hidl + + + MyFeature:Write + SecAccess_Write + esdllib, hidl + + + MyFeature:Full + SecAccess_Full + esdllib, hidl + + + MyFeature:None + No access required (overrides service attribute) + esdllib, hidl + + + MyFeature:Deferred + Equivalent to None + esdllib, hidl + + + + + + + Forbidden Tokens + The following tokens are not permitted for feature MyFeature: + + + + + + MyFeature: + Not permitted; shortcut not needed; accepted by hidl as equivalent to MyFeature:Read. + + + MyFeature:X (where X is not listed above) + Invalid token; error; accepted by hidl as equivalent to MyFeature:Full. + + + + + + - Example: + + Examples + + Example 1: Service-level authentication + + +ESPservice [auth_feature("DataAccess:Read")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod ListData(ListDataRequest, ListDataResponse); +}; + + + Both GetData and ListData require SecAccess_Read access for DataAccess. + + + Example 2: Combined service and method authentication + + +ESPservice [auth_feature("DataAccess:Read")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); +}; + + + GetData requires SecAccess_Read; UpdateData requires both SecAccess_Read and SecAccess_Write for DataAccess. + + + Example 3: Method bypassing service authentication + + +ESPservice [auth_feature("DataAccess:Full")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); +}; + + + GetData requires SecAccess_Full access; GetPublicData requires no access for DataAccess. + + - ESPservice MyService [auth_feature("NONE")] - { - ESPmethod MyMethod1(MyMethod1Request, MyMethod1Response); - ESPmethod - [ - description("MyMethod Two"), - auth_feature("AllowMyMethod2"), - help("This method does everything MyMethod1 does plus a few extra features"), - min_ver("1.2") - ] - MyMethod2(MyMethod2Request, MyMethod2Response); - }; - + + Formal Syntax (Pseudo-BNF) + + auth_feature tokens follow the grammar and precedence below: + + +token ::= ( exclusion | suppression | deferral | assignment ) +exclusion ::= ( exclude-all | exclude-scope | exclude-feature | exclude-feature-in-scope ) + ; no form of exclusion satisfies a requirement to affirmatively specify security +exclude-all ::= '!' [ '::' ] + ; all lower precedence tokens are ignored + ; any lower precedence affirmation of security is ignored +exclude-scope ::= '!' scope-name [ '::' ] + ; all lower precedence tokens specified by the named scope are ignored + ; any lower precedence affirmation of security resulting from the named scope is ignored +exclude-feature ::= '!' [ '' ] '::' feature-name + ; any lower precedence token specifying the named feature is ignored + ; any lower precedence affirmation of security resulting from the named feature is ignored +exclude-feature-in-scope ::= '!' scope-name '::' feature-name + ; any lower precedence token specifying the named feature and specified in the named scope is ignored + ; any lower precedence affirmation of security resulting from the named scope and feature is ignored +suppression ::= ( suppress-all | suppress-feature ) +suppress-all ::= 'NONE' + ; all lower precedence tokens are ignored + ; the absence of security is affirmed +suppress-feature ::= feature-name ':NONE' + ; any lower precedence token specifying the named feature is ignored + ; any lower precedence affirmation of security resulting from the named feature is ignored +deferral ::= ( defer-all | defer-feature ) +defer-all ::= 'DEFERRED' + ; the current security state, which may or may not be empty, is affirmed +defer-feature ::= feature-name ':DEFERRED' + ; any lower precedence token specifying the named feature is ignored + ; a new map entry is created that requires no security + ; the security state is affirmed +assignment ::= ( assign-default-level | assign-default-feature | assign-feature-and-level ) +assign-default-level ::= feature-name + ; any lower precedence token specifying the named feature is ignored + ; a new map entry is created that requires full access-level + ; the security state is affirmed +assign-default-feature ::= ':' access-level + ; any lower precedence token specifying the feature-name equivalent to '${service}Access' is ignored + ; a new map entry is created specifying the feature-name equivalent to '${service}Access' and the given access level + ; the security state is affirmed +assign-feature-and-level ::= feature-name ':' access-level + ; any lower priority token specifying the named feature is made obsolete + ; a new map entry is created specifying the named feature and the given access level + ; the security state is affirmed +scope-name ::= ( 'DEFAULT' | 'ESDLSERVICE' | 'ESDLMETHOD' | ... ) + ; additional names are anticipated resulting from binding integration +access-level ::= ( 'ACCESS' | 'READ' | 'WRITE' | 'FULL' ) +reserved-word ::= scope-name | access-level +feature-name ::= ( feature-name-char* '${' variable-name '}' feature-name-char* | feature-name-char+ ) + ; feature-name-char is any char except whitespace, ',', '"', '!', or ':' + ; feature-name has the added restrictions of not being a reserved-word +variable-name ::= ( 'SERVICE' | 'METHOD' ) + + + Note: + The method scope overtakes the service scope: a method may override any or all requirements set at the service level by its own auth_feature string. + + + \ No newline at end of file From cd5c8a815bbfc18ad785e8eb497b28addc9bb83d Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Tue, 17 Mar 2026 10:45:04 -0400 Subject: [PATCH 2/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- .../DESDL-Mods/ESDLauth_feature.xml | 189 ++++++++++++------ 1 file changed, 131 insertions(+), 58 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index adc79ca0721..f08afcd2de7 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,122 +1,185 @@ +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - ESDL auth_feature: Semantics and Syntax - - + auth_feature + + auth_feature - - The auth_feature attribute configures feature-level security in ESDL by associating features and access levels to ESPservice and ESPmethod elements. This provides fine-grained, declarative access control for ESDL services and methods. - + The auth_feature attribute configures + feature-level security in ESDL by associating features and access levels to + ESPservice and ESPmethod elements. This provides + fine-grained, declarative access control for ESDL services and + methods. Overview and Precedence - - An auth_feature string is a comma-delimited list of tokens, interpreted in order from service (lowest precedence) to method (highest precedence), and processed in reverse order. - - - ESPservice values take effect at the EsdlService scope, while ESPmethod values are in the EsdlMethod scope and override service scope requirements. If auth_feature is set on both service and method, the resulting security requirement is the union, with method-level tokens taking precedence where conflicts arise. - - - See formal BNF specification and parsing details below for precise semantics. - + + An auth_feature string is a comma-delimited + list of tokens, interpreted in order from service (lowest precedence) to + method (highest precedence), and processed in reverse order. + + ESPservice values take effect at the + EsdlService scope, while ESPmethod values are in + the EsdlMethod scope and override service scope requirements. + If auth_feature is set on both service and method, + the resulting security requirement is the union, with method-level tokens + taking precedence where conflicts arise. + + See formal BNF specification and parsing details below for precise + semantics. Token Semantics and Categories - - Each auth_feature may include universal tokens and feature-specific tokens, each with well-defined semantics and support. - + + Each auth_feature may include universal tokens + and feature-specific tokens, each with well-defined semantics and + support. + Feature-Independent Tokens - The following tokens are universally supported and do not reference any specific feature: + + The following tokens are universally supported and do not + reference any specific feature: + - + + None - No feature access required. Standalone: disables access checks; combined: ignored. Supported by esdllib and hidl. + + No feature access required. Standalone: disables access + checks; combined: ignored. Supported by + esdllib and hidl. + Deferred - Equivalent to None; security may be enforced dynamically by the method handler. Supported by esdllib and hidl. + + Equivalent to None; security may be + enforced dynamically by the method handler. Supported by + esdllib and hidl. + !X (where X is any value) - Reserved for future semantics; constraints on X to be defined. New syntax. + + Reserved for future semantics; constraints on X to be + defined. New syntax. + Permitted Feature-Specific Tokens - For a feature named MyFeature, permitted tokens include: + + For a feature named MyFeature, permitted tokens + include: + - - + + + + Token + SecAccess Required + Supported By + MyFeature + SecAccess_Read + esdllib + MyFeature:Access + SecAccess_Access + esdllib, hidl + MyFeature:Read + SecAccess_Read + esdllib, hidl + MyFeature:Write + SecAccess_Write + esdllib, hidl + MyFeature:Full + SecAccess_Full + esdllib, hidl + MyFeature:None + No access required (overrides service attribute) + esdllib, hidl + MyFeature:Deferred + Equivalent to None + esdllib, hidl + Forbidden Tokens - The following tokens are not permitted for feature MyFeature: + + The following tokens are not permitted for feature + MyFeature: + - + + MyFeature: - Not permitted; shortcut not needed; accepted by hidl as equivalent to MyFeature:Read. + + Not permitted; shortcut not needed; accepted by hidl as + equivalent to MyFeature:Read. + - MyFeature:X (where X is not listed above) - Invalid token; error; accepted by hidl as equivalent to MyFeature:Full. + MyFeature:X (where X is not listed + above) + + Invalid token; error; accepted by hidl as equivalent to + MyFeature:Full. @@ -126,9 +189,10 @@ Examples - - Example 1: Service-level authentication - + + Example 1: Service-level + authentication + ESPservice [auth_feature("DataAccess:Read")] DataService { @@ -136,12 +200,14 @@ ESPservice [auth_feature("DataAccess:Read")] DataService ESPmethod ListData(ListDataRequest, ListDataResponse); }; - - Both GetData and ListData require SecAccess_Read access for DataAccess. - - - Example 2: Combined service and method authentication - + + Both GetData and ListData + require SecAccess_Read access for + DataAccess. + + Example 2: Combined service and method + authentication + ESPservice [auth_feature("DataAccess:Read")] DataService { @@ -149,12 +215,16 @@ ESPservice [auth_feature("DataAccess:Read")] DataService ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); }; - - GetData requires SecAccess_Read; UpdateData requires both SecAccess_Read and SecAccess_Write for DataAccess. - - - Example 3: Method bypassing service authentication - + + GetData requires + SecAccess_Read; UpdateData requires + both SecAccess_Read and + SecAccess_Write for + DataAccess. + + Example 3: Method bypassing service + authentication + ESPservice [auth_feature("DataAccess:Full")] DataService { @@ -162,16 +232,18 @@ ESPservice [auth_feature("DataAccess:Full")] DataService ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); }; - - GetData requires SecAccess_Full access; GetPublicData requires no access for DataAccess. - + + GetData requires + SecAccess_Full access; GetPublicData + requires no access for DataAccess. Formal Syntax (Pseudo-BNF) - - auth_feature tokens follow the grammar and precedence below: - + + auth_feature tokens follow the grammar and + precedence below: + token ::= ( exclusion | suppression | deferral | assignment ) exclusion ::= ( exclude-all | exclude-scope | exclude-feature | exclude-feature-in-scope ) @@ -224,9 +296,10 @@ feature-name ::= ( feature-name-char* '${' variable-name '}' feature-name-char* ; feature-name has the added restrictions of not being a reserved-word variable-name ::= ( 'SERVICE' | 'METHOD' ) - - Note: - The method scope overtakes the service scope: a method may override any or all requirements set at the service level by its own auth_feature string. - + + Note: The method scope overtakes + the service scope: a method may override any or all requirements set at + the service level by its own auth_feature + string. - \ No newline at end of file + From 03f95e2e4a91d4455a16c0ae62ea54971308f0cb Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Mon, 23 Mar 2026 15:19:59 -0400 Subject: [PATCH 3/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- .../DESDL-Mods/ESDLauth_feature.xml | 207 +++++++----------- 1 file changed, 82 insertions(+), 125 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index f08afcd2de7..0f2532f6172 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,6 +1,7 @@ + auth_feature @@ -9,33 +10,54 @@ The auth_feature attribute configures feature-level security in ESDL by associating features and access levels to ESPservice and ESPmethod elements. This provides - fine-grained, declarative access control for ESDL services and - methods. + fine-grained, declarative access control for ESDL services and methods. + - - Overview and Precedence + + Examples + + Example 1: Service-level authentication + +ESPservice [auth_feature("DataAccess:Read")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod ListData(ListDataRequest, ListDataResponse); +}; + + Both GetData and ListData require SecAccess_Read access for DataAccess. - An auth_feature string is a comma-delimited - list of tokens, interpreted in order from service (lowest precedence) to - method (highest precedence), and processed in reverse order. + Example 2: Combined service and method authentication + +ESPservice [auth_feature("DataAccess:Read")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); +}; + + GetData requires SecAccess_Read; UpdateData requires both SecAccess_Read and SecAccess_Write for DataAccess. - ESPservice values take effect at the - EsdlService scope, while ESPmethod values are in - the EsdlMethod scope and override service scope requirements. - If auth_feature is set on both service and method, - the resulting security requirement is the union, with method-level tokens - taking precedence where conflicts arise. + Example 3: Method bypassing service authentication + +ESPservice [auth_feature("DataAccess:Full")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); +}; + + GetData requires SecAccess_Full access; GetPublicData requires no access for DataAccess. + - See formal BNF specification and parsing details below for precise - semantics. + + Overview + An auth_feature string is a comma-delimited list of tokens, interpreted in order from service (lowest precedence) to method (highest precedence), and processed in reverse order. + ESPservice values take effect at the EsdlService scope, while ESPmethod values are in the EsdlMethod scope and override service scope requirements. If auth_feature is set on both service and method, the resulting security requirement is the union, with method-level tokens taking precedence where conflicts arise. + See the formal BNF specification and parsing details below for precise semantics. + Token Semantics and Categories - - Each auth_feature may include universal tokens - and feature-specific tokens, each with well-defined semantics and - support. + Each auth_feature may include universal tokens and feature-specific tokens, each with well-defined semantics and support. Feature-Independent Tokens @@ -158,123 +180,49 @@ Forbidden Tokens - - The following tokens are not permitted for feature - MyFeature: - + The following tokens are not permitted for feature MyFeature: - MyFeature: - - Not permitted; shortcut not needed; accepted by hidl as - equivalent to MyFeature:Read. + Not permitted; shortcut not needed; accepted by hidl as equivalent to MyFeature:Read. - - MyFeature:X (where X is not listed - above) - - Invalid token; error; accepted by hidl as equivalent to - MyFeature:Full. + MyFeature:X (where X is not listed above) + Invalid token; error; accepted by hidl as equivalent to MyFeature:Full. - - - - - Examples - - Example 1: Service-level - authentication - - -ESPservice [auth_feature("DataAccess:Read")] DataService -{ - ESPmethod GetData(GetDataRequest, GetDataResponse); - ESPmethod ListData(ListDataRequest, ListDataResponse); -}; - - - Both GetData and ListData - require SecAccess_Read access for - DataAccess. - - Example 2: Combined service and method - authentication - - -ESPservice [auth_feature("DataAccess:Read")] DataService -{ - ESPmethod GetData(GetDataRequest, GetDataResponse); - ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); -}; - - - GetData requires - SecAccess_Read; UpdateData requires - both SecAccess_Read and - SecAccess_Write for - DataAccess. - - Example 3: Method bypassing service - authentication - - -ESPservice [auth_feature("DataAccess:Full")] DataService -{ - ESPmethod GetData(GetDataRequest, GetDataResponse); - ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); -}; - - - GetData requires - SecAccess_Full access; GetPublicData - requires no access for DataAccess. - - - - Formal Syntax (Pseudo-BNF) - - auth_feature tokens follow the grammar and - precedence below: - - -token ::= ( exclusion | suppression | deferral | assignment ) -exclusion ::= ( exclude-all | exclude-scope | exclude-feature | exclude-feature-in-scope ) - ; no form of exclusion satisfies a requirement to affirmatively specify security -exclude-all ::= '!' [ '::' ] - ; all lower precedence tokens are ignored - ; any lower precedence affirmation of security is ignored -exclude-scope ::= '!' scope-name [ '::' ] - ; all lower precedence tokens specified by the named scope are ignored - ; any lower precedence affirmation of security resulting from the named scope is ignored -exclude-feature ::= '!' [ '' ] '::' feature-name - ; any lower precedence token specifying the named feature is ignored - ; any lower precedence affirmation of security resulting from the named feature is ignored -exclude-feature-in-scope ::= '!' scope-name '::' feature-name - ; any lower precedence token specifying the named feature and specified in the named scope is ignored - ; any lower precedence affirmation of security resulting from the named scope and feature is ignored -suppression ::= ( suppress-all | suppress-feature ) -suppress-all ::= 'NONE' - ; all lower precedence tokens are ignored - ; the absence of security is affirmed -suppress-feature ::= feature-name ':NONE' - ; any lower precedence token specifying the named feature is ignored - ; any lower precedence affirmation of security resulting from the named feature is ignored -deferral ::= ( defer-all | defer-feature ) -defer-all ::= 'DEFERRED' - ; the current security state, which may or may not be empty, is affirmed -defer-feature ::= feature-name ':DEFERRED' - ; any lower precedence token specifying the named feature is ignored - ; a new map entry is created that requires no security - ; the security state is affirmed -assignment ::= ( assign-default-level | assign-default-feature | assign-feature-and-level ) + + + Formal Syntax (Pseudo-BNF) + auth_feature tokens follow the grammar and precedence below: + + token ::= ( exclusion | suppression | deferral | assignment ) + exclusion ::= ( exclude-all | exclude-scope | exclude-feature | exclude-feature-in-scope ) + ; no form of exclusion satisfies a requirement to affirmatively specify security + exclude-all ::= '!' [ '::' ] + ; all lower precedence tokens are ignored + ; any lower precedence affirmation of security is ignored + exclude-scope ::= '!' scope-name [ '::' ] + ; all lower precedence tokens specified by the named scope are ignored + ; any lower precedence affirmation of security resulting from the named scope is ignored + exclude-feature ::= '!' [ '' ] '::' feature-name + ; any lower precedence token specifying the named feature is ignored + ; any lower precedence affirmation of security resulting from the named feature is ignored + exclude-feature-in-scope ::= '!' scope-name '::' feature-name + ; any lower precedence token specifying the named feature and specified in the named scope is ignored + ; any lower precedence affirmation of security resulting from the named scope and feature is ignored + suppression ::= ( suppress-all | suppress-feature ) + suppress-all ::= 'NONE' + ; all lower precedence tokens are ignored + ; the absence of security is affirmed + suppress-feature ::= feature-name ':NONE' + ; any lower precedence token specifying the named feature is ignored + ; any lower precedence affirmation of security resulting from the named feature is ignored assign-default-level ::= feature-name ; any lower precedence token specifying the named feature is ignored ; a new map entry is created that requires full access-level @@ -301,5 +249,14 @@ variable-name ::= ( 'SERVICE' | 'METHOD' ) the service scope: a method may override any or all requirements set at the service level by its own auth_feature string. +Note: The method scope overtakes the service scope: a method may override any or all requirements set at the service level by its own auth_feature string. - + + See Also + + ESPservice, + ESPmethod, + ESDL Attributes + + + \ No newline at end of file From 950f919be121147d94ea3921495cc156d63b046c Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Mon, 23 Mar 2026 16:52:12 -0400 Subject: [PATCH 4/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- .../DESDL-Mods/ESDLauth_feature.xml | 318 ++++++++++-------- 1 file changed, 171 insertions(+), 147 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index 0f2532f6172..acc640b383c 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,7 +1,6 @@ - auth_feature @@ -10,198 +9,226 @@ The auth_feature attribute configures feature-level security in ESDL by associating features and access levels to ESPservice and ESPmethod elements. This provides - fine-grained, declarative access control for ESDL services and methods. - + fine-grained, declarative access control for ESDL services and + methods. + + Examples: + + Service-level authentication - - Examples + Both GetData and ListData + require SecAccess_Read access for + DataAccess. - Example 1: Service-level authentication - + ESPservice [auth_feature("DataAccess:Read")] DataService { ESPmethod GetData(GetDataRequest, GetDataResponse); ESPmethod ListData(ListDataRequest, ListDataResponse); }; - Both GetData and ListData require SecAccess_Read access for DataAccess. - Example 2: Combined service and method authentication - + Combined service and method + authentication + + GetData requires SecAccess_Read; + UpdateData requires both + SecAccess_Read and SecAccess_Write for + DataAccess. + + ESPservice [auth_feature("DataAccess:Read")] DataService { ESPmethod GetData(GetDataRequest, GetDataResponse); ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); }; - GetData requires SecAccess_Read; UpdateData requires both SecAccess_Read and SecAccess_Write for DataAccess. - Example 3: Method bypassing service authentication - + Method bypassing service + authentication + + GetData requires SecAccess_Full + access; GetPublicData requires no access for + DataAccess. + + ESPservice [auth_feature("DataAccess:Full")] DataService { ESPmethod GetData(GetDataRequest, GetDataResponse); ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); }; - GetData requires SecAccess_Full access; GetPublicData requires no access for DataAccess. - - - Overview - An auth_feature string is a comma-delimited list of tokens, interpreted in order from service (lowest precedence) to method (highest precedence), and processed in reverse order. - ESPservice values take effect at the EsdlService scope, while ESPmethod values are in the EsdlMethod scope and override service scope requirements. If auth_feature is set on both service and method, the resulting security requirement is the union, with method-level tokens taking precedence where conflicts arise. - See the formal BNF specification and parsing details below for precise semantics. - + An auth_feature string is a comma-delimited list + of tokens, interpreted in order from service (lowest precedence) to method + (highest precedence), and processed in reverse order. + + ESPservice values take effect at the + EsdlService scope, while ESPmethod values are in + the EsdlMethod scope and override service scope requirements. + If auth_feature is set on both service and method, the + resulting security requirement is the union, with method-level tokens taking + precedence where conflicts arise. + + See the formal BNF specification and parsing details for precise + semantics. + + Token Semantics + + Each auth_feature may include universal tokens + and feature-specific tokens, each with well-defined semantics and + support. + Feature-Independent Tokens - - Token Semantics and Categories - Each auth_feature may include universal tokens and feature-specific tokens, each with well-defined semantics and support. + The following tokens are universally supported and do not reference + any specific feature: - - Feature-Independent Tokens + + + - The following tokens are universally supported and do not - reference any specific feature: + + + None - - - + No feature access required. Standalone: disables access + checks; combined: ignored. Supported by esdllib + and hidl. + - - - None + + Deferred - No feature access required. Standalone: disables access - checks; combined: ignored. Supported by - esdllib and hidl. - + Equivalent to None; security may be + enforced dynamically by the method handler. Supported by + esdllib and hidl. + - - Deferred + + !X (where X is any value) - Equivalent to None; security may be - enforced dynamically by the method handler. Supported by - esdllib and hidl. - + Reserved for future semantics; constraints on X to be + defined. New syntax. + + + + - - !X (where X is any value) + Permitted Feature-Specific + Tokens - Reserved for future semantics; constraints on X to be - defined. New syntax. - - - - - + For a feature named MyFeature, permitted tokens + include: - - Permitted Feature-Specific Tokens + + + - For a feature named MyFeature, permitted tokens - include: + - - - + + + Token - + SecAccess Required - - - Token + Supported By + - SecAccess Required + + MyFeature - Supported By - + SecAccess_Read - - MyFeature + esdllib + - SecAccess_Read + + MyFeature:Access - esdllib - + SecAccess_Access - - MyFeature:Access + esdllib, hidl + - SecAccess_Access + + MyFeature:Read - esdllib, hidl - + SecAccess_Read - - MyFeature:Read + esdllib, hidl + - SecAccess_Read + + MyFeature:Write - esdllib, hidl - + SecAccess_Write - - MyFeature:Write + esdllib, hidl + - SecAccess_Write + + MyFeature:Full - esdllib, hidl - + SecAccess_Full - - MyFeature:Full + esdllib, hidl + - SecAccess_Full + + MyFeature:None - esdllib, hidl - + No access required (overrides service attribute) - - MyFeature:None + esdllib, hidl + - No access required (overrides service attribute) + + MyFeature:Deferred - esdllib, hidl - + Equivalent to None - - MyFeature:Deferred + esdllib, hidl + + + + - Equivalent to None + Forbidden Tokens - esdllib, hidl - - - - - + The following tokens are not permitted for feature + MyFeature: - - Forbidden Tokens - The following tokens are not permitted for feature MyFeature: - - - - - - MyFeature: - Not permitted; shortcut not needed; accepted by hidl as equivalent to MyFeature:Read. - - - MyFeature:X (where X is not listed above) - Invalid token; error; accepted by hidl as equivalent to MyFeature:Full. - - - - - - - Formal Syntax (Pseudo-BNF) - auth_feature tokens follow the grammar and precedence below: - - token ::= ( exclusion | suppression | deferral | assignment ) + + + + + + + MyFeature: + + Not permitted; shortcut not needed; accepted by hidl as + equivalent to MyFeature:Read. + + + + MyFeature:X (where X is not listed + above) + + Invalid token; error; accepted by hidl as equivalent to + MyFeature:Full. + + + + + + Formal Syntax: + + auth_feature tokens follow the grammar and + precedence as demonstrated below: + + token ::= ( exclusion | suppression | deferral | assignment ) exclusion ::= ( exclude-all | exclude-scope | exclude-feature | exclude-feature-in-scope ) ; no form of exclusion satisfies a requirement to affirmatively specify security exclude-all ::= '!' [ '::' ] @@ -242,21 +269,18 @@ reserved-word ::= scope-name | access-level feature-name ::= ( feature-name-char* '${' variable-name '}' feature-name-char* | feature-name-char+ ) ; feature-name-char is any char except whitespace, ',', '"', '!', or ':' ; feature-name has the added restrictions of not being a reserved-word -variable-name ::= ( 'SERVICE' | 'METHOD' ) - +variable-name ::= ( 'SERVICE' | 'METHOD' ) + + Note: The method scope overtakes the + service scope: a method may override any or all requirements set at the + service level by its own auth_feature string. + + Note: The method scope overtakes the + service scope: a method may override any or all requirements set at the + service level by its own auth_feature string. - Note: The method scope overtakes - the service scope: a method may override any or all requirements set at - the service level by its own auth_feature - string. -Note: The method scope overtakes the service scope: a method may override any or all requirements set at the service level by its own auth_feature string. - - - See Also - - ESPservice, - ESPmethod, - ESDL Attributes - - - \ No newline at end of file + See Also: ESPservice, ESPmethod, ESDL + Attributes + From cf48b5844dddab3fd102804edae8c10175db0bc8 Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Mon, 6 Apr 2026 14:56:41 -0400 Subject: [PATCH 5/7] HPCC-22655 Updates to the AuthFeature Signed-off-by: Panagiotatos --- docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index acc640b383c..1a669e60a72 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,5 +1,5 @@ - auth_feature @@ -280,7 +280,7 @@ variable-name ::= ( 'SERVICE' | 'METHOD' ) service level by its own auth_feature string. See Also: ESPservice, ESPservice, ESPmethod, ESDL Attributes From 8dc9bcb748da011be4189b8eb100a4e9230e2bd9 Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Mon, 6 Apr 2026 16:06:39 -0400 Subject: [PATCH 6/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index 1a669e60a72..34bb783078a 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -6,7 +6,7 @@ auth_feature - The auth_feature attribute configures + The auth_feature attribute configures feature-level security in ESDL by associating features and access levels to ESPservice and ESPmethod elements. This provides fine-grained, declarative access control for ESDL services and From eae8d891f8ba56a27af7bfd4eba154643195091a Mon Sep 17 00:00:00 2001 From: Panagiotatos Date: Tue, 7 Apr 2026 07:39:07 -0400 Subject: [PATCH 7/7] HPCC-22655 Update ESDL auth_feature documentation Signed-off-by: Panagiotatos --- docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index 34bb783078a..9fcc2fb2298 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -281,6 +281,5 @@ variable-name ::= ( 'SERVICE' | 'METHOD' ) See Also: ESPservice, ESPmethod, ESDL - Attributes + linkend="ESPmethod">ESPmethod