Adabas Authentication

Authentication provides a means of identifying a user, by having the user provide a valid user name and valid password before access is granted.

The Adabas server checks the credentials against security definitions in an external authentication system like LDAP, Active Directory, operating system, or internal repository. If the credentials match, the user is provided access to the database. If the credentials are at variance, authentication fails and database access is denied.

The audit trail logs both successful and failed attempts to access the database.

In the current version:

The security infrastructure is used to provide access to external security systems.
Supported credentials are: domain, User ID and password.
Authentication implies “access or no access” to the database.
Database utilities do not perform authentication checks.
The audit trail is written to the ADABAS logging file.

This document covers the following:

How does Authentication work?
Security Infrastructure
Initial Setup
Configuration
Enable Security Mode
Utilities Required for Adabas Authentication
Application Development

How does Authentication work?

Architecture

graphics/auth_arch.png

Authentication Process

Application provides credentials: user ID and password.
Adabas server requests validation of the credentials via the security infrastructure.
Security infrastructure validates the credentials against the security repository.

Security Infrastructure

The Adabas server uses the predefined login module SSXLoginModule from the security infrastructure to authenticate user credentials.

Authentication is done against LDAP, Active Directory, internal repository or operating system.

The SSXLoginModule is part of the security libraries delivered with the Software AG Installer. The installation of this component is mandatory for the usage of this feature.

Initial Setup

When Installing Adabas

The Infrastructure Security Libraries are required by the Adabas Server. They contain the necessary functionality to implement the Adabas Authentication feature.

The Infrastructure Security Libraries are installed with the Software AG Installer and are, by default, preselected in the GUI installation.

Start of instruction set Enable Authentication Security Facility

Use the ADAINI utility
- To define the Extended Operations database log.
- To enable the Extended Operations Analyser.
- To enable the Audit Trail feature.
  
  Note:
  This is database-specific and must be performed for each database.
- To configure the SSXLoginModule usage.
  - Authorization Type specific options
  - Logging / Diagnostics options
Use the SECURITY function of the ADADBM utility to enable the Authentication Security Facility.
Start the database.

Start of instruction set Enable Legacy Applications to use Authentication

The Adabas nucleus user exit 21 is intended to assist when modifying legacy applications to use the authentication feature. For further details, please refer to the section Modifying Legacy Applications to use Authentication.

Customize the sample Adabas Nucleus User Exit 21 to meet the site-specific requirements.
Build the site-specific nucleus user exit.
Modify the environment settings for the nucleus user exit.
Start the database with the USEREXITS parameter.

Configuration

This section describes how to configure the authentication and audit trail features.

Audit Trail
Authentication
Performance Considerations

Audit Trail

The Audit Trail is written to the database log file and thus requires that the Event Analyser (AEO analyser or simply the analyser) be enabled. The analyser is enabled via the NODE_PARAMETER in the ADABAS.INI configuration file and thus enables the analyser in all databases within the node.

The Audit Trail feature is database-specific and is configured via the DBnnn.INI configuration files. The audit trail filter receives security events and writes them to the database log file, where they can be analyzed later. It is possible to either log all access attempts or only security violations.

Configuration File	Section	Subtopic	Item
`ADABAS.INI`	`NODE_PARAMETER`	`ANALYSER`	`ACTION`
`ADABAS.INI`	`NODE_PARAMETER`	`LOGGING`	`ACTION` `LOG_FILE`
`DBnnn.INI`	`DB_PARAMETER`	`AUDIT_TRAIL`	`ACTION` `FILTER`

For further information on the configuration files and syntax, see the descriptions of ADABAS.INI and DBnnn.INI in the Extended Operation documentation.

Authentication

The authentication checking is database-specific and is configured via the SSXLoginModule Options. These options are to be entered in the DBnnn.INI.

Configuration File	Section	Subtopic	Item
`DBnnn.INI`	`DB_PARAMETER`	`SSX_CONFIGURATION`	SSX Configuration Options

For further information on the configuration files and syntax, see the descriptions of DBnnn.INI in the Extended Operation documentation.

The SSXLoginModule supports multiple authorization types (or methods), for example:

AuthType	Description
TEXT	Authentication is performed using the security definitions, which are located in an Software AG internal user repository.
LDAP	Authentication is performed using the security definitions in LDAP.
ADSI	Authentication is performed using the security definitions in an Active Directory.
OS	Authentication is performed using the security definitions from the operating system.

In the section SSXLoginModule Configuration Templates you can find examples and example templates for the different authorization types. These templates are not complete as some of the settings are customer-specific and must be modified were necessary.

Performance Considerations

The following configuration options have a detrimental influence on performance and should be used with care:

Feature Option Explanation

Audit Trail

Feature	Option	Explanation
Audit Trail	`LOG_FILE`	A large volume of entries being written to the database log file may be detrimental to performance, when multiple databases are competing for the same resource; e.g. accessing the same database log file.
Audit Trail	`FILTER`	A large number of user-sessions will result in a large number of security entries being written to the database log file. The size of the database log file increases rapidly, with the numbers of user-sessions. Default Value: `FILTER = ALL`. Recommended Value: `FILTER = REJECT`.
SSX Logging / Diagnostics	`nativeloglevel`	Multiple user sessions attempting to write diagnostic information concurrently to the Security Infrastructure log file. Default Value: `None`. Recommended Value: `0` or `None`.

LOG_FILE

A large volume of entries being written to the database log file may be detrimental to performance, when multiple databases are competing for the same resource; e.g. accessing the same database log file.

Audit Trail

FILTER

A large number of user-sessions will result in a large number of security entries being written to the database log file. The size of the database log file increases rapidly, with the numbers of user-sessions.

Default Value: FILTER = ALL.

Recommended Value: FILTER = REJECT.

SSX Logging / Diagnostics

nativeloglevel

Multiple user sessions attempting to write diagnostic information concurrently to the Security Infrastructure log file.

Default Value: None.

Recommended Value: 0 or None.

Enable Security Mode

The security mode is enabled via the SECURITY function of the ADADBM utility.

The following database Security modes are available:

Security mode ACTIVE activates the security functionality and only authenticated users get access to the database. The mode ACTIVE can neither be changed nor disabled.
Security mode WARN simulates the security functionality and, if defined, writes warnings to the database log file in case of a security violation, but does not reject access to the database. The mode WARN can only be changed to ACTIVE.

Important:
The Database Security mode can be either set to WARN or ACTIVE. Once enabled, the security mode cannot be disabled.

Tip:
It is recommended that you create a backup for the database for recovery purposes, prior to activating the security mode.

Utilities Required for Adabas Authentication

The utilities required to configure and administer the authentication security feature are:

ADADBM - Enable Security Mode
ADAREP - Query Database Security Mode
ADAINI - Configure Security Features

ADADBM - Enable Security Mode

Use the SECURITY function of the ADADBM utility to activate the authentication and auditing features.

Note:
The SECURITY function requires that the database that is to be secured is offline.

adadbm: dbid=nnn
%ADADBM-I-DBOFF, database nnn accessed offline
adadbm: security=active
%ADADBM-I-FUNC, function SECURITY executed

ADAREP - Query Database Security Mode

Use the SUMMARY function of the ADAREP utility to display the database security mode settings.

Note:
The security mode setting is only displayed, when the feature has been activated. It is not displayed, when the feature is not activated.

ADAINI - Configure Security Features

Use the ADAINI utility to set and modify the configuration of the security features. The following examples show how ADAINI can be used to configure the security features.

Example 1: Activate Extended Operations Logging

ADABAS.INI
> adaini   add topic=NODE_PARAMETER topic=LOGGING  item=LOG_FILE=path_and_name_adabas_log_file
> adaini   add topic=NODE_PARAMETER topic=LOGGING  item=ACTION=YES
> adaini   add topic=NODE_PARAMETER topic=ANALYSER item=ACTION=YES

Example 2: Activate Audit Trail

DBnnn.INI
> adaini dbid=nnn add topic=DB_PARAMETER topic=AUDIT_TRAIL item=FILTER=ALL
> adaini dbid=nnn add topic=DB_PARAMETER topic=AUDIT_TRAIL item=ACTION=YES

Example 3: Configure Authorization Type TEXT

DBnnn.INI
> adaini dbid=nnn add topic=DB_PARAMETER topic=SSX_CONFIGURATION item=authType=TEXT
> adaini dbid=nnn add topic=DB_PARAMETER topic=SSX_CONFIGURATION item=internalRepository=path_and_name_ssxuser_file

Example 4: Configure Security Infrastructure Logging

DBnnn.INI
> adaini dbid=nnn add topic=DB_PARAMETER topic=SSX_CONFIGURATION item=nativeLogFile=path_and_name_of_ssxlog_file
> adaini dbid=nnn add topic=DB_PARAMETER topic=SSX_CONFIGURATION item=nativeLogLevel=6

Example 5: Display Configuration Settings

ADABAS.INI
> adaini   show topic=NODE_PARAMETER

DBnnn.INI
> adaini dbid=nnn show topic=DB_PARAMETER

Application Development

This section covers the following:

Developing Applications to use Authentication
Modifying Legacy Applications to use Authentication
SSXLoginModule Configuration Templates

Developing Applications to use Authentication

The application is responsible for setting the user credentials prior to opening a database session.

The following Adabas Client functions are provided to manage client sessions and set credentials:

Steps	Function	Description
1	lnk_set_adabas_id()	Set the session identification.
2	lnk_set_uid_pw()	Set the authentication credentials for a specific database.

Details on the above Adabas client functions can be found in the section Calling Adabas with Authentication in the section Calling Adabas of the Command Reference documentation

Modifying Legacy Applications to use Authentication

Without modification, legacy applications will receive nucleus response 200 “Security Violation”, when accessing secured databases.

The Adabas nucleus user exit 21 can be used to set authentication credentials via the ADABAS Server API Functions. The routine is called when the processing of a session begins.

This routine should be used as briefly as possible. It is intended for use during the transition period, until all applications use and support the Adabas Security authentication feature.

For further details, see the Nucleus User Exit 21 in the section User Exits and Hyperexits.

SSXLoginModule Configuration Templates

The following configuration options must be set in the configuration file DBnnn.INI in the subtopic SSX_CONFIGURATION of the DB_PARAMETER section.

DBnnn.INI

[DB_PARAMETER]
  [SSX_CONFIGURATION]
    <option>=<value>
  [SSX_CONFIGURATION-END]
[DB_PARAMETER-END]

In SSXLoginModule Configuration Templates you can find additional configuration templates you can use with the different authorization types (OS, TEXT, LDAP and ADSI).