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 the following type of user authentication:
User and password file called Realm.
The password is stored in an MD5 and SHA-hash in a text file.
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.
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.
The service.sh (for Linux platform) or service.bat (for Windows platform) script should be used to add Administration permissions. The script is located in <install-dir>/AdabasRestAdministration/bin
service.bat add_admin admin_name
where admin_name represents the user to be added as an
administrator role.
The list of Аdministrators with permissions are located in the file <install-dir>/AdabasRestAdministration/configuration/administration.xml.
The file is auto-generated, containing usernames and generated checksum. It should not be edited manually.
In the example below, the users admin and
sag have Administration permissions:
<Users>
<User name="admin" checksum=<generated-checksum> />
<User name="sag" checksum=<generated-checksum> />
</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.