RESTful Security

This section provides information about Adabas RESTful server security topics such as SSL-encrypted connections and access restrictions to Adabas data.


Secure connection with SSL

The Adabas RESTful server can handle simultaneous HTTP and HTTPS connections to Adabas Manager or any other RESTful client. To prevent the RESTful server from providing an unsecured HTTP protocol link, the port number must be set to -1.

If the secure HTTPS protocol port is to be used, a keystore file (.JKS) containing the server certificate and key must be added to the RESTful server configuration. An example certificate to be used for testing purposes is delivered as part of the RESTful server release. This certificate can be found in <SAG installation>/AdabasRestAdministratrion/keys.

Important:
After testing, the example certificate must be exchanged with the corporate certificates of the customer environment!

If a self-signed certificate is needed, it can be generated by a script that is delivered with the Adabas RESTful server release (available with version 7.0.1 and above). For detailed instructions on how to generate the self-signed certificate, keys and keystore file, refer to the section Creating a Keystore file (.JKS).

Adabas User Authentication

The Adabas RESTful server supports two types of user authentication:

  • User and password file called Realm.

    The password is stored in an MD5 and SHA-hash in a text file.

  • Java JAAS support.

    The authentication can be done using the standard Java authentication module with Java Authentication and Authorization Service (JAAS).

Realm Text File Usage

Realm-based password authentication is handled by the configuration file AdabasRestAdministration/configuration/realm.properties. The file contains usernames and passwords. The password is stored as SHA or MD5 hashsum.

The service.sh script can add users to the file. The output of the command will appear on screen as shown below:

AdabasRestAdministration/bin> ./service.sh
add_userAdding user to password file ...
2022-09-20 08:40:20 Adabas REST client version v7.1.1.0
2022-09-20 08:40:20 Trace 'info' log send to /opt/softwareag/AdabasRestAdministration/logs/client.log
Enter username: sag2
Enter password: manage
User sag2 added to realm file
2022-09-20 08:40:42 client ended

If no realm.properties file is available, a new file can be generated by using the service.sh init command.

JAVA JAAS usage

With Adabas RESTful server version 7.0 and above, a number of additional platform specific JAAS modules are delivered to be used in authenticating users with the local system:

  • On Linux:

    The Adabas RESTful server delivers a Software AG internal JAAS module using the internal Software AG Security eXtensions (SSX). An example configuration is provided in the installation in the directory configuration/security.conf.

  • On Windows:

    The Adabas RESTful server is delivered with a JAAS module called Waffle. For more information see https://waffle.github.io/waffle/

Adabas User Authorization

The Adabas RESTful server provides Adabas users direct access to Adabas database administration tasks, records and data resources like Adabas Maps and Database IDs.

This user access to Adabas data resources can be controlled and limited using security definitions and Role-based Access Control (RBAC). RBAC definitions are configured on Adabas.

However, if RBAC definitions cannot be used for any reason, an alternative advanced security feature is provided on the RESTful server. This security feature allows you to configure and control access authorizations to Adabas data resources through the use of several configuration files in the <SAG>/AdabasRestAdministration/configuration directory. The main configuration file is config.xml.

The following user authorizations can be assigned using the configuration files:

  • Enable access for an Adabas Database ID

  • User-based access control

    • Provide Administration Permission

    • Provide Data Resources Permission

Enable Access for an Adabas Database ID

In the Adabas RESTful configuration (config.xml), direct access to Adabas databases using Database IDs is restricted with the DatabaseAccess tag. The DatabaseAccess attribute global defines whether all databases are accessible by default. If the attribute global is set to false, then any Adabas database ID used for direct access needs to be listed in the Database tag. In the example below, direct access is enabled only for the database with ID 123:

  <DatabaseAccess global="false">
      <Database dbid="123" />
  </DatabaseAccess>

User-based Access Control

Any user can be added to the Administrator role. In addition, the user can be restricted to access only specific Adabas Maps or Database IDs.

Within the LoginService tag of config.xml there are two tags that are used to differentiate Administrators from plain Users:

  <LoginService module="" webTokenExpires="24">
       <Administrators file="${CURDIR}/configuration/administrator.xml"></Administrators>
       <Users file="${CURDIR}/configuration/users.xml"></Users>
  </LoginService> 

The administrator.xml file that is specified in the Administrator tag must list all users with Administrator rights. Similarly, the users.xml file specified in the Users tag must list all users that should not have administrator rights. The users.xml also allows you to set permissions to specific data resources.

Provide Administration Permission

To provide Administrator permissions to a user, specify that user in the file <SAG>/AdabasRestAdministration/configuration/administrator.xml. In the example below, the users admin and sag have Administration permissions:

  <Users>
     <User name="admin" />
     <User name="sag" />
  </Users>

The rights to work with Adabas as Administrator covers all accesses and modifications that relate to administration and monitoring of the database

Provide Data Resources Permission

To restrict user access to specific Adabas data resources, you can define permissions with the Users tag in the file <SAG>/AdabasRestAdministration/configuration/users.xml. The tag allows users’ read and write permissions to be set for following Adabas record-based resources:

  • Adabas Map

  • Database ID

An example is shown below:

  <Users>
      <Default read="*" write="" />
      <User name="sag" read="*,#*" write="*" />
      <User name="sag2" read="Employees,Vehicles" write="Employees" />
  </Users>

In this example:

  • All users not listed under Users can read all Adabas Maps (*) and have no write access (“”) to any Adabas Maps.

  • The user sag has read permission to all Adabas Maps (*) and all database IDs (#*). Note that all database ID definitions need to have the prefix #. The user sag also has write permissions to all Adabas Maps (*).

  • The user sag2 only has read permission to the Adabas Maps named Employees and Vehicles. sag2 only has write permission to the Adabas Map Employees.

If RBAC or LDAP-based authentication is used, you can disable all user restrictions by setting the Default tag to prove full access for all users.

Provide Database Modification Permission

To restrict access for any modification made on the database, set the NoModification configuration parameter in config.xml. This parameter enables or restricts access to create and delete any database.

The following example enables the permission to create and delete any database:

  <Module>
    <Admin NoModification="false"></Admin>
  </Module>

JSON Web Token

Adabas RESTful server supports the use of signed JSON Web Tokens (JWT). After logging in using the /login web page, a JWT token is returned. The JWT token is valid for a limited time range and may be provided alternatively as a credential.

The token issuer and time limit can be configured in the configuration file <SAG>/AdabasRestAdministration/configuration/config.xml. In the example below, the token is configured to expire after 120 minutes:

  <Server>
    <JsonWebToken issuer="https://softwareag.com" expire="120" />
  </Server>

The JSON Web Token can be sent in an HTTP call as Authorization: Bearer <jwt token> to the Adabas RESTful server.

Creating a Keystore File (.JKS)

Follow the steps below to create a self-signed certificate for SSL and JWT, or to create keys, or to generate a keystore file for the certificate and keys. These scripts are only available from version 7.0.1 and above:

  1. Navigate to the directory <SAG installation>/AdabasRestAdministratrion/keys/scripts. This directory contains the sample config file (csr_config.cnf) and the script (generate_jks.sh) used to generate the self-signed certificate, keys and keystore file.

  2. The config file csr_config.cnf is shown below. Adapt this file for the domain and infrastructure in your destination environment. For example, example.com must be replaced with your actual DNS names.

      [ req ]
      default_bits = 2048
      default_keyfile = test_privatekey.pem
      distinguished_name = req_distinguished_name
      encrypt_key = no
      prompt = no
      string_mask = nombstr
      req_extensions = v3_req
    
      [ v3_req ]
      basicConstraints = CA:FALSE
      keyUsage = digitalSignature, keyEncipherment, dataEncipherment
      extendedKeyUsage = serverAuth, clientAuth
      subjectAltName = DNS:test.example.com, DNS:*.test.example.com
    
      [ req_distinguished_name ]
      countryName = DE
      stateOrProvinceName = Hessen
      localityName = Locale Test
      0.organizationName = Test Certificate
      organizationalUnitName = Evaluation
      commonName = test.example.com
    
  3. Create the keyfile.jks keystore file by running the command:

    > generate_jks.sh

    The contents of the script generate_jks.sh are shown below and they can be adapted to suit your needs:

      # Generate self signed certificate and keys dependent on the csr_config.conf input file
      openssl req -new -x509 -nodes -days 365 -sha256 -newkey rsa:4096 -keyout key.pem -out certificate.pem -config csr_config.cnf
      openssl x509 -text -noout -in certificate.pem
      openssl pkcs12 -password pass:test123 -inkey key.pem -in certificate.pem -export -out certificate.p12
      openssl pkcs12 -password pass:test123 -in certificate.p12 -noout -info
    
      # Generate keystore file based on the p12 certificate
      keytool -importkeystore -keypass test123 -srcstorepass test123 -srckeystore certificate.p12 -srcstoretype jks -destkeystore keystore.jks -deststoretype pkcs12 -deststorepass test123
    
  4. Copy the generated keystore file keyfile.jks to the location defined in the configuration. The default location is the keys directory of the installation.