HPCC-22655 Update ESDL auth_feature documentation #21025
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,48 +1,285 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | ||
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> | ||
| <sect1 id="ESDL_AuthFeature"> | ||
| <title>auth_feature</title> | ||
|
|
||
| <para><indexterm> | ||
| <primary>auth_feature</primary> | ||
| </indexterm>The <emphasis>auth_feature</emphasis> attribute configures | ||
| feature-level security in ESDL by associating features and access levels to | ||
| <code>ESPservice</code> and <code>ESPmethod</code> elements. This provides | ||
| fine-grained, declarative access control for ESDL services and | ||
| methods.</para> | ||
|
|
||
| <para><emphasis role="bold">Examples: </emphasis></para> | ||
|
|
||
| <para><emphasis role="bold">Service-level authentication</emphasis></para> | ||
|
|
||
| <para>Both <literal>GetData</literal> and <literal>ListData</literal> | ||
| require <literal>SecAccess_Read</literal> access for | ||
| <literal>DataAccess</literal>.</para> | ||
|
|
||
| <programlisting> | ||
| ESPservice [auth_feature("DataAccess:Read")] DataService | ||
| { | ||
| ESPmethod GetData(GetDataRequest, GetDataResponse); | ||
| ESPmethod ListData(ListDataRequest, ListDataResponse); | ||
| }; | ||
| </programlisting> | ||
|
|
||
| <para><emphasis role="bold">Combined service and method | ||
| authentication</emphasis></para> | ||
|
|
||
| <para><literal>GetData</literal> requires <literal>SecAccess_Read</literal>; | ||
| <literal>UpdateData</literal> requires both | ||
| <literal>SecAccess_Read</literal> and <literal>SecAccess_Write</literal> for | ||
| <literal>DataAccess</literal>.</para> | ||
|
|
||
| <programlisting> | ||
| ESPservice [auth_feature("DataAccess:Read")] DataService | ||
| { | ||
| ESPmethod GetData(GetDataRequest, GetDataResponse); | ||
| ESPmethod [auth_feature("DataAccess:Write")] UpdateData(UpdateDataRequest, UpdateDataResponse); | ||
| }; | ||
| </programlisting> | ||
|
|
||
| <para><emphasis role="bold">Method bypassing service | ||
| authentication</emphasis></para> | ||
|
|
||
| <para><literal>GetData</literal> requires <literal>SecAccess_Full</literal> | ||
| access; <literal>GetPublicData</literal> requires no access for | ||
| <literal>DataAccess</literal>.</para> | ||
|
|
||
| <programlisting> | ||
| ESPservice [auth_feature("DataAccess:Full")] DataService | ||
| { | ||
| ESPmethod GetData(GetDataRequest, GetDataResponse); | ||
| ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse); | ||
|
There was a problem hiding this comment. Consider splitting into multiple lines to improve appearance. Text extends beyond block background. |
||
| }; | ||
| </programlisting> | ||
|
|
||
| <para>An <emphasis>auth_feature</emphasis> string is a comma-delimited list | ||
| of tokens, interpreted in order from service (lowest precedence) to method | ||
| (highest precedence), and processed in reverse order.</para> | ||
|
|
||
| <para><code>ESPservice</code> values take effect at the | ||
| <code>EsdlService</code> scope, while <code>ESPmethod</code> values are in | ||
| the <code>EsdlMethod</code> scope and override service scope requirements. | ||
|
There was a problem hiding this comment. ... and may either extend or override service scope requirements. The next sentence does reflect this, but it feels contradictory as written. |
||
| If <emphasis>auth_feature</emphasis> is set on both service and method, the | ||
| resulting security requirement is the union, with method-level tokens taking | ||
| precedence where conflicts arise.</para> | ||
|
|
||
| <para>See the formal BNF specification and parsing details for precise | ||
|
There was a problem hiding this comment. Similar to BNF, but may be better to not call it that. |
||
| semantics.</para> | ||
|
|
||
| <para><emphasis role="bold">Token Semantics</emphasis></para> | ||
|
|
||
| <para>Each <emphasis>auth_feature</emphasis> may include universal tokens | ||
| and feature-specific tokens, each with well-defined semantics and | ||
| support.</para> | ||
|
|
||
| <para><emphasis role="bold">Feature-Independent Tokens</emphasis></para> | ||
|
|
||
| <para>The following tokens are universally supported and do not reference | ||
| any specific feature:</para> | ||
|
|
||
| <informaltable colsep="1" frame="all" rowsep="1"> | ||
| <tgroup cols="2"> | ||
| <colspec colwidth="120pt"/> | ||
|
|
||
| <tbody> | ||
| <row> | ||
| <entry><literal>None</literal></entry> | ||
|
|
||
| <entry>No feature access required. Standalone: disables access | ||
| checks; combined: ignored. Supported by <literal>esdllib</literal> | ||
| and <literal>hidl</literal>.</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>Deferred</literal></entry> | ||
|
|
||
| <entry>Equivalent to <literal>None</literal>; security may be | ||
| enforced dynamically by the method handler. Supported by | ||
| <literal>esdllib</literal> and <literal>hidl</literal>.</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>!X</literal> (where X is any value)</entry> | ||
|
|
||
| <entry>Reserved for future semantics; constraints on X to be | ||
| defined. New syntax.</entry> | ||
|
Comment on lines
+109
to
+112
There was a problem hiding this comment. It is used. If you look in the formal syntax, it can negate all lower precedence settings (X is empty or |
||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </informaltable> | ||
|
|
||
| <para><emphasis role="bold">Permitted Feature-Specific | ||
| Tokens</emphasis></para> | ||
|
|
||
| <para>For a feature named <literal>MyFeature</literal>, permitted tokens | ||
| include:</para> | ||
|
|
||
| <informaltable colsep="1" frame="all" rowsep="1"> | ||
| <tgroup cols="3"> | ||
| <colspec colwidth="130pt"/> | ||
|
|
||
| <colspec colwidth="170pt"/> | ||
|
|
||
| <tbody> | ||
| <row> | ||
| <entry><literal>Token</literal></entry> | ||
|
|
||
| <entry><literal>SecAccess Required</literal></entry> | ||
|
|
||
| <entry><literal>Supported By</literal></entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature</literal></entry> | ||
|
|
||
| <entry>SecAccess_Read</entry> | ||
|
|
||
| <entry>esdllib</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:Access</literal></entry> | ||
|
|
||
| <entry>SecAccess_Access</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:Read</literal></entry> | ||
|
|
||
| <entry>SecAccess_Read</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:Write</literal></entry> | ||
|
|
||
| <entry>SecAccess_Write</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:Full</literal></entry> | ||
|
|
||
| <entry>SecAccess_Full</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:None</literal></entry> | ||
|
|
||
| <entry>No access required (overrides service attribute)</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:Deferred</literal></entry> | ||
|
|
||
| <entry>Equivalent to None</entry> | ||
|
|
||
| <entry>esdllib, hidl</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </informaltable> | ||
|
|
||
| <para><emphasis role="bold">Forbidden Tokens</emphasis></para> | ||
|
|
||
| <para>The following tokens are not permitted for feature | ||
| <literal>MyFeature</literal>:</para> | ||
|
|
||
| <informaltable colsep="1" frame="all" rowsep="1"> | ||
| <tgroup cols="2"> | ||
| <colspec colwidth="120pt"/> | ||
|
|
||
| <tbody> | ||
| <row> | ||
| <entry><literal>MyFeature:</literal></entry> | ||
|
|
||
| <entry>Not permitted; shortcut not needed; accepted by hidl as | ||
| equivalent to <literal>MyFeature:Read</literal>.</entry> | ||
| </row> | ||
|
|
||
| <row> | ||
| <entry><literal>MyFeature:X</literal> (where X is not listed | ||
| above)</entry> | ||
|
|
||
| <entry>Invalid token; error; accepted by hidl as equivalent to | ||
| <literal>MyFeature:Full</literal>.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </informaltable> | ||
|
|
||
| <para><emphasis role="bold">Formal Syntax: </emphasis></para> | ||
|
|
||
| <para><emphasis>auth_feature</emphasis> tokens follow the grammar and | ||
| precedence as demonstrated below:</para> | ||
|
|
||
| <programlisting> 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 | ||
|
There was a problem hiding this comment. The defined scopes for ecm defined features are: EsdlServie and EsdlMethod. DESDL adds BindingService and BindingMethod to the list. All values are case insensitive. The DESDL extensions have higher precedence than the ecm values, meaning EsdlService can be overridden by EsdlMethod, which can be overridden by BindingService, which can be overridden by BindingMethod.
Member
Author
There was a problem hiding this comment. this : The DESDL extensions have higher precedence than the ecm values, meaning EsdlService can be overridden by EsdlMethod, which can be overridden by BindingService, which can be overridden by BindingMethod. : better description
Member
Author
There was a problem hiding this comment. key is that DESDL introduces 2 additional scopes (and the key is you can 'override' ancestor scopes) |
||
| 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' ) </programlisting> | ||
|
There was a problem hiding this comment. This is not a program listing. It's a variation of a standard notation describing how the attribute value is assembled/interpreted. No part of it is meant to be copied and pasted by a user as a code sample. Any line beginning with ';' is a comment. These do not need to be presented in code style, except for text between back ticks. Feel free to format the lines as anything but code and, more importantly, line preservation is not required. Multiple comments are truncated by strictly preserving lines. |
||
|
|
||
| <para><emphasis role="bold">Note:</emphasis> The method scope overtakes the | ||
| service scope: a method may override any or all requirements set at the | ||
| service level by its own <emphasis>auth_feature</emphasis> string.</para> | ||
|
|
||
| <para><emphasis role="bold">Note:</emphasis> The method scope overtakes the | ||
| service scope: a method may override any or all requirements set at the | ||
| service level by its own <emphasis>auth_feature</emphasis> string.</para> | ||
|
Comment on lines
+278
to
+280
There was a problem hiding this comment. It's an important note but probably not worth repeating. |
||
|
|
||
| <para><emphasis role="bold">See Also: </emphasis> <link | ||
| linkend="EPservice">ESPservice</link>, <link | ||
| linkend="ESPmethod">ESPmethod</link></para> | ||
| </sect1> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The formal syntax refers to scope-name, which comes into play when discussing overriding settings. It may be good to associate scopes to the elements mentioned.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
add note: that this scope could relate