This section provides information about Adabas RESTful server security topics such as SSL-encrypted connections and access restrictions to Adabas data.
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).
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-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.
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/
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
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>
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.
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
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.
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>
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.
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:
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.
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
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
Copy the generated keystore file keyfile.jks to the location defined in the configuration. The default location is the keys directory of the installation.