Author: amagyar
Date: Wed Mar 30 08:15:50 2022
New Revision: 1899380
URL: http://svn.apache.org/viewvc?rev=1899380&view=rev
Log:
KNOX-2716 Document KNOX-2707 Virtual Group Mapping Provider
Modified:
knox/trunk/books/1.6.0/config_id_assertion.md
Modified: knox/trunk/books/1.6.0/config_id_assertion.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.6.0/config_id_assertion.md?rev=1899380&r1=1899379&r2=1899380&view=diff
==============================================================================
--- knox/trunk/books/1.6.0/config_id_assertion.md (original)
+++ knox/trunk/books/1.6.0/config_id_assertion.md Wed Mar 30 08:15:50 2022
@@ -24,7 +24,7 @@ The general responsibilities of the iden
2. determine whether it matches any group principal mapping rules and apply
them
3. if it is determined that the principal will be impersonating another
through a principal mapping rule then a Subject.doAS is required so providers
farther downstream can determine the appropriate effective principal name and
groups for the user
-#### Default Identity Assertion Provider ####
+###### Default Identity Assertion Provider ######
The following configuration is required for asserting the users identity to
the Hadoop cluster using Pseudo or Simple "authentication" and for using
Kerberos/SPNEGO for secure clusters.
<provider>
@@ -61,7 +61,7 @@ When a principal mapping is defined that
If there is no mapping to another principal then the authenticated or primary
principal is the effective principal.
-#### Principal Mapping ####
+###### Principal Mapping ######
<param>
<name>principal.mapping</name>
@@ -82,7 +82,7 @@ For multiple mappings:
<value>guest,alice=hdfs;mary=alice2</value>
</param>
-#### Group Principal Mapping ####
+###### Group Principal Mapping ######
<param>
<name>group.principal.mapping</name>
@@ -98,7 +98,256 @@ For instance:
this configuration indicates that all (*) authenticated users are members of
the "users" group and that user "hdfs" is a member of the admin group. Group
principal mapping has been added along with the authorization provider
described in this document.
-#### Concat Identity Assertion Provider ####
+
+###### Group Mapping Based on Predicates ######
+
+ <param>
+ <name>group.mapping.{mappedGroupName}</name>
+ <value>{predicate}</value>
+ </param>
+
+
+The predicate-based group mapping offers more flexibility by allowing the use
of arbitrary logical expressions to define the mappings. The predicate
expression must evaluate to a boolean result, true or false. The syntax is
inspired by the Lisp language, but it is limited to boolean expressions and
comparisons.
+
+For instance:
+
+ <param>
+ <name>group.mapping.admin</name>
+ <value>(or (username 'guest') (member 'analyst'))</value>
+ </param>
+
+This configuration maps the user to the "admin" group if either the
authenticated user is "guest" or the authenticated user is a member of the
"analyst" group.
+
+The syntax of the language is based on parenthesized prefix notation, meaning
that the operators precede their operands.
+
+The language is made up of two basic building blocks: atoms (boolean, string,
number, symbol) and lists. A list is written with its elements separated by
whitespace, and surrounded by parentheses. A list can contain other lists or
atoms.
+
+A function call or an operator is written as a list with the function or
operator's name first, and the arguments following. For instance, a function f
that takes three arguments would be called as (f arg1 arg2 arg3).
+
+
+Lists are of arbitrary length and can be nested to express more complex
conditionals.
+
+ (or
+ (and
+ (member 'admin')
+ (member 'scientist'))
+ (or
+ (username 'tom')
+ (username 'sam')))
+
+Returns:
+
+1. True if the user is either 'tom' or 'sam'
+2. True if the user is both in the 'admin' and the 'scientist' group.
+3. False otherwise.
+
+The following predicate checks if the user is a member of any group:
+
+ (!= (size groups) 0)
+
+ (not (empty groups))
+
+ (match groups '.*')
+
+
+This predicate checks if the username is either "tom" or "sam":
+
+ (match username 'tom|sam')
+
+This checks the username in a case insensitive manner:
+
+ (= (lowercase username) 'bob')
+
+
+##### Supported functions and operators #####
+
+###### or ######
+Evaluates true if one or more of its operands is true. Supports short-circuit
evaluation and variable number of arguments.
+
+Number of arguments: 1..N
+
+ (or bool1 bool2 ... boolN)
+
+Example
+
+ (or true false true)
+
+###### and ######
+Evaluates true if all of its operands are true. Supports short-circuit
evaluation and variable number of arguments.
+
+Number of arguments: 1..N
+
+ (and bool1 bool2 ... boolN)
+
+Example
+
+ (and true false true)
+
+###### not ######
+Negates the operand.
+
+Number of arguments: 1
+
+ (not aBool)
+
+Example
+
+ (not true)
+
+###### = ######
+Evaluates true if the two operands are equal.
+
+Number of arguments: 2
+
+ (= op1 op2)
+
+Example
+
+ (= 'apple' 'orange')
+
+###### != ######
+Evaluates true if the two operands are not equal.
+
+Number of arguments: 2
+
+ (!= op1 op2)
+
+Example
+
+ (!= 'apple' 'orange')
+
+###### member ######
+Evaluates true if the current user is a member of the given group
+
+Number of arguments: 1
+
+ (member aString)
+
+Example
+
+ (member 'analyst')
+
+###### username ######
+Evaluates true if the current user has the given username
+
+Number of arguments: 1
+
+ (username aString)
+
+Example
+
+ (username 'admin')
+
+This is a shorter version of (= username 'admin')
+
+###### size ######
+Gets the size of a list
+
+Number of arguments: 1
+
+ (size alist)
+
+Example
+
+ (size groups)
+
+###### empty ######
+Evaluates to true if the given list is empty
+
+Number of arguments: 1
+
+ (empty alist)
+
+Example
+
+ (empty groups)
+
+###### match ######
+Evaluates true if the given string matches to the given regexp. Or any items
of the given list matches the given regexp.
+
+Number of arguments: 2
+
+ (match aString aRegExpString)
+
+ (match aList aRegExpString)
+
+Example
+
+ (match username 'tom|sam')
+
+This function can also take a list as a first argument. In this case it will
return true if the regexp matches to any of the items in the list.
+
+ (match groups 'analyst|scientist')
+
+This returns true if the user is either in the 'analyst' group or in the
'scientist' group. The same can be expressed by combining 2 member functions
with an or expression.
+
+###### request-header ######
+Returns the value of the specified request header as a String. If the given
key doesn't exist empty string is returned.
+
+Number of arguments: 1
+
+ (request-header aString)
+
+Example
+
+ (request-header 'User-Agent')
+
+###### request-attribute ######
+Returns the value of the specified request attribute as a String. If the given
key doesn't exist empty string is returned.
+
+Number of arguments: 1
+
+ (request-attribute aString)
+
+Example
+
+ (request-attribute 'sourceRequestUrl')
+
+###### session ######
+
+Returns the value of the specified session attribute as a String. If the given
key doesn't exist empty string is returned.
+
+Number of arguments: 1
+
+ (session aString)
+
+Example
+
+ (session 'subject.userRoles')
+
+###### lowercase ######
+Converts the given string to lowercase.
+
+Number of arguments: 1
+
+ (lowercase aString)
+
+Example
+
+ (lowercase 'KNOX')
+
+###### uppercase ######
+Converts the given string to uppercase.
+
+Number of arguments: 1
+
+ (uppercase aString)
+
+Example
+
+ (uppercase 'knox')
+
+
+### Constants ###
+The following constants are populated automatically from the current security
context.
+
+###### username ######
+The username (principal) of the current user, derived from
javax.security.auth.Subject.
+
+###### groups ######
+The groups of the current user (as determined by the authentication provider),
derived from subject.getPrincipals(GroupPrincipal.class).
+
+###### Concat Identity Assertion Provider ######
The Concat identity assertion provider allows for composition of a new user
principal through the concatenation of optionally configured prefix and/or
suffix provider parameters. This is a useful assertion provider for converting
an incoming identity into a disambiguated identity within the Hadoop cluster
based on what topology is used to access Hadoop.
The following configuration would convert the user principal into a value that
represents a domain specific identity where the identities used inside the
Hadoop cluster represent this same separation.
@@ -117,7 +366,7 @@ The above configuration will result in a
In addition to the concat.suffix parameter, the provider supports the setting
of a prefix through a `concat.prefix` parameter.
-#### SwitchCase Identity Assertion Provider ####
+###### SwitchCase Identity Assertion Provider ######
The SwitchCase identity assertion provider solves issues where down stream
ecosystem components require user and group principal names to be a specific
case.
An example of how this provider is enabled and configured within the
`<gateway>` section of a topology file is shown below.
This particular example will switch user principals names to lower case and
group principal names to upper case.
@@ -146,7 +395,7 @@ group.principal.case | The case mapping
If no parameters are provided the full defaults will results in both user and
group principal names being switched to lower case.
A setting of "none" or anything other than "upper" or "lower" leaves the case
of the principal name unchanged.
-#### Regular Expression Identity Assertion Provider ####
+###### Regular Expression Identity Assertion Provider ######
The regular expression identity assertion provider allows incoming identities
to be translated using a regular expression, template and lookup table.
This will probably be most useful in conjunction with the HeaderPreAuth
federation provider.
@@ -215,27 +464,27 @@ The 'hadoop.security.group.mapping' prop
</param>
Some of the valid implementations are as follows:
-#### org.apache.hadoop.security.JniBasedUnixGroupsMappingWithFallback
+###### org.apache.hadoop.security.JniBasedUnixGroupsMappingWithFallback
This is the default implementation and will be picked up if
'hadoop.security.group.mapping' is not specified. This implementation will
determine if the Java Native Interface (JNI) is available. If JNI is available,
the implementation will use the API within Hadoop to resolve a list of groups
for a user. If JNI is not available then the shell implementation,
`org.apache.hadoop.security.ShellBasedUnixGroupsMapping`, is used, which shells
out with the `bash -c id -gn <user> ; id -Gn <user>` command (for a Linux/Unix
environment) or the `groups -F <user>` command (for a Windows environment) to
resolve a list of groups for a user.
-#### org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMappingWithFallback
+###### org.apache.hadoop.security.JniBasedUnixGroupsNetgroupMappingWithFallback
As above, if JNI is available then we get the netgroup membership using Hadoop
native API, else fallback on ShellBasedUnixGroupsNetgroupMapping to resolve
list of groups for a user.
-#### org.apache.hadoop.security.ShellBasedUnixGroupsMapping
+###### org.apache.hadoop.security.ShellBasedUnixGroupsMapping
Uses the `bash -c id -gn <user> ; id -Gn <user>` command (for a Linux/Unix
environment) or the `groups -F <user>` command (for a Windows environment) to
resolve list of groups for a user.
-#### org.apache.hadoop.security.ShellBasedUnixGroupsNetgroupMapping
+###### org.apache.hadoop.security.ShellBasedUnixGroupsNetgroupMapping
Similar to `org.apache.hadoop.security.ShellBasedUnixGroupsMapping` except it
uses `getent netgroup` command to get netgroup membership.
-#### org.apache.hadoop.security.LdapGroupsMapping
+###### org.apache.hadoop.security.LdapGroupsMapping
This implementation connects directly to an LDAP server to resolve the list of
groups. However, this should only be used if the required groups reside
exclusively in LDAP, and are not materialized on the Unix servers.
-#### org.apache.hadoop.security.CompositeGroupsMapping
+###### org.apache.hadoop.security.CompositeGroupsMapping
This implementation asks multiple other group mapping providers for
determining group membership, see [Composite Groups
Mapping](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/GroupsMapping.html#Composite_Groups_Mapping)
for more details.
