RESTful Security

#### Search Results

Search

# 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

- Adabas User Authentication

- Adabas User Authorization

- JSON Web Token

- Creating a Keystore File (.JKS)

## 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 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 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.

## 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

- User-based Access Control

### 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

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.

#### 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.

Adabas RESTful server does not return a JWT token if the signing key files are not specified in the configuration file, or if the signing key files do not exist. Currently, any RSA public-private key pair can be used for JWT signing. If you are using OpenSSL, the key pair can be generated by executing the following command:

    openssl genrsa -out apiKey.prv 2048
    openssl rsa -in apiKey.prv -pubout -outform PEM -out apiKey.pem

You must specify the key pair files in the configuration file:

    <Server>
        <JsonWebToken issuer="https://softwareag.com" expire="120" encrypt="false">
            <PublicKey>${SAG}/AdabasRestAdministration/keys/apiKey.pem</PublicKey>
            <PrivateKey>${SAG}/AdabasRestAdministration/keys/apiKey.prv</PrivateKey>
        </JsonWebToken>
    </Server>

## Creating a Keystore File (.JKS)

Follow the steps below to create a self-signed certificate for SSL, 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.

### On this page

- Secure connection with SSL
- Adabas User Authentication
- Adabas User Authorization
- JSON Web Token
- Creating a Keystore File (.JKS)