You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by am...@apache.org on 2022/03/30 08:15:50 UTC
svn commit: r1899380 - /knox/trunk/books/1.6.0/config_id_assertion.md
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.