Chapter 5. Securing Fabric Containers

Abstract

By default, fabric containers uses text-based username/password authentication. Setting up a more robust access control system involves creating and deploying a new JAAS realm to the containers in the fabric.
The default fabric authentication mechanism uses a text-based authentication cache that is stored on the fabric's registry. This authentication mechanism is used to control who can access fabric containers, who can issue commands to remote containers, who can update fabric profiles, and who can retrieve the details on the container's in the fabric. The management console also uses the fabric's authentication scheme.
The authentication system uses the JAAS framework. The fabric uses the karaf JAAS realm. This realm is defined in the fabric-jaas feature. It is deployed to all containers in the fabric as part of the default profile.
Important
The default authentication system is not recommended for production use.
You can configure the fabric to use a different authentication mechanism by overriding the karaf JAAS realm to use a proper login module. The fabric containers include an LDAP module that is preloaded and simply needs to be activated. Doing so requires that the new JAAS realm be defined in OSGi blueprint files and deployed to the container's in the fabric.

5.1. Using the Default Authentication System

Abstract

The default authentication system for the fabric can be managed using management console's Users. It can also be enhanced to store passwords using encryption.
By default fabric uses a simple text-based authentication system. This system allows you to define user accounts and assign passwords and roles to the users. Out of the box, the user credentials are stored in the fabric registry unencrypted.
You can mange the users in the default realm using the Users tab. You can also strengthen the default system by configuring it to use encryption when storing user credentials.

5.1.1. Managing Users

Viewing user data

To view the users configured to access fabric select the Users item from the main menu. This will open the Users page.
The Users page lists all of the users along the left hand side of the page. If you select the user, the user's roles will be displayed along the right hand of the page and you the buttons to edit the user will become active.

Adding a user

To add a user:
  1. Click Users from the main menu.
    The Users page opens.
  2. Click Create User.
    The Create New User dialog opens.
  3. In the Username field, enter a unique name for the user.
    The user name must be at least five characters long.
  4. In the Password field, enter a password for the user.
    The password must be atleast six characters long.
  5. In the Repeat Password field, reenter the password for the user.
  6. Click Create.
    The dialog closes and the new user is added to the list.

Removing a user

To remove a user:
  1. Click Users from the main menu.
    The Users page opens.
  2. Select the user to be deleted from the list.
  3. Click Delete User.
    A confirmation dialog opens.
  4. Click Yes.
    The dialog closes and the user is removed from the list.

Changing a user's password

To change a user's password:
  1. Click Users from the main menu.
    The Users page opens.
  2. Select the user to update from the list.
  3. Click Change Password.
    The Change Password dialog opens.
  4. In the Password field, enter a password for the user.
    The password must be at least six characters long.
  5. In the Repeat Password field, reenter the password for the user.
  6. Click Change.
    The dialog closes and a message shows that the password was changed.

Adding a role to a user

Note
Roles are not enforced.
To add a role to a user:
  1. Click Users from the main menu.
    The Users page opens.
  2. Select the user to update from the list.
  3. Click Add Role.
    The Add New Role dialog opens.
  4. In the Role Name field, enter a role for the user.
  5. Click Add.
    The dialog closes and a message shows that the role was added.

Deleting a role from a user

Note
Roles are not enforced.
To delete a role from a user:
  1. Click Users from the main menu.
    The Users page opens.
  2. Select the user to update from the list.
    The user's roles are listed on the right side of the page.
  3. Click the X opposite the role to delete.
    A confirmation dialog opens.
  4. Click Yes.
    The dialog closes and the role is removed from the list.

5.1.2. Encrypting Stored Passwords

Overview

By default, the JAAS login modules store passwords as plain text. You can provide additional protection to passwords by storing them in an encrypted format. This can be done by adding the appropriate JAAS configuration to the profile defining the fabric's karaf realm. This can be done by adding the appropriate configuration properties to the io.fabric8.jaas PID and ensuring that they are applied to all of the containers in the fabric.
Note
Although message digest algorithms are not easy to crack, they are not invulnerable to attack (for example, see the Wikipedia article on cryptographic hash functions). Always use file permissions to protect files containing passwords, in addition to using password encryption.

Editing the default profile

The easiest way to update all of the containers in a fabric is to modify the default profile. It is applied to all containers in a fabric through inheritance.
Important
Before making changes to the default profile, you should create a new profile version. Editing the active default profile could make your fabric unstable.
To enable password encryption by editing the default profile:
  1. Select the management console's Profiles tab.
  2. Create a new version by clicking Create Version.
    The Create New Version dialog appears.
  3. Optionally enter a name for the new version in the Name
    If you leave the Name field blank, the management console will use the name of the parent version and append the next available version number, starting from 1, to the name. For example, if version brokers1 existed, the management console would create version brokers1.1.
  4. From the Parent Version list, select the version from which the new version will originate.
    By default Use most recently created version is selected.
  5. Click Create to create the version.
    The dialog will close and the new version will be listed in the Versions table.
  6. Select the new version from the Versions list.
  7. Select the default profile from the Profiles list.
    The Profiles page for the selected profile opens.
  8. Select the Config Files tab.
  9. Select io.fabric8.jaas from the list.
    A text editing window opens.
  10. Enter values for the properties described in Table 5.1, “JAAS Encryption Properties” following the example shown in Example 5.1, “Password Encryption Configuration”.

    Example 5.1. Password Encryption Configuration

    encryption.enabled = true
    encryption.name = jasypt
    encryption.algorithm = SHA-256
    encryption.encoding = base64
    encryption.iterations = 100000
    encryption.saltSizeBytes = 16
  11. Click Save.
  12. If you configure the encryption to use Jasypt, add the jasypt-encryption feature to the profile.
    1. Select the Repositories tab.
    2. In the Add repository field enter mvn:org.apache.karaf.assemblies.features/standard/2.3.0.fuse-71-044/xml/features.
    3. Click Add.
    4. Select the Features tab.
    5. From the Repository list select mvn:org.apache.karaf.assemblies.features/standard/2.3.0.fuse-71-044/xml/features.
    6. From the Features list select jasypt-encryption.
  13. Select the management console's Containers tab.
  14. Click Migrate Containers.
  15. Click Select All.
  16. Select the version to which you added encryption from the Target Version table.
  17. Click Apply.

Configuration properties

Table 5.1, “JAAS Encryption Properties” describes the properties used to enable password encryption.

Table 5.1. JAAS Encryption Properties

PropertyDescription
encryption.enabledSpecifies if password encryption is enabled.
encryption.nameSpecifies the name of the encryption service, which has been registered as an OSGi service. See the section called “Encryption services”.
encryption.prefixSpecifies the prefix for encrypted passwords.
encryption.suffixSpecifies the suffix for encrypted passwords.
encryption.algorithm
Specifies the name of the encryption algorithm—for example, MD5 or SHA-1. You can specify one of the following encryption algorithms:
  • MD2
  • MD5
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512
encryption.encodingSpecifies the encrypted passwords encoding: hexadecimal or base64.
encryption.providerName (Jasypt only)Name of the java.security.Provider instance that is to provide the digest algorithm.
encryption.providerClassName (Jasypt only)Specifies the class name of the security provider that is to provide the digest algorithm.
encryption.iterations (Jasypt only)Specifies the number of times to apply the hash function recursively.
encryption.saltSizeBytes (Jasypt only)Specifies the size of the salt used to compute the digest.
encryption.saltGeneratorClassName (Jasypt only)Specifies the class name of the salt generator.
role.policySpecifies the policy for identifying role principals. Can have the values, prefix or group.
role.discriminatorSpecifies the discriminator value to be used by the role policy.

Encryption services

An encryption service can be defined by inheriting from the org.apache.karaf.jaas.modules.EncryptionService interface and exporting an instance of the encryption service as an OSGi service. Two alternative implementations of the encryption service are provided:
  • Basic encryption service—installed in the standalone container by default and you can reference it by setting the encryption.name property to the value, basic. In the basic encryption service, the message digest algorithms are provided by the SUN security provider (the default security provider in the Oracle JDK).
  • Jasypt encryption—can be installed in the standalone container by installing the jasypt-encryption feature. To access the Jasypt encryption service, set the encryption.name property to the value, jasypt.
    For more information about Jasypt encryption, see the Jasypt documentation.