[KNOX-2983] Combine the functionality of different identity assertion providers

• Type: Improvement
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.1.0
• Assignee: Attila Magyar
• Reporter: Attila Magyar
• Created: 07/Nov/23 12:41
• Updated: 27/Feb/24 10:43
• Resolved: 16/Nov/23 23:32

Description

Motivation

Currently there is no way to add multiple identity assertion providers and combine the functionality of them. For example one might want to use the Concat identity assertion together with the Switch case provider. This is not possible due to a limitation of Knox which only allows having one identity assertion provider in the topology. Additionally, having a distinct provider for each functionality has its own limitations that prevents expressing complex mappings.

Expression-Based principal mapping

The idea behind the Expression-Based principal mapping is that it leverages the language that was introduced by https://issues.apache.org/jira/browse/KNOX-2707.

<provider>
  <role>identity-assertion</role>
  <name>HadoopGroupProvider</name>
  <enabled>true</enabled>
  <param>
    <name>expression.principal.mapping</name>
    <!-- expression that returns the new principal -->
    <value>...</value>
  </param>
  [...]
</provider>

The value of expression.principal.mapping must be a valid expression that evaluates to a string, which will be the new, mapped principal.

For example, in the following example all authenticated users will be mapped to principal: 'bob'.

<param>
  <name>expression.principal.mapping</name>
  <value>'bob'</value>
</param>

By adding a conditional you can selectively apply the mapping to specific users.

<param>
  <name>expression.principal.mapping</name>
  <!-- Only map sam/tom to bob -->
  <value>
    (if (or (= username 'sam') 
            (= username 'tom')) 
        'bob')
  </value>
</param>

When the expression returns null, the original principal will be unchanged.

Reference

if

The if is an expression (rather than a statement), that has 2 or 3 parameters. When you call it with 2 parameters it will behave like an if-then, when you call it with 3 parameters it will behave like an if-then-else expression.

The first parameters is a conditional that must evaluate to either true or false. In case of true, the first branch is evaluated, otherwise the 2nd branch is evaluated. If the 2nd branch is omitted, and the conditional is false, then null is returned.

Returns 1:

(if true 1)

Returns null:

(if false 1)

Returns 2:

(if false 1 2)

Returns 1:

(if true 1 2)

concat

The concat function takes variable number of arguments and concats them into one single string.

(concat 'The' 'sun' 'will' 'come' 'up' 'tomorrow.')

This can be used to concat/prepend a prefix or suffix to the usename.

(concat 'prefix_' username '_suffix')

uppercase / lowercase

Convert a string to upper case and lower case letters.

(uppercase 'sam')

returns 'SAM'

(lowercase 'SAM')

returns 'sam'

The combination of uppercase/lowercase and concat can be used to capitalize a username

(concat
    (uppercase (substr username 0 1))
    (lowercase (substr username 1)))

substr

The substr function works the same way as Java's subString. It takes one or two parameters, where the first is the begin index, and the second is the end index.

The substring begins with the character at the specified index and extends to the end of this string.

(substr 'unhappy' 2)

returns 'happy'

The end index is exclusive. The substring begins at the specified beginIndex and extends to the character at index endIndex - 1.

(substr 'hamburger' 4 8) 

returns 'urge'

strlen

The strlen function returns the length of a string.

(strlen 'apple')

returns 5

For example, a combination of substr and strlen can be used to cut the first and last characters of a username

(substr username 1 (- (strlen username) 1))  

contains

Check if a string includes a substring.

(contains 'dm' 'admin')

returns true since 'admin' contains 'dm'

index-of

Find a substring in the given string and return the (zero based) index.

(index-of 'ppl' 'apple')

returns 1

(index-of 'xx' 'apple')

If the given substring is not found, -1 is returned.

For example this will find the '@' substring, and return the part coming after the '@' sign.

(if (contains '@' username)
    (substr username (+ (strlen '@') 
                        (index-of '@' username))))

[e-mail] will be converted to hwx.site

Similarly, this will cut everything after the @ sign, including the @ sign.

(if (contains '@' username)
    (substr username 0 (index-of '@' username)))

[e-mail] will be converted to admin

starts-with / ends-with

starts-with and ends-with can be used to check if a string begins or ends with a given substring.

(starts-with 'apple' 'app')

returns true

(ends-with 'apple' 'ple')

returns false

For example, remove a prefix from a username

(if (starts-with username 'prefix_')
    (substr username (strlen 'prefix_')))

prefix_admin will be converted to admin

hash

The hash function creates a hash table for holding key value pairs. The number or arguments varies, but it must be an even number.

(hash)

returns an empty hash table

(hash 'key1' 'value1' 'key2' 'value2')

returns a hash table with key1=value1, and key2=value2.

at

The at function returns the value for the given key from a hash table.

(at username 
    (hash
         'tom' 'Thomas'
         'sam' 'Samual'
         'admin' 'Administrator'))

This maps the user 'admin' to 'Administrator', 'tom' to 'Thomas' and 'sam' to 'Samuel'

regex-template

The regex-template template function works the same was as the Regex type identity assertion provider.

(regex-template  username '(.*)@(.*?)\..*' '{1}_{[2]}' (hash 'us' 'USA' 'ca' 'CANADA') true)

The above expression turns '[e-mail]' to 'nobody_USA'.

The regular expression contains optional groups and the template can reference those groups. The last 2 parameters are optional. For more information see.

Issue Links

• is related to: KNOX-2988 Documentation for KNOX-2983
• links to: GitHub Pull Request #817