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
section properties shall be set properly, as described later in this article. 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
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:
ldap_auth
. adldap_auth
.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.
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:
class_name=com.k2view.fabric.authentication.providers.LdapAuthenticator
.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.
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.
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:
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.In addition, WEB_AUTHENTICATION_PROTOCOL
property's value shall set to "SAML".
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.
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).
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:
The adldap_auth
or ldap_auth
sections must define the following:
The values should be provided by the LDAP owner.
The instructions for LDAP and LDAPS can be found here.
In order to use a custom authenticator do the following at the config.ini:
server_authenticator
authenticator list<authenticator_name>_auth
. For more information about customer authenticator implementation see here.
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
section properties shall be set properly, as described later in this article. 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
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:
ldap_auth
. adldap_auth
.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.
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:
class_name=com.k2view.fabric.authentication.providers.LdapAuthenticator
.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.
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.
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:
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.In addition, WEB_AUTHENTICATION_PROTOCOL
property's value shall set to "SAML".
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.
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).
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:
The adldap_auth
or ldap_auth
sections must define the following:
The values should be provided by the LDAP owner.
The instructions for LDAP and LDAPS can be found here.
In order to use a custom authenticator do the following at the config.ini:
server_authenticator
authenticator list<authenticator_name>_auth
. For more information about customer authenticator implementation see here.