Introduction

For security reasons, Ubisecure Identity Server does not store passwords as plaintext in the user data repository (LDAP). Password encoding is primarily a protection against two situations:

1. Casual observation. A system administrator who browses the user data repository will not accidentally see clear text passwords, only encrypted passwords. To prevent this, any scheme other than plain is sufficient.
2. Brute force to local copy of repository. An attacker who gains access to an offline copy of the user data repository and wants to recover clear text passwords by brute force.

• Salted schemes are better as the database required to keep encrypted passwords is significantly larger
• Schemes with more iterations (such as pkcs5s2, pbkdf2 and bcrypt) are better as it slows down brute force guessing
  
  

Supported hashing algorithms

The following page in the documentation lists the currently supported algorithms Management UI authentication methods - SSO 

If not specified, the default hashing algorithm is SSHA (Salted SHA1).

• Supported values are: 
  {BCRYPT}, {SSHA512}, {SHA512}, {SSHA384}, {SHA384}, {SSHA256}, {SHA256}, {SSHA}, {SHA}, {PKCS5S2}, {PBKDF2}, {PBKDF2-SHA256}, {MD4}, {PLAIN}
• An empty value means that the default password encoding of the Directory Service is used. For example, for SQL it is {SSHA} and for Ubisecure Directory it is {SSHA}. Please consult the specific Directory Integration guide for the default password encoding.

Be careful to ensure that a value is defined in the ubiloginConfString field, otherwise the passwords will be stored as plain text.

This is how the passwords are stored by default in Identity Server:

ubiloginConfString: {SSHA}L0IWAW4PDzEPcnED+TiliFiGqTa4vlMe2ahjyg==

The hashing algorithm is prepended to the password hash, such as {SSHA}.

Selecting a password hashing algorithm

When you start a new production project, one of the decisions to make is how the passwords will be stored. You can either choose a specific password encoding scheme or use the default. Ubisecure Identity Server uses {SSHA} by default. SSHA is the standard algorithm used by OpenLDAP, which gives an advantage in terms of interoperability.

However if you think you need a stronger algorithm, you can choose another from the list presented earlier.

Further technical details of algorithms

When storing passwords, parameters key length, salt length and number of iterations are not configurable in Identity Platform. Below you can find details on how algorithms PBKDF2 and PKCS5S2 are encoded.

PBKDF2

Parameters in PBKDF2 coding are specified in the page https://github.com/openldap/openldap/tree/OPENLDAP_REL_ENG_2_4_44/contrib/slapd-modules/passwd/pbkdf2

Coding is OpenLDAP compliant.

In short, the parameters are:

PKCS5S2

Parameters in PKCS5S2 coding are specified in the pages http://svn.apache.org/viewvc/directory/shared/trunk/ldap/model/src/main/java/org/apache/directory/api/ldap/model/password/ and https://github.com/apache/directory-ldap-api/blob/2.0.0/ldap/model/src/main/java/org/apache/directory/api/ldap/model/password/PasswordUtil.java

Coding is Apache Directory compliant.

In short, the parameters are: 

When verifying passwords, we either use default values or parameters from encoded representation.

Configuring password encoding in the authentication method

Password hashing algorithms are configured per authentication method in the system. You can have several authentication methods for different applications, and each can have a different password encoding. You will use SSO Management Console to configure password encoding in the authentication method.

1. From the Home menu, first go to Global Method Settings.
2. Select the method, which for most production projects will be "password.2".

3. Click on the tab SPI Password and you will see the password encoding. If the field appears empty, the current value is the default {SSHA}.
4. On Password Encoding field, write the short name for the selected hashing algorithm (e.g. {PBKDF2-SHA256}).
5. Click Update
6. Restart SSO and CustomerID services.

Importing password hashes from other systems

A very common task when deploying Ubisecure Identity Server in a new project is to import the hashed passwords that are used in the current applications. Many applications, especially from legacy systems, have not been conceived to interact with a CIAM solution, thus the hashing algorithm is not compatible with LDAP.

Password hashes can be imported to Ubisecure data repository using LDAP import via an LDIF file.

Plaintext passwords, which is very uncommon today, can be imported as it is.

Example: How the Ubisecure encodes a hashed PBKDF2-SHA256 password

Ubisecure directory encodes every PBKDF2-SHA256 password the following way:

{PBKDF2-SHA256}count$salt$hash

Where

• count is the iteration count
• salt is the salt value from import data
• hash is the actual hash from the import data

Import using CustomerID import

These are the steps to import hashed passwords using CustomerID import functionality.

1.  Take the server offline for a short maintenance period. You need to do it to prevent users from creating or changing passwords during this time.

2. Change password.2 password encoding to {PLAIN} in SSO management console. Press "Update" button
3. Restart both SSO and CustomerID services. It’s important to restart both.
4. Import the users with the hashed passwords. The simplest way is by calling Create User API call, including the hashed passwords as Body parameters.
   Example of an encoded password: {PBKDF2-SHA256}50000$9maWZglYIt2FYOO5FE3o4g==$4iZynLlUgvV2/IqukFefdLAnxVBc63Q69C/ox5KaI10=
   Additionally, make sure you include pwd.activated = True in the call.
5. Go to SSO Management Console and change Password Encoding for password.2 back to default. It's enough to keep the field empty. Press "Update" button
6. Restart both SSO and CustomerID services.
7. Finally, test login with your users and their respective plaintext passwords

Import using SSO import

You can also import users and their hashed passwords with SSO import tool.

First you have to create a LDIF file as the example below. 

# Set password.2 password for CID user 5932a00c-66fd-404a-ac01-6fdfd6c4ad14
#

version: 1


dn: CN=password.2,CN=5932a00c-66fd-404a-ac01-6fdfd6c4ad14,OU=Users,OU=eIDM Users,CN=Ubilogin,DC=login,DC=smartplan,DC=com
changetype: modify
replace: ubiloginConfString
ubiloginConfString: {PBKDF2-SHA256}50000$e7CGst2dXUaqSfTBJfDorg==$g2YEPA+vkmn+J73Gj7sSigyxtpdFQp3jUBod01i+yVs=
-

dn: CN=password.2,CN=5932a00c-66fd-404a-ac01-6fdfd6c4ad14,OU=Users,OU=eIDM Users,CN=Ubilogin,DC=login,DC=smartplan,DC=com
changetype: modify
replace: ubiloginPasswordLastSet
ubiloginPasswordLastSet: 0
-

dn: CN=password.2,CN=5932a00c-66fd-404a-ac01-6fdfd6c4ad14,OU=Users,OU=eIDM Users,CN=Ubilogin,DC=login,DC=smartplan,DC=com
changetype: modify
replace: ubiloginBadLogonCount
-

Once the LDIF file is created and contains all the users and their hashed passwords, execute the following command to import the file:

/ubilogin/ldap/openldap/import.sh importpasswordhashes.ldif

\ubilogin\ldap\adam\import.cmd importpasswordhashes.ldif

Exporting password hashes to other systems

It's also possible to export hashed passwords from Ubisecure Identity Server data repository to another identity management system.

In this scenario, password hashes are only exportable using direct LDAP export and CustomerID export scripts. Curently it is not possible to manage credentials using SSO Management API.

The commands are explained below.

LDAP export

/ubilogin/ldap/openldap/export.sh exportpasswordhashes.ldif

\ubilogin\ldap\adam\export.cmd exportpasswordhashes.ldif

CustomerID export

The page Data export to external systems - CustomerID explains the steps in detail, which in short are:

/customerid/tools/export-users.sh > export.txt

\customerid\tools\export-users.cmd > export.txt