User IAM Configuration

Fabric allows you to configure web access and console access according to required authentication methods.

The configuration resides in the Fabric main configuration file - config.ini. For more information about this file see here.

First, look for the config parameters in the locations as described below:

• The web access is based on the WEB_AUTHENTICATION_PROTOCOL property which gets one of 2 values:

  • "SAML", indicate to Fabric to use SAML as IDP. In this case the saml section properties shall be set properly, as described later in this article.
  • SERVER_AUTHENTICATOR", indicate to Fabric to use the authenticators which are defined at server_authenticator section, as described later in this article. This is the default option and when it is in use you can leave WEB_AUTHENTICATION_PROTOCOL entry in comments.

• The console access is based on server_authenticator section definitions.

server_authenticator Configuration

server_authenticator property defines which authenticator to be used. In case SAML is not in use it is relevant also for the web access.

There are four authenticators which come as part of the Fabric platform, and are considered as reserved names: "fabric", "block_all", "ldap", "asldap", as following:

• cassandra, when using Fabric local Cassandra as Fabric System Database.
• fabric, when using Fabric as authenticator. For this no further settings are required.
• ldap, connect to LDAP server. For this option the LDAP server connection details are required and should be defined at section name: ldap_auth.
• adldap. connect to AD/LDAP server. For this option the AD/LDAP server connection details are required and shall be defined at section name: adldap_auth.
• block_all meaning that access is blocked. For this no no further settings are required.

The default authenticator is "cassandra" when server_authenticator is not set.

As will be explained later in this article, Fabric allows using also proprietary custom authenticators.

Sequence Authenticators

A sequence of authenticators can be specified using a comma separator: server_authenticator=<auth_1>[,<auth_2>, <auth_3>...]. For example: server_authenticator=ldap,fabric. The specified authenticators are evaluated by their order, where each is used as fallback to its predecessor.

Note that appropriate accompanying section must be added per authenticator. For example, if server_authenticator=ldap,fabric is configured then one additional section - "ldap_auth" - should be added.

If there is a need to use the same type, for example - use 2 LDAP servers, where one is a fallback to another, then you need to do the following:

1. Give a name to each of them, for example: "ldap1", "ldap2"
2. Make sure the additional section names match their names, for example: "ldap1_auth", "ldap2_auth"
3. Define their class-name as an additional property for the "_auth" section, similar to proprietary custom authenticator. This must be done because these names are not the reserved names. For example, in case of LDAP - class_name=com.k2view.fabric.authentication.providers.LdapAuthenticator.

SAML Configuration

Preparations & Prerequisites

The integration with a SAML IDP requires that both the identity provider (IDP) and the service provider (SP) i.e. Fabric, will provide information to each other which will then be uploaded and configured in both platforms.

• Get from the IDP - to be copied and downloaded from the IDP Admin user interfaces

  • IDP entity ID

  • IDP SERVICE URL, the IDP endpoint to which Fabric redirects the user.

  • Certificate file, the public key which is generated by the IDP. To import it into Fabric truststore run the following:

  keytool -importcert -alias <ALIAS-NAME> -file <full-path-to-downloaded-cert-file> -storetype JKS -keystore <full-path-to-truststore-file>

  The path to the trust-store file and related parameters can be found at the jvm.options file: At the TLS/SSL SETTINGS section look for "javax.net.ssl.trustStore" . All those values are set there for a hardened environment. An example to such path is: "$K2_HOME/.cassandra_ssl/cassandra.truststore"

  The specified alias name should also be used at the configuration for the IDP_CERT_ALIAS property. You can specify any alias name.

• Provide the IDP

  • SP entity ID

  • ACS URL - the endpoint at Fabric to which the SAML response should be sent

  • Certificate file - this is the public key which is generated by the Fabric private key. To generate it, run the following:

  keytool -export -alias <ALIAS-NAME> -storepass <password> -file <output-filename>.cer -keystore <full-path-to-keystore-file>

  The path to the key-store file and related parameters can be found at the jvm.options file: At the TLS/SSL SETTINGS section look for "javax.net.ssl.keyStore" . All those values are set there for a hardened environment. An example to such path is: "$K2_HOME/.cassandra_ssl/keystore.jks"

  The specified alias name should be used at the configuration for the SP_CERT_ALIAS property. You shall use the alias of the certificate which is already stored. Please verify it, using the keytool list command.

Keystore verification

You can verify the certification keys by using this command: keytool -list -storepass <passowrd> -keystore <path to the jks repository file>. JKS (Java KeyStore) is a repository of security certificates – either authorization certificates or public key certificates – as well as corresponding private keys.

While running this command after running the above two keytool's import and export commands, you will see the corresponding two entries, where you can see, for each entry, its alias, last modified date, its type, and its fingerprint. Below is an example of the command's output using Okta as IDP:

okta, Apr 28, 2021, trustedCertEntry, Certificate fingerprint (SHA1): 7F:CD:76:A6:B2:47:53:7E:BD:9E:20:44:B0:25:6B:78:A9:E3:25:40 k2view, Apr 18, 2021, PrivateKeyEntry, Certificate fingerprint (SHA1): 2C:9B:F3:8E:60:E6:BC:9F:82:84:A6:55:BE:62:2B:87:7D:42:BB:46

For more information about keystore handling please see here and here.

For more information and guides as to where and how this information should be set at IDPs - refer to Azure AD SAML Setup Guide and Okta SAML Setup Guide.

Editing the config.ini file

Following are the configuration actions that should be applied in the Fabric config.ini configuration file, using the information that was set and acquired at the preparation step.

At the [saml] section edit these properties:

• SP_ENTITYID, the identity of the Fabric, in URI format, which should be populated at the IDP
• SP_ASSERTION_CONSUMER_SERVICE_URL, the endpoint at Fabric to where the identity provider will redirect with its authentication response. Format: https://<HOSTNAME>:<PORT>/api/authenticate. The host name should be the Fabric load-balancer hostname (DNS name can be used too) . This property is also populated at the IDP side.
• IDP_ENTITYID, the entity ID, in URI format, as supplied by the IDP.
• IDP_SINGLE_SIGN_ON_SERVICE_URL, the IDP endpoint for SAML request.
• SECURE, flag indicating if certification and encryption is applied. Default is "true".
• SP_CERT_ALIAS, alias to the certification that is uploaded to the IDP,which is the public key to sign and encrypt the SAML response
• IDP_CERT_ALIAS, alias to the certification supplied by the IDP, which is the public key to to sign and encrypt the SAML request.
• GROUPS_KEY_MAPPING (optional), name of the groups list, as retrieved from IDP, as part of the SAML response. While Fabric expects that this value will be "groups" and this is its default, when required you can add this parameter and set its value.
• SP_SECURE (optional, default is true), indicates if expecting SAML response to be secured (encrypted). Set it to false when IDP does not want to upload the certificate file, provided by k2view. Having that IDP does not have the public key, it cannot encrypt the response.

In addition, WEB_AUTHENTICATION_PROTOCOL property's value shall set to "SAML".

Configurations for Windows OS

When Fabric is running on Windows OS, usually when working locally during the project implementation or testing, the following additional steps need to be done, in regards to the certification files.

1. Open the "fabric-server-start.bat" located in the Fabric server scripts directory - "\Server\fabric\scripts".
2. Update the following 4 properties
   • set javax_net_ssl_keyStore - the full path of the Fabric key store repository (jks file). This repository stores the the private key based upon which the public key is generated (this key is sent to the IDP).
   • set javax_net_ssl_keyStorePassword
   • set javax_net_ssl_trustStore - the full path of the trust store, where the public key, which retrieved from the IDP, is stored (for local machine you can use same jks file, which holds the keystore).
   • set javax_net_ssl_trustStorePassword
3. Restart Fabric.

LDAP & LDAPS Configuration

Preparations & Prerequisites

Admin Role Settings

When LDAP is used as an authenticator, an admin role is created automatically for Fabric bootstrap. The admin role's name should be configured in the admin_privileges configuration file (Use $K2_HOME/config.template/admin_privileges.template file as reference).

The role's name should be provided by the IT / LDAP owner (we assume he will create a dedicated role, to be used as K2View admin role).

LDAPS: Secured LDAP

When working with LDAPS (this is a secured LDAP), you must get a certificate file from the LDAP owner and import it to the Fabric truststore as shown:

Editing the config.ini file

The adldap_auth or ldap_auth sections must define the following:

• url - LDAP URL endpoint. in case of LDAPS (secured LDAP) it will start with "ldaps://" (note that it is in lowercase letters)
• security_level, set to "simple" (The default value. It can be used also for LDAPS).
• admin_dn, the LDAP admin user that has permissions to search and look for other users.
• admin_password, the admin user password.
• users_base_dn, the root base "dn" of the users.

The values should be provided by the LDAP owner.

The instructions for LDAP and LDAPS can be found here.

Proprietary Custom Authenticator

In order to use a custom authenticator do the following at the config.ini:

1. Add the server_authenticator authenticator list
2. Add an new accompany section, following this naming convention: <authenticator_name>_auth.
   • Under this section add a parameter named "class_name" where its value is the full class name of the implemented authenticator. Other parameters can be added too and will be passed to the authenticator when activated.

For more information about customer authenticator implementation see here.