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.

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

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.standard.TransformAttributes
Logging	StdStates
Auditing	none
Properties	createSession (boolean, false)Defines whether to create a new session when a session variable should be written and no session exists yet.
	writeEmptyValues (boolean, false)When activated, this property causes the AuthState to write variable values even if the value is an empty string.
	removeOnEmptyValue (boolean, false)If activated, this property causes the AuthState to remove the variable when the variable value is empty.
	cryptoKey ").
	cryptoAlgorithm (JCE Cryptography Alogrithm 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".
Methods	process (all events)
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>

Example(mapping)

<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>}" />
-->

Example (modifying roles)

<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/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 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
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