TransformAttributes

Introduction and overview

This AuthState supports generic context attribute transformations (useful to glue different AuthStates together in complex setups). It can be used to base64-encode session attributes or return input arguments after URL-encoding them to be used directly in login renderers. The TransformAttributes AuthState can also be used to implement a mapping of variable values. This is achieved by using constant strings as dummy conditions. See the examples for a demonstration of this principle. To modify the roles assigned to a user, the special pseudo-scope roles may be used. See Scopes and predefined variables.

The TransformAttributes does not rely on the order of the property elements in the esauth4.xml. In case you have a dependency between variables that cannot be resolved inline, use multiple TransformAttributes or a ScriptState.

note

The TransformAttributes AuthState may not support some complex transformations. In these cases, use the more flexible ScriptState AuthState instead. See ScriptState for more information about the ScriptState AuthState.

Passwords in the configuration are not supported by all properties in the TransformAttributes AuthState. It is only supported by the cryptoKey property.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.standard.TransformAttributes
Logging	StdStates
Auditing	none
Marker	none
Methods	process (all events)

Properties

• writeEmptyValues (boolean, false)

  When set to true, this property causes the AuthState to write variable values even if the value is an empty string.

  info

  If removeOnEmptyValue is set to true, it will take precedence over this property; the value will be removed.

• removeOnEmptyValue (boolean, false)

  If activated, this property causes the AuthState to remove the variable when the variable value is empty.

• cryptoKey Cryptographic Keymaterial, null)

  A secret key to use for encryption and decryption filters. See the description of the passPhrase attribute (keyObject) for a list of accepted syntaxes (go to Certificate validation).

• cryptoAlgorithm (JCE Cryptography Algorithm Name, null)

  The name of the cryptographic algorithm to use for encryption and decryption filters.

• hashAlgorithm (Java Hashing Algorithm Name, null)

  The name of the digest algorithm to use for hashing filters.

• [<condition>?]<destination>:<name>[:<filter>] A constant or variable description that is processed by the generic variable substitution.

  • <destination> is one of the context sources described in Configuration expressions that should be used to store the new attribute, given by <name>.

  • <filter> is optional and one of:

    • base64enc encode to base64
    • base64dec decode from base64
    • urlenc apply URL-encoding
    • urldec apply URL-decoding
    • encrypt-hex, encrypt-b64 encrypt and encode to hex or base64, respectively
    • decrypt-hex, decrypt-b64 decode from hex or base64, respectively and decrypt
    • hash-hex, hash-b64 apply hash algorithm and encode to hex or base64, respectively

  • <condition> is optional and one of:

    • ${variable}?

      Data referenced by the variable exists.

    • !${variable}?

      Data referenced by the variable does not exist.

    • ${variable}==expected?

      Data referenced by the variable exists and is exactly equal to the value "expected".

    • ${variable}!=expected?

      Data referenced by the variable exists and is not equal to the value "expected".

Input

none (except if referenced as inargs variable)

Transitions

• ok or default (depending on what is configured. A transition to the next non-final state is expected.)

Output

none

Errors

none

Notes

none

Example

<AuthState name="TransformAttributes" class="ch.nevis.esauth.auth.states.standard.TransformAttributes" final="false">
    <ResultCond name="default" next="AuthDone"/>
    <Response value="AUTH_CONTINUE"/>
    <property name="cryptoKey" value="secret://xABbOEpdP48VmxqEbefUoRjbPHP5L0T7"/>
    <property name="cryptoAlgorithm" value="AES/CTR/PKCS5Padding"/>
    <property name="hashAlgorithm" value="SHA256"/>
    <property name="sess:mysessarg" value="just_a_constant"/>
    <property name="outargs:myuserid" value="${request:userId}"/>
    <property name="sess:saml.SAMLResponse.b64:base64enc" value="${sess:saml.SAMLResponse}"/>
    <property name="outargs:encrypted:encrypt-hex" value="${notes:secret_input}"/>
    <property name="notes:decrypted:decrypt-b64" value="${inargs:secret_output}"/>
    <property name="notes:hashed:hash-hex" value="${sess:something_to_hash}"/>
</AuthState>

Mapping example

<AuthState name="MapValues"  class="ch.nevis.esauth.auth.states.standard.TransformAttributes" final="false">
    <ResultCond name="default" next="..."/>
    <Response value="AUTH_ERROR"/>
    <property name="myProperty?outargs:outvar" value="${inargs:invar:^.foo.$:found foo!}"/>
    <property name="exampleProperty?outargs:outvar" value="${inargs:invar:^.bar.$:found bar!}"/>
    <property name="customProperty?outargs:outvar" value="${inargs:invar:^.rofl.$:found rofl!}"/>
</AuthState>

<!--
   The generic structure for mapping entries is:
   <property name="<unique-constant>?<destination-scope>:<destination-var>"
       value="${<source-scope>:<source-var>:<regex-condition>:<mapped-value>}" />
-->

Modifying roles example

<AuthState name="AddRoles" class="ch.nevis.esauth.auth.states.standard.TransformAttributes" final="false">
  <ResultCond name="default" next="RedirectToApp"/>
  <Response value="AUTH_CONTINUE"/>
  <property name="roles:add" value="${notes:newRoles}"/>
</AuthState>

Encryption

The purpose of the encryption filter feature is obfuscation of short living internal data.

Recommendations

Attribute	Recommendation
cryptoAlgorithm	AES/CTR/PKCS5Padding
cryptoKey	Key with at least 256 or 512 length and changed in at least every quarter

In case the encrypted data is stored for long term in the file system or database, it is recommended to apply an additional layer of encryption outside of nevisAuth.

Supported Algorithms

The following algorithms are supported for encryption (specified using the cryptoAlgorithm attribute):

• AES/CBC/NoPadding Use CBC only if you know how to handle padding oracle attacks.
• AES/GCM/NoPadding
• AES/PCBC/NoPadding
• AES/PCBC/PKCS5Padding
• AES/CFB/NoPadding
• AES/CFB/PKCS5Padding
• AES/OFB/NoPadding
• AES/OFB/PKCS5Padding
• AES/CTS/NoPadding
• AES/CTS/PKCS5Padding
• AES/CTR/NoPadding
• AES/CTR/PKCS5Padding
• AES/CCM/NoPadding
• AES/ECB/NoPadding
• AES/ECB/PKCS5Padding
• Blowfish/PCBC/NoPadding
• Blowfish/PCBC/PKCS5Padding
• Blowfish/CFB/NoPadding
• Blowfish/CFB/PKCS5Padding
• Blowfish/OFB/NoPadding
• Blowfish/OFB/PKCS5Padding
• Blowfish/CTS/NoPadding
• Blowfish/CTS/PKCS5Padding
• Blowfish/CTR/NoPadding
• Blowfish/CTR/PKCS5Padding
• Blowfish/ECB/NoPadding
• Blowfish/ECB/PKCS5Padding

Encrypted Data Format

When the encryption algorithm requires an initialization vector, the initialization vector is required to decrypt the data. This is why the initialization vector is provided at the beginning of the returned encrypted data. The returned byte array (encoded using Base64 or HEX) will be the concatenation of the IV (if required by the algorithm) and the resulting encrypted data:

<Initialization Vector><Encrypted Data>

The length of the initialization vector for each of the algorithms is the following:

Encryption Algorithm	Initialization Vector Length	Authentication tag length
AES/GCM/NoPadding	12	128
AES/PCBC/NoPadding	16
AES/PCBC/PKCS5Padding	16
AES/CFB/NoPadding	16
AES/CFB/PKCS5Padding	16
AES/OFB/NoPadding	16
AES/OFB/PKCS5Padding	16
AES/CTS/NoPadding	16
AES/CTS/PKCS5Padding	16
AES/CTR/NoPadding	16
AES/CTR/PKCS5Padding	16
AES/CCM/NoPadding	7
Blowfish/PCBC/NoPadding	8
Blowfish/PCBC/PKCS5Padding	8
Blowfish/CFB/NoPadding	8
Blowfish/CFB/PKCS5Padding	8
Blowfish/OFB/NoPadding	8
Blowfish/OFB/PKCS5Padding	8
Blowfish/CTS/NoPadding	8
Blowfish/CTS/PKCS5Padding	8
Blowfish/CTR/NoPadding	8
Blowfish/CTR/PKCS5Padding	8