diff --git a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml index 3b511c33b4e..9fcc2fb2298 100644 --- a/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml +++ b/docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml @@ -1,48 +1,285 @@ - - + auth_feature 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 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. - - 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. - - Example: - - 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); - }; + 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. + + Examples: + + Service-level authentication + + Both GetData and ListData + require SecAccess_Read access for + DataAccess. + + +ESPservice [auth_feature("DataAccess:Read")] DataService +{ + ESPmethod GetData(GetDataRequest, GetDataResponse); + ESPmethod ListData(ListDataRequest, ListDataResponse); +}; + + + 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); +}; + + + 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); +}; + + + 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 + + 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. + + + + + + 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 ::= '!' [ '::' ] + ; 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 + ; 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. + + 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