abas Software GmbH

Foreword

Keycloak is an open source project from Redhat that can be used as an Identity Provider by any application. Integrated into the project eco system it can serve the purpose of User Authentication and Authorization using the OAuth2.0 and Open Connect 1.0 standards.

abas ERP integrates with this solution well to serve all your User Authentication and Authorization needs.

General Pre-requisites

abas ERP User’s Password Record Changes

User password record is configured for SSO (More details can be found here).

  • Checkbox "ssologin" is selected for users

  • Field "ssoLoginName" is the Email-Address of the users as imported in Keycloak. The value of this field is case-sensitive and should be exactly equal to the email address defined in AD (when AD and SSO is being used.)

abas GUI changes

  1. abas GUI must be configured to use SSO as defined here

    • In section [general], insert the below line

useSSO=true
  • In section for the client insert the following line. For multiple clients, the line must appear in each client section.

authBaseUrl=http://<Keycloak-Server>:<Keycloak-Port>/auth/realms/<Keycloak-Realm>

Where <Keycloak-Server>, <Keycloak-Port> und <Keycloak-Realm> correspond to what you defined in the abasfile.yml.

AD/LDAP Automatic User Import and Single Sign On

The current version of the abas-installer is capable of automatic importing user from Active Directory (AD) or LDAP.

If you are using Active Directory (AD) and have a Windows Domain in your company, you can activate Single Sign On for your users. Some preparation has to be done for this before the installation can be started. The next sections will help guide you through this set up.

Pre-requisites

  • At least the following of versions of software components are available to you

    • abas GUI version 3 - actual version

    • abas ERP - version 2019r4n06 or higher

Service Principle Generation

Create a new user in Active Directory with following details:

Name: <ActiveDirectory-Username> e.g. "keycloak-abasserver"
Loginname: HTTP/<hostname-keycloak-server>.<ad-domain-Lowercase>
Account → Account Option: Check the option "This account supports Kerberos-AES-256-Bit-Encryption"

"keytab" file generation for the Service Principle

Basically we are going to use a "Kerberos Keytab" file to integrate a non-Windows system (the Keycloak Server) with a Windows domain. Keycloak is able to verify the Windows Credentials using this keytab file against the Windows Domain Controller. A Domain Administrator can generate this file for you on the Domain Controller machine by executing the following interactive command on the Windows Domain Controller machine:.

ktpass -out <name>.keytab -mapUser <ActiveDirectory-Username>@<ad-domain-Lowercase> +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ HTTP/<hostname-keycloak-server>.<ad-domain-Lowercase>@<ad-domain-Uppercase>

where:

<name> is any string. For e.g it can be the Hostname of the server where Keycloak is installed or a string
that represents the usuage of the keytab file.
Example: keycloak-abasserver
<ad-domain-Lowercase> is the name of the Active Directory domain in lower case
Example: mydomain.com
<ActiveDirectory-Username> the username, that you created in the previous step on Active Directory
Keycloak: keycloak-abasserver
<hostname-keycloak-Server> is the hostname of the server where keycloak is installed.
Example: abasserver
<ad-domain-Uppercase> is the name of the Active Directory domain in upper case
Example: MYDOMAIN.COM

Example command:

ktpass -out keycloak-abasserver.keytab -mapUser keycloak-abasserver@mydomain.com +rndPass -mapOp set +DumpSalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -princ HTTP/abasserver.mydomain.com@MYDOMAIN.COM
You need to base64 encode the keytab file and put the result in the abasfile.yml as shown in next step

Once you have the keytab file, you can base64 encode it and use the outputted string as value for the "keytab" parameter the keycloak module in your abasfile.yml

bash@linux> base64 -w 0 keycloak-abasserver.keytab
BQIAAhasjdhasjHJHJHfjkabsbKJHJVBNMXBJHCSKHjkahjsbfbnvjdksluwueirz7uahsdjbh8a7c73iu4hrudcss<lwrjkfkndsfnvsdkvcksdlfcvkIKdf2mLgg==

Creating a "krb5.conf" file

You need to create a "krb5.conf" file that will be placed for you in the keycloak server by the abas-installer. The contents of this file can be specified as a multiline yaml string on the "krb5-conf" parameter in keycloak module. Please use the yaml scalar literal block syntax (i.e the pipe symbol to preserve newlines )for the multiline string. Do not add block chomping or indentation indicators as these are not supported in the abasfile.yml.

You can copy the lines below to abasfile.yml in keycloak module and adapt to your setup. If you need special values for your setup, you can reference the kerberos guide here.

      krb5_conf: |
        # To opt out of the system crypto-policies configuration of krb5, remove the
        # symlink at /etc/krb5.conf.d/crypto-policies which will not be recreated.
        includedir /etc/krb5.conf.d/

        [logging]
            default = FILE:/var/log/krb5libs.log

        [libdefaults]
            dns_lookup_kdc = true
            dns_lookup_realm = false
            ticket_lifetime = 24h
            renew_lifetime = 7d
            forwardable = true
            rdns = false
            pkinit_anchors = FILE:/etc/pki/tls/certs/ca-bundle.crt
            spake_preauth_groups = edwards25519
            default_realm = MYDOMAIN.COM   (1)
            default_ccache_name = /tmp/krb5cc_%{uid}

        [realms]
            MYDOMAIN.COM = {  (1)
                kdc = my-domain-controller.mydomain.com   (3)
            }

        [domain_realm]
            .mydomain.com = MYDOMAIN.COM   (2) (1)
            mydomain.com = MYDOMAIN.COM    (2) (1)
1 "MYDOMAIN.COM" is your domain name in uppercase
2 "mydomain.com" is your domain name in lowercase
3 "my-domain-controller.mydomain.com" is your domain controller name.

Automatic AD/LDAP setup with abas-installer

The newer version of keycloak module in abas-installer is capable of setting up User Federation for Active Directory / LDAP automatically. Please read the module documentation about the "ldap_config" parameters. You need to use the ldap parameters to configure SSO. The ldap-config section can look like below for ldap and kerberos setup.

abasfile.yml - ldap_config parameter snippet from abas-keycloak module
      ldap_config:
        connectionUrl: ldap://ad-serer.mydomain.com (1)
        ldap_bind_credentials: ldap_bind_credentials  (1)
        usersDn: OU=users,OU=abas AG,DC=mydomain,DC=com (1)
        vendor: ad (2)(3)
        usernameLDAPAttribute: sAMAccountName (2)
        rdnLDAPAttribute: cn (2)
        uuidLDAPAttribute: objectGUID (2)
        userObjectClasses: person, organizationalPerson, user (2)
        customUserSearchFilter: (&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=ATeam,ou=users,dc=mydomain,dc=com)) (5)
        extra_ldap_config_args: -s 'config.debug=["true"]' (5)
        kerberos_config: (5)
          kerberos_realm: MYDOMAIN.COM (4)
          server_principal: HTTP/keycloak-abasserver.mydomain.com@MYDOMAIN.COM (4)
          keytab: BQIAAhasjdhasjHJHJHfjkabsbKJHJVBNMXBJHCSKHjkahjsbfbnvjdksluwueirz7uahsdjbh8a7c73iu4hrudcss<lwrjkfkndsfnvsdkvcksdlfcvkIKdf2mLgg==  (4)
          krb5_conf: |    (4)
            # To opt out of the system crypto-policies configuration of krb5, remove the
            # symlink at /etc/krb5.conf.d/crypto-policies which will not be recreated.
            includedir /etc/krb5.conf.d/

            [logging]
                default = FILE:/var/log/krb5libs.log

            [libdefaults]
                dns_lookup_kdc = true
                dns_lookup_realm = false
                ticket_lifetime = 24h
                renew_lifetime = 7d
                forwardable = true
                rdns = false
                pkinit_anchors = FILE:/etc/pki/tls/certs/ca-bundle.crt
                spake_preauth_groups = edwards25519
                default_realm = MYDOMAIN.COM
                default_ccache_name = /tmp/krb5cc_%{uid}

            [realms]
                MYDOMAIN.COM = {
                    kdc = my-domain-controller.mydomain.com
                }

            [domain_realm]
                .mydomain.com = MYDOMAIN.COM
                mydomain.com = MYDOMAIN.COM
1 AD/LDAP credentials in credential.yml
2 This parameter can be left out. The value specified here is the default value. Only change if you want some other value.
3 ad or ldap values possible
4 Required ( if parent element is optional, it means only required if parent element present )
5 Optional
credential.yml showing escape character usuage
ldap_bind_credentials:
  scope: module
  username: MYDOMAIN\\USERNAME  (1)
  password: your-password-here
1 Note the use of double backspace to escape the single "\" in the username string.
You can leave out the "kerberos_config" parameters if you just want to configure ldap. But if you provide it all child elements are required then.

Post Installation User Creation

If your company does not use an LDAP server for user management, then you will have to create the users manually in Keycloak in the correct realm. The only user that exists after a fresh installation is the "admin" user in "master" realm.

Follow the guide here from keycloak to create other users. Take care to create them in the correct realm.

Take care to fill in the following fields when creating the user, these cannot be left empty, otherwise login with keycloak will not work:

  • Username

  • First Name

  • Last Name

  • email

While running "jwt_auth_userinfo" module with "user_sync_mode=full", you do not have to create the users in abas ERP beforehand. They will be automatically created using the template module defined in the "jwt_auth_userinfo" module on first usage. Defining new users in Keycloak is enough in this case.

By alternative "user_sync_mode=update_only" in "jwt_auth_userinfo", the email must match the ssologinname in abas ERP for existing users. "jwt_auth_userinfo" does not create any users in abas ERP and expects them to exist already.

AD/LDAP Manual User Import

Alternative to manually creating users you can import them from your LDAP or Active Directory server.

The newer "abas installer keycloak module" version automates the complete manual step of setting up User Federation. But if you wish to do this manually, you can follow the guide below for importing users from your LDAP / AD server. The parameters in abasfile correspond directly to the fields in the setup form.

Setup LDAP over SSL

If you need LDAP over SSL then follow the guide here:

Adding "admin" Group to users for Dashboards

There is a simple group setup that is needed for some features. This has to be done manually. The following guide takes you through these steps.

Browser Setup for Single Sign On under Windows

If you have setup Single Sign On with SPNEGO and Kerberos in your Windows Domain environment, then you can also tell your browsers to automatically sign you in using the SPNEGO protocol. But these settings have to be done manually on each user browser and differ from browser to browser. The most popular browser setup are listed below in short. The rest can be configured by searching for the relevant documentation from the browser vendor.

Firefox

  • Open Firefox.

  • Type about:config in the address field.

  • In filter/search, type negotiate.

  • Set the value of the parameter "network.negotiate-auth.trusted-uris" to the url of your keycloak server. Generally speaking this parameter has to replaced with the server address if Kerberos delegation is required. For e.g. http(s)://<your-abas-server-hostname>:<port>/auth

  • Additionally, if for some reason, you did not use the fqdn for your keycloak server (which is highly encouraged since you will get a lot of other problems otherwise), you might need to set the parameter "network.negotiate-auth.allow-non-fqdn" to the value of "true".

Firefox SPNEGO Kerberos Setup
Figure 1: Firefox SPNEGO Kerberos Setup

Chrome/Microsoft Edge/Internet Explorer

If your abas GUI is already working with SSO, there might be no steps needed for these browsers. Since abas GUI also shares the setting that are needed for these browsers. Otherwise just for info, Chrome and hence by design Microsoft Edge use the Intranet Zone settings in "Internet Option" to do SSO. How to set this up is described below. Under certain circumstances, your Windows Administrator already defines these settings for you and you cannot change them.

  • In Windows search box search for the term "Internet Options".

  • Click to open it and switch to tab "Security".

  • In Local intranet section make sure your server is trusted by i.e. adding it the list of trusted sites. If your admin controls this list, then perhaps selecting the option Automatically detect Intranet might help.

Backing up and Restoring your Keycloak Installation

Backup

There is some downtime associated with it while the backup runs. Backing up your keycloak installation is very easy. You just need to run the following script as sudo or the installation owner. The script can be run from any folder and must not necessarily be run from the installation’s bin folder.

sudo <install-dir>/bin/backup.sh

This will stops the keycloak containers (if running), backup everything under the installation folder (which also includes the database) and then restarts the containers(if previously running).

If you see the string "POSSIBLY-INCONSISTENT" in the backup name. It means that stopping the keycloak container failed for some reason and there is no guarantee that the backup that was created is consistent. Resolve the problem and re-take the backup in this case.
Every time your run "abas-installer update-modules -i keycloak" command, an automatic backup of your existing installation is done. This is in case something goes wrong during the update. You can then restore the back up manually if you cannot continue to update for some reason.

Restore

To restore the back up to the exact same location, you can use something like below:

sudo mv <install-dir> <install-dir>-bk
tar -xzvf <install-dir>-bk/backups/backup-<Year-month-day-HourMinuteSeconds>.tar.gz --directory /

Further Documentation

You can further configure your Keycloak server to use its full functionality. For help on other settings and options available to you from Keycloak, you can refer to the official guides which can be found here:

Troubleshooting