Encoding Attribute Values

There are two ways to encode attribute values for managed objects—reversible encryption and salted hashing algorithms. Attribute values that might be encoded include passwords, authentication questions, credit card numbers, and social security numbers. If passwords are already encoded on the external resource, they are generally excluded from the synchronization process. For more information, see Secure Passwords.

You configure attribute value encoding, per schema property, in the managed object configuration (in your project's conf/managed.json file). The following sections show how to use reversible encryption and salted hash algorithms to encode attribute values.

Encoding Attribute Values With Reversible Encryption

The following excerpt of a managed.json file shows a managed object configuration that encrypts and decrypts the password attribute using the default symmetric key:

{
    "objects" : [
        {
            "name" : "user",
            ...
            "schema" : {
                ...
                "properties" : {
                    ...
                    "password" : {
                        "title" : "Password",
                        ...
                        "encryption" : {
                            "purpose" : "idm.password.encryption"
                        },
                        "scope" : "private",
                    }
            ...
        }
    ]
}

To encrypt attribute values from the command-line, see "encrypt".

To Configure Encryption Through the UI

Select Configure > Managed Objects, and select the object type whose property values you want to encrypt (for example User).
On the Properties tab, select the property whose value should be encrypted and select the Encrypt checkbox.

Encoding Attribute Values by Using Salted Hash Algorithms

To encode attribute values with salted hash algorithms, add the secureHash property to the attribute definition and define the hashing configuration. The configuration depends on the algorithm that you choose.

If you do not specify an algorithm, SHA-256 is used by default. MD5 and SHA-1 are supported for legacy reasons but you should use a more secure algorithm in production environments.

The following list shows the supported hash algorithms and their configurations:

SHA-256

"secureHash" : {
    "algorithm" : "SHA-256",
    "saltLength" : 16
}

SHA-384

"secureHash" : {
    "algorithm" : "SHA-384",
    "saltLength" : 16
}

SHA-512

"secureHash" : {
    "algorithm" : "SHA-512",
    "saltLength" : 16
}

Bcrypt

"secureHash" : {
    "algorithm" : "BCRYPT",
    "cost" : 16
}

Scrypt

"secureHash" : {
    "algorithm" : "SCRYPT",
    "hashLength" : 16,
    "saltLength" : 16,
    "n" : 32768,
    "r" : 8,
    "p" : 1
}

Password-Based Key Derivation Function 2 (PBKDF2)

"secureHash" : {
    "algorithm" : "PBKDF2",
    "hashLength" : 16,
    "saltLength" : 16,
    "iterations" : 10,
    "hmac" : "SHA-256"
}

Warning

Some one-way hash functions are designed to be computationally expensive. Functions such as PBKDF2, Bcrypt, and Scrypt are designed to be relatively slow even on modern hardware. This makes them generally less susceptible to brute force attacks. However, computationally expensive functions can dramatically increase response times. If you use these functions, be aware of the performance impact and perform extensive testing before deploying your service in production. Do not use functions like PBKDF2 and Bcrypt for any accounts that are used for frequent, short-lived connections.

Hashing is a one-way operation, such that the original value cannot be recovered. Therefore, if you hash the value of any property, you cannot synchronize that property value to an external resource. For managed object properties with hashed values, you must either exclude those properties from the mapping or set a random default value if the external resource requires the property.

The following excerpt of a managed object configuration shows that values of the password attribute are hashed using the SHA-256 algorithm:

{
    "objects" : [
        {
            "name" : "user",
            ...
            "schema" : {
                ...
                "properties" : {
                    ...
                    "password" : {
                        "title" : "Password",
                        ...
                        "secureHash" : {
                            "algorithm" : "SHA-256"
                        },
                        "scope" : "private",
                    }
            ...
        }
    ]
}

To hash attribute values from the command-line, see "secureHash".

To Configure Hashing Through the UI

You can configure hashing of properties through the Admin UI, but the functionality is limited to setting the hash algorithm. Not all algorithms are supported in the UI, and none of the enhanced configuration options are supported. To configure attribute hashing in the UI:

Select Configure > Managed Objects, and select the object type whose property values you want to hash (for example, User).
On the Properties tab, select the property whose value must be hashed, select Privacy & Encryption, then select the Hashed checkbox.
Select the algorithm that should be used to hash the property value.