Important:
Before securing databases with Adabas Role-based Security,
please familiarize yourself with the concepts and implementation of this
feature. Once enabled, security cannot be disabled.
Adabas Role-based Security implements Role-Based Access Control (RBAC) and restricts access based on the roles assigned a user and the permissions that are assigned to the role.
With Adabas Role-based Security, you can control what end-users can do at both broad and granular levels. You can designate the roles assigned a user and align the roles and access privileges with your users’ tasks. This means a user can be assigned a minimum of privileges, only the privileges essential to perform a specific task.
This feature includes the functionality:
- Authentication
This provides a means of validating credentials against an authority.
- Authorization for Direct Call Interface
This provides a means of restricting the usage of Adabas commands, which access a file, by assigning users a role which represents selective access privileges.
- Authorization for Adabas Utilities
This provides a means of restricting the execution of Adabas utilities by assigning users a role which has the execute privilege.
- Audit Trail
This provides a means of tracking access attempts and security violations.
The utility ADARBA provides the functionality required to administer security definitions.
The RBAC reference model used by Adabas is based on the Core RBAC (RBAC0) of the ANSI Specification (ANSI INCITS 359-2004).
Core RBAC defines a minimum Role-Based Access Control system. This includes user-role assignment and permission-role assignment relations, considered fundamental in any RBAC system.
In the standard, the core RBAC model includes a set of sessions, where each session is a mapping between a user and an activated subset of roles that are assigned to the user. Sessions are currently not supported and are thus not part of the Adabas role-based security model.
The Adabas RBAC reference model enables the database or security administrator to implement the following:
The assignment of USERS to ROLES,
The assignment of ROLES to PERMISSIONS,
where a PERMISSION consists of a set of OPERATIONS which can be performed on OBJECTS.
A user (USER) is defined as a human being. Although the concept of a user can be extended to include applications, the definition is limited to a person here for simplicity reasons.
A role (ROLE) is a job function within the context of an organization, with some associated semantics regarding the authority and responsibility conferred on the user assigned to the role.
Permissions (PERMISSIONS) are an approval to perform an operation on one or more RBAC protected objects.
An operation (OPERATION) is an action or function, such as the execution of an Adabas utility, Adabas command, etc.
An object (OBJECT) is a resource that is subject to access control, such as an Adabas database, file, etc.
This section describes the location and content of the security definitions.
The security definitions are stored in the RBAC system file of a security-enabled database. The contents of the system file constitute the security repository.
The security repository stores granted privileges, the denial of specific operations is not supported. It is accessible when the database is online or offline.
The initial security definitions implement unrestricted access to all operations and can be adapted and extended as required.
The unrestricted access to operations is achieved via the PUBLIC user and PUBLIC role security definitions.
The PUBLIC user is a pre-defined security definition. It is a convenience definition that is used when the provided credentials cannot be validated. This user has the permissions that can be derived from the assigned roles.
The PUBLIC user may be modified as follows:
The PUBLIC user may be dropped;
The roles assigned to the PUBLIC user may be modified or removed as required. Additional roles may be assigned.
By default, the PUBLIC user is assigned the PUBLIC role.
The PUBLIC role is a predefined security definition. All users have the permissions which are assigned to the PUBLIC role.
The PUBLIC role may be modified as follows:
The PUBLIC role is a system definition and as such should not be dropped.
The permissions assigned to the PUBLIC role may be modified or removed as required. Additional permissions may be assigned.
By default, the PUBLIC role has “legacy privileges”; for example, the privilege to execute to all Adabas utilities.
Authentication provides a means of identifying a user, by having the user provide a valid user name and a valid password before access is granted.
The credentials are checked against an authentication authority, for example against an external authentication system such as LDAP, Active Directory, operating system, or an internal user repository. If the credentials match, the user is provided access to the database. If the credentials are at variance, authentication fails and access to the database is denied.
The results of the authentication check are protocolled in the audit trail log.
Please refer to the section Configuration of the Infrastructure Security Libraries for further information about the possible authentication authorities.
Adabas uses the Infrastructure Security Libraries to access the authentication authority for validation of credentials. These libraries enable the authentication of credentials against LDAP, Active Directory, and internal repository or the operating system.
The installation of the Infrastructure Security Libraries is mandatory for usage of this feature.
Please refer to the section on configuration for further details on how to configure the authentication feature.
The credentials used by Adabas are user identification and password. The user identification consists of the user account name. In the case of Windows, the user identification also contains the domain of the user.
Credentials can be provided by one of the following means:
The application provides the credentials;
The credentials are provided by the nucleus user exit 21.
The application should always provide the credentials to ensure that the application user can be identified. How applications credentials are supplied is described in the section Developing Applications of Application Development.
The nucleus user exit 21 can be used to transition existing applications to a secure database. Further information on this topic is provided in the section Modifying Legacy Applications.
The authentication authority that is to be used is defined in a database configuration file.
Currently, the supported credentials are the local system credentials, which have been authenticated by the operating system.
Unix: User ID
Windows: Domain and User ID
Important:
The Adabas utilities currently do not perform
authentication checks. The local system credentials are used to perform the
authorization check. This is subject to change in a future release.
By default, authentication is not enabled.
The configuration and usage of the authentication feature are described in Configuration > Authentication below.
Authorization provides the means of restricting operations which are to be performed on a resource or, in other words, the execution of
An Adabas command on a file, or
An Adabas utility on a database.
An access request can be issued by either the Adabas nucleus or an Adabas utility.
The Adabas nucleus issues an access request prior to processing an Adabas command.
An Adabas utility issues an access request prior to executing the requested utility.
The access request is validated by the authorization authority. It is validated against the security repository stored in the database. The credentials used to process the access request were validated previously by the authentication authority.
The results of the authorization check are protocolled in the audit trail log.
Authorization for Adabas Direct Call Interface allows you to secure specific database files against unauthorized access via Adabas commands.
This feature uses role-based security definitions to restrict and monitor the usage of the Adabas commands, which can be performed on a specific file in the database.
If a matching access privilege is found, the user is authorized to execute the requested operation, otherwise the request is rejected.
Attempts to execute a controlled operation, here an Adabas command, are documented in an audit trail. The configuration of the audit trail log is described in Configuration > Audit Trail below.
The following table is a list of controlled access operations on files:
| Operation | Description | Commands |
|---|---|---|
| READ |
Read data stored in file |
L1, L2, L3, L4, L5, L6, L9, S1, S2, S4, S8, S9 |
| INSERT |
Insert data into the file |
N1, N2 |
| UPDATE |
Update data that is stored in a file |
A1 |
| DELETE |
Delete data that is stored in a file |
E1 |
| ANY |
This is a convenience notation. It includes the READ, INSERT, UPDATE and DELETE operations. |
All of the commands above |
Note:
In the current version, the execution of Adabas commands, which
are not listed above, is not restricted. This will change in a future
release.
The operation names above are the external representation of the security definitions.
When using the LIST function of the ADARBA utility, the internal representation of the security definition is shown.
| Operation | Description | LIST Layout |
|---|---|---|
| READ |
Read data stored in a file |
ada.dml.read |
| INSERT |
Insert data into a file |
ada.dml.insert |
| UPDATE |
Update data that is stored in a file |
ada.dml.update |
| DELETE |
Delete data that is stored in a file |
ada.dml.delete |
Authorization for Adabas Utilities allows you to secure a specific database against unauthorized access via Adabas utilities.
This feature uses role-based security definitions to restrict and monitor the usage of the Adabas utilities, which can be performed on a specific database.
If a matching access privilege is found, the user is authorized to execute the requested operation, otherwise the request is rejected. The authorization of a request implies the privilege to execute the Adabas utility.
All attempts to execute an Adabas utility are documented in an audit trail.
The following table is a list of possible access operations on Adabas utilities; all values are case-sensitive:
| Operation Name | Utility | Description |
|---|---|---|
| ada.uti.bck | ADABCK | Backup and restore database or files |
| ada.uti.clp | ADACLP | Command log report |
| ada.uti.cmp | ADACMP | Compression of data |
| ada.uti.cvt | ADACVT | Convert a database from a previous version |
| ada.uti.dbm | ADADBM | Database modification |
| ada.uti.dcu | ADADCU | Decompression of data |
| ada.uti.dev | ADADEV | Disk space management |
| ada.uti.ela | ADAELA | Event anaylitics administration |
| ada.uti.elp | ADAELP | Event log report |
| ada.uti.err | ADAERR | Error file report |
| ada.uti.fdu | ADAFDU | File definition |
| ada.uti.fin | ADAFIN | File information report |
| ada.uti.inv | ADAINV | Creating, removing and verifying inverted lists |
| ada.uti.mon | ADAMON | Monitoring the database nucleus |
| ada.uti.mup | ADAMUP | Mass add and delete |
| ada.uti.nuc | ADANUC | Starting the database, defining nucleus parameters |
| ada.uti.opr | ADAOPR | Operator utility |
| ada.uti.ord | ADAORD | Reorder the database or export/import files |
| ada.uti.plp | ADAPLP | Protection log printout |
| ada.uti.pri | ADAPRI | Print Adabas blocks |
| ada.uti.rba | ADARBA | RBAC administration |
| ada.uti.rec | ADAREC | Recovery of database or files |
| ada.uti.rep | ADAREP | Database report |
| ada.uti.scr | ADASCR | Manage and enable security functionality |
| ada.uti.uld | ADAULD | File unloading |
| ada.uti.vfy | ADAVFY | Database consistency check |
Note:
The operation names listed above are subject to change.
By default, authorization is not enabled.
The configuration and usage of the authorization feature are described in Configuration > Authorization below.
An audit trail entry is written to the audit trail log file for each authentication and authorization attempt. The audit trail logs both successful and failed attempts to access the database.
The content of each audit trail entry provides the following information on the attempted access:
Timestamp of access attempt;
Information about the application or utility, which attempted access;
User and session identification of access attempt;
Information about the attempted operation;
Information about the object of the operation.
The following requirements apply to the audit trail log file:
The audit entries are appended to the log file;
The size of the log file should be monitored and the log file should be backed-up or moved as required.
The location and layout of the audit trail log file is described in the section Authorization for Adabas Direct Call Interface.
The audit trail log is database-specific and is located in the database directory. The file name is NUCADT.log.
The layout of the audit trail log file is CSV format. The values of the audit trail entry are separated by comma “,”.
The following table contains a description of the audit trail entries for authentication and authorization, the values provided in each audit trail entry are dependent on the type of entry.
| Column | Description | Value |
|---|---|---|
| Timestamp | Timestamp | |
| Security Mode | Security Mode |
A[ctive] W[arn] |
| Result | Processing result - access is allowed or not |
YES NO |
| DBID | Database ID | |
| DBName | Database name | |
| Session ID | Client information, as specified in the Adabas User Queue | |
| ET User | ET User | |
| Security User | User credential provided for authentication | |
| RBAC User | User credential used to determine access privileges | |
| RBAC Role | Role with which access privilege was given | |
| Operation | Adabas command category |
INSERT READ UPDATE DELETE |
| Command | Adabas command code | |
| File Number | Adabas file number | |
| File Name | Adabas file name | |
| Authority | Authentication or Authorization authority |
SSX RBAC |
| Response Code | Adabas response code | |
| Subcode | Adabas subcode | |
| SSX Response | SSX response | |
| SSX Message | SSX message |
In this release, the adaaudit.ini configuration file defines the layout and location of the audit trail.
Please refer to the section Location of Configuration and Logging Files for further information about the location, configuration and content of the audit trail for Authorization for Adabas Utilities.
Important:
The location and configuration of the audit trail log file
for Authorization for Adabas utilities is deprecated. It is subject to change
in a future release.
| Column | Description | Prefix | Values |
|---|---|---|---|
| Timestamp | Timestamp | yyyy-mm-ddThh:mm:ssZ | |
| Message Type | Message indicator | %AUTHORIZATION- |
I[nformation] E[rror] |
| Hostname | Host name of machine | HOST= | <hostname> |
| Opsys Version | Name and version of operating system | OS= | <operating_system> |
| Credentials | Name of user account | USER= | [<domain>/]<user> |
| Operation | Name of attempted operation | OPERATION= | <operation> |
| DBID | Database ID | DBID= | <number> |
| Result | Result of authorization | AUTHORIZED= |
YES NO |
The audit trail is automatically enabled when either authentication or authorization is enabled.
Please refer to the section Location of Configuration and Logging Files for further information on the configuration of the contents of the audit trail log file.
The configuration and usage of the authorization feature are described below.
This section describes the configuration of the Adabas Role-based Security feature.
An initial security configuration is created during installation.
Security (MODE ADABAS) is enabled in the security configuration files;
Authentication is not enabled;
Authorization is not enabled;
Audit Trail is not enabled.
The following settings in the security configuration file adaauth.ini are mandatory:
ACTION=YES
MODE=ADABAS
Please refer to the section Configuration of Adabas Role-Based Security for further information on the file location and content.
Note:
The security configuration files will be deprecated in a future
release.
Important:
Database security cannot be disabled once it has been
activated.
Use the SECURITY function of the ADADBM utility to enable the authentication. The security mode can either be set to WARN or ACTIVE.
The security mode ACTIVE implies that only authenticated users are allowed access to the database. Security violations, such as authentication errors, are protocolled as “Error” in the audit trail.
The security mode WARN is intended for transitioning applications to use a secure database. It implies that all users are allowed access to the database. Security violations, like authentication or authorization errors, are protocolled as “Warning” in the audit trail. In case of a security violation, access to the operation is not rejected.
Once enabled, the security mode can only be changed from mode WARN to ACTIVE.
When you introduce this feature, Software AG strongly recommends that you initially start with security mode WARN.
Please refer to the section Nucleus user exit 21 for detailed information on how to provide authentication credentials for legacy applications.
The following types of authentication authority are supported:
Authentication Type OS (Operating System)
Authentication Type TEXT (Internal User Repository)
Authentication Type LDAP
Authentication Type ADSI
These settings are described in the section Configuration of the Infrastructure Security Library, where you can find example templates for the different authentication types. These templates are not complete as some of the settings are customer-specific and must be modified where necessary.
These configuration settings are stored in the section [SSX_CONFIGURATION] of the DBnnn.INI file. Use the administration command ADAINI to set and modify these settings.
Use the RBAC_FILE function of the ADADBM utility to load the RBAC system file.
Use the ADARBA utility to manage customer-specific security definitions.
Please refer to the examples in section Getting Started for further information.
Note:
The RBAC System File is closely related to the database. It
has to be backed up and restored together with the complete database and cannot
be restored individually.
The audit trail log is written to the file NUCADT.log, which is located in the database directory.
The configuration settings are stored in the section [AUDIT_TRAIL] of the DBnnn.INI file. Use the administration command ADAINI to set and modify these settings.
The following AUDIT_TRAIL settings can be used to configure the audit trail:
Please refer to the section Configuration Files for further information on AUDIT_TRAIL settings .
The configuration settings for the audit trail log file are stored in the section [AUDIT] of the configuration file adaaudit.ini.
The following options are available:
The item FORMAT defines the layout of an audit log entry.
The item SEPARATOR defines the character to be used to separate values in CSV format.
The item LOG_FILE defines the location and file name of the audit log.
Please refer to the section Configuring Adabas Role-based Security for further information.
The utilities required to configure and administer the authorization feature are:
Use the SECURITY function to enable Adabas RBAC Security;
Use the RBAC_FILE function to create the RBAC system file.
Note:
These functions require that the database is offline.
Use the administration command ADAINI to set and modify the configuration of security features;
Configure the authentication authority;
Configure the audit trail;
Display the configuration settings.
Use the SUMMARY function to display the database system files and whether security is enabled;
The SECURITY setting is displayed if security is enabled;
The RBAC system file information is displayed if the RBAC system file is defined.
Use the CREATE, DROP, GRANT, REVOKE functions to create, modify and delete security definitions;
Use the LIST functions to display the security definitions.
Note:
These functions require that the database is online.
This feature could have a detrimental effect on the overall system performance for the following reasons:
Due to the effort required to authenticate the credentials;
Due to the large number of entries being written to the audit trail log file.
This feature could have a detrimental effect on the overall system performance for the following reasons:
Due to the effort required to authenticate the credentials;
Due to the effort required to determine the user’s access privileges;
Due to the large number of entries being written to the audit trail log file.
This feature only has minimal impact on the overall system performance.
Due to the high number of synchronized file I/Os, this feature could have a detrimental influence on the overall system performance.
The impact can be minimized by using the AUDIT_TRAIL parameter setting FILTER=REJECTED for authentication and authorization for Direct Call Interface requests.
The following configuration options have a detrimental influence on performance, and should be used with care:
| Feature | Option | Explanation |
|---|---|---|
| Audit Trail | Filter |
A large number of user sessions or Adabas commands will result in a large number of security entries being written to the audit trail log file. The size of the audit trail log file increases rapidly with the numbers of user sessions or Adabas commands. Default value: FILTER = ALL Recommended value: FILTER = REJECTED |
| 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 |
This section covers the following topics:
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:
| Step | 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 about the above Adabas client functions can be found in the section Calling Adabas with Authentication in the section Calling Adabas in the Command Reference.
It is recommended to use OPTIONS=OPEN_REQUIRED.
Without modification, legacy applications will receive the 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.
If a security violation occurs during authentication processing, Adabas issues a response code, backs out the user's current transaction, and closes the user session.
Response code 9, subcode SE
Response code 200, subcode 31
If a security violation occurs during authorization processing, Adabas issues a response code,
Response code 200, subcode 175
The error handling for security mode WARN is intended for transitioning to a secure database. The error handling is described below. It differs to that of mode ACTIVE.
The current transaction is not backed out;
The response code returned indicates “success” (response 0);
A “Warning” entry is entered in the audit trail log file.
The following Adabas nucleus response codes indicate that a security issue has occurred:
| Response Code | Explanation | Action |
|---|---|---|
| 9/SE |
The credentials have been modified since the start of the session. Hence the credentials are invalid, and the user session has been terminated. |
Ensure that the credentials are not set or modified during a user session. To proceed processing, set the credentials and open a new user session. |
| 200/31 |
The credentials could not be validated by the authentication authority. |
Ensure that the credentials have been provided and that they are valid. |
| Response Code | Explanation | Action |
|---|---|---|
| 200/175 |
The user identified by the provided credentials does not have the privileges to perform the requested operation. |
Ensure that the credentials have the required privileges. |
This section covers the following topics:
In order to execute the steps described in the following section, you will require a database.
The following prerequisites are mandatory:
The Infrastructure Security Libraries are installed.
The security feature is enabled.
Authentication has the following prerequisites:
The security mode is enabled.
The user credentials that are to be validated by the authentication authority.
Authorization has the following prerequisites:
The RBAC system file is loaded.
Security definitions will be required.
You, or an administrator, will require the necessary access privileges:
To modify the security configuration files.
To create and configure a database.
To start and stop a database.
Important:
When starting with the Adabas RBAC security feature, it is
recommended to create a database and to initially use the SECURITY mode WARN.
Once the Adabas role-based security feature has been enabled, it cannot be
disabled.
This section describes how to configure Adabas role-based security (ADARBA).
Edit the security configuration file adaauth.ini.
To enable Adabas role-based security, set the following in the section [AUTHZ]:
ACTION=YES
MODE=ADABAS
By default, the following settings do not require modification:
AUDIT_FILE - location of the Audit configuration file.
RBAC_FILE - this setting has been deprecated.
The modification of the Audit configuration file settings is described in the section Audit Trail.
The following steps describe how to enable authentication.
Ensure the database is offline.
Configure the authentication authority for the database.
Enable authentication by setting the SECURITY mode.
Start the database.
Note:
Authentication is not required and does not have to be
enabled for Authorization for Adabas Utilities.
The authentication examples below use the internal user repository as the authentication authority.
This example shows how to create a user, password credential in an internal user repository.
> ssxtxtpasswd -f SAGInternalUserRepository.txt -c -p mypsw myuid Hash: bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVkA== User entry for "myuid" successfully added
The contents of the file SAGInternalUserRepository.txt are shown below:
* * * SAG Internal User Repository * version:3.0 * user:myuid:$6a$bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVk
Please refer to the section Configuring the Infrastructure Security Libraries for further information about how to create and administer an internal user repository.
This example shows the configuration of authentication with a text file. This file contains authenticated credentials and passwords. Please refer to the section describing the Configuration for further information on the creation and administration of an authentication text file.
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=SAGInternalUserRepository.txt
Please refer the section Validating the Configuration for an example on how to display the SSX_CONFIGURATION settings.
This example shows how to enable the security mode, which enables authentication. When starting with the Adabas RBAC security feature, it is recommended to initially use the SECURITY mode WARN.
Use the SECURITY function of the ADADBM utility to activate the authentication feature.
> adadbm dbid=nnn security=warn %ADADBM-I-STARTED, 15-AUG-2018 11:13:39, Version 6.7.0.0 %ADADBM-I-DBOFF, database 224 accessed offline %ADADBM-I-FUNC, function SECURITY executed
The following steps describe how to enable authorization.
Ensure the database is offline.
Load the RBAC system file.
Start the database.
Use the RBAC_FILE function of the ADADBM utility to load the RBAC system file.
> adadbm dbid=nnn rbac_file=250 %ADADBM-I-STARTED, 15-AUG-2018 15:26:58, Version 6.7.0.0 %ADADBM-I-DBOFF, database 224 accessed offline %ADABCK-I-STARTED, 15-AUG-2018 15:26:58, Version 6.7.0.0 %ADABCK-I-DBOFF, database 224 accessed offline %ADABCK-I-BKREAL, new RABN allocations for file 7 Restore files dumped on 27-JUL-2018 09:00:19 Database 1, RBAC-FILE File 7 renumbered to file 250 File 250, RBAC-FILE , loaded on 27-JUL-2018 09:00:14 %ADABCK-I-IOCNT, 52 IOs on dataset DATA %ADABCK-I-IOCNT, 228 IOs on dataset ASSO %ADABCK-I-IOCNT, 228 IOs on dataset BCK001 %ADABCK-I-TERMINATED, 15-AUG-2018 15:27:19, elapsed time: 00:00:21 %ADADBM-I-ACLLOAD, RBAC-FILE loaded in file 250 %ADADBM-I-IOCNT, 4 IOs on dataset WORK %ADADBM-I-IOCNT, 13 IOs on dataset ASSO %ADADBM-I-TERMINATED, 15-AUG-2018 15:27:20, elapsed time: 00:00:22
Please refer the section Validating the Configuration for an example of how to display the RBAC system file information.
The audit trail log file for authentication and authorization of Adabas direct call interface is located in the database directory. The file name is NUCADT.LOG.
The following steps describe how to enable the audit trail for authentication and authorization for Adabas direct call interface.
Configure the audit trail for authentication and authorization for Adabas direct call interface.
Restart the database, so that the modifications are active.
The following example shows the configuration of the audit trail for authentication and authorization for Adabas direct call interface.
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
Please refer the section Validating the Configuration for an example of how to display the audit trail settings.
The following steps describe how to enable the audit trail for authorization for Adabas utilities.
Edit the security configuration file adaaudit.ini.
To enable the audit trail, set the following in the section [AUDIT]
FORMAT = <file layout>
SEPARATOR = <separator_character>
LOG_FILE = <log file name>
The modification of the audit trail configuration file settings is described in the section Configuration for Authorization for Adabas Utilities.
The following examples show how you can validate the configuration of authentication and authorization.
Use the SUMMARY function of the ADAREP utility to display the SECURITY mode setting and the RBAC system file information.
When enabled, the SECURITY mode will be displayed with a value of either WARN or ACTIVE. When not enabled, the SECURITY mode is not displayed.
When loaded, the file number of RBAC system file will be shown.
> adarep dbid=nnn summary
%ADAREP-I-STARTED, 15-AUG-2018 15:37:23, Version 6.7.0.0
Summary of Database nnn 15-AUG-2018 15:37:23
DATABASE NAME EXAMPLE-DB
DATABASE ID 224
MAXIMUM FILE NUMBER LOADED 255
SYSTEM FILES 255 (CHK), 251 (SEC), 254 (USR)
250 (RBAC)
ACTUAL FILES LOADED 8
CURRENT PLOG NUMBER 4
CURRENT CLOG NUMBER 0
SECURITY WARN
Container Device Extents in Blocks Number of Block Total Size
File Type from to Blocks Size (Megabytes)
-------------------------------------------------------------------------------
ASSO1 file 1 2,000 2,000 2,048 3.91
ASSO2 file 2,001 10,000 8,000 2,048 15.63
DATA1 file 1 2,000 2,000 4,096 7.81
DATA2 file 2,001 10,000 8,000 4,096 31.25
WORK1 file 1 2,000 2,000 4,096 7.81
-------------------------------------------------------------------------------
66.41
=====
%ADAREP-I-IOCNT, 17 IOs on dataset ASSO
%ADAREP-I-TERMINATED, 15-AUG-2018 15:37:23, elapsed time: 00:00:00
Use the SHOW function of the administration command ADAINI to display the authentication configuration.
Show the configuration of the authentication authority.
> adaini dbid=nnn show topic=DB_PARAMETER topic=SSX_CONFIGURATION authType=TEXT internalRepository=path_and_name_ssxuser_file
Use the SHOW function of the administration command ADAINI to display the audit trail configuration.
Show the audit trail configuration for authentication and authorization for Adabas direct call interface.
> adaini dbid=nnn show topic=DB_PARAMETER topic=AUDIT_TRAIL ACTION=YES FILTER=ALL
The security infrastructure is initialized during the start of the ADANUC utility. This infrastructure is used for authentication and indicates that the authentication feature is enabled and that the SSX_CONFIGURATION parameters have been processed.
> adanuc dbid=nnn %ADANUC-I-STARTED, 15-AUG-2018 16:21:59, Version 6.7.0.0 %ADANUC-I-SSXINI, SSX Security Infrastructure initialized %ADANUC-I-CREATED, dataset NUCTMP1, file D:\ ADADATADIR\dbnnn\NUCTMP1.nnn created %ADANUC-I-PLOGCRE, plog NUCPLG, file 'D:\ADADATADIR\dbnnn\NUCPLG.0001' created %ADANUC-I-DBSTART, Database nnn, session 5 started, 15-AUG-2018 16:22:02
The examples below show the initial values of the security definitions stored in the security repository. Start the database and display the security definitions.
> adarba dbid=nnn list,user
This shows the user PUBLIC.
> adarba dbid=nnn list,role
This shows the role PUBLIC.
> adarba dbid=nnn list,assignment,user
This shows the assignment PUBLIC,PUBLIC. That is the role PUBLIC has been assigned to the user PUBLIC.
The usage of authentication requires that the credentials be set by the application, or be provided by the Adabas nucleus user exit 21. Please refer the section Application Development for further information on the setting credentials.
The example below show how ADATST can be used to verify the authentication of credentials.
> adatst %ADATST-I-STARTED, 16-AUG-2018 12:11:22, Version 6.7.0.0 > adatst: ;-------- Database ID > adatst: dbid=<dbid> > adatst: ;-------- Credentials (without trailing whitespace) > adatst: sec_uid=<userid> > adatst: sec_pwd=<password> > adatst: ;-------- Session Open > adatst: cc=op > adatst: rb=. > adatst: go Command : OP Test-Nr : 1 Started %ADATST-I-NORMAL, normal successful completion Command : OP Test-Nr : 1 Completed > adatst: ;-------- Session Close > adatst: cc=cl > adatst: go Command : CL Test-Nr : 2 Started %ADATST-I-NORMAL, normal successful completion Command : CL Test-Nr : 2 Completed > adatst: quit %ADATST-I-TERMINATED, 16-AUG-2018 12:11:22, elapsed time: 00:00:00
A nucleus response code 200 with subcode 31 indicates a security violation; the authentication check in the external security system failed.
Possible causes of a security violation are:
The credentials are invalid.
The configuration of the authentication authority is invalid.
The authentication authority is not accessible.
A nucleus response code 9 with subcode SE indicates that the credentials have been modified; for example by altering the credentials during the open session.
The example below shows how ADATST can be used to verify that valid credentials are provided by nucleus user exit 21. The user exit is called to provide credentials if the calling application has not provided credentials.
> adatst %ADATST-I-STARTED, 16-AUG-2018 12:11:22, Version 6.7.0.0 > adatst: ;-------- Database ID > adatst: dbid=<dbid> > adatst: ;-------- Session Open > adatst: cc=op > adatst: rb=. > adatst: go Command : OP Test-Nr : 1 Started %ADATST-I-NORMAL, normal successful completion Command : OP Test-Nr : 1 Completed > adatst: ;-------- Session Close > adatst: cc=cl > adatst: go Command : CL Test-Nr : 2 Started %ADATST-I-NORMAL, normal successful completion Command : CL Test-Nr : 2 Completed > adatst: quit %ADATST-I-TERMINATED, 16-AUG-2018 12:11:22, elapsed time: 00:00:00
A nucleus response code 200 with subcode 31 indicates a security violation; the authentication check in the external security system failed.
Possible causes of a security violation are:
Nucleus user exit 21 is not enabled.
The provided credentials are invalid.
The configuration of the authentication authority is invalid.
The authentication authority is not accessible.
This section describes how to secure access to application data, for example allowing all users READ access to the EMPLOYEES file, and at the same time restricting the privilege to modify data.
In this example, you will create and modify the security definitions. In the end, only users assigned the HR_department role are able to modify data in the EMPLOYEES file, but all users are allowed to READ the file.
To achieve this, you need to:
Create a HR_department role;
Grant the role permission to modify the EMPLOYEES file;
Create an HR_userid user;
Grant the user the HR_department role;
Grant the PUBLIC role permission to READ the EMPLOYEES file.
The examples below show the security definitions required to restrict access to the EMPLOYEES file.
> adarba > adarba: dbid=nnn > adarba: create,role=HR_department > adarba: grant,operation=ANY,object=11,to,role=HR_department > adarba: create,user=HR_userid > adarba: grant,role=HR_department,to,user=HR_userid > adarba: grant,operation=READ,object=11,to,role=PUBLIC
The following security definitions are created or modified:
Created:
Role: HR_department
User: HR_userid
Permission to Operation and Object: ANY, File 11 (EMPLOYEES-NAT)
Modified:
Role: PUBLIC
Permission to Operation and Object: READ, File 11 (EMPLOYEES-NAT)
Note:
The role name and the user name are site-specific.
The user name used for authorization is the same as the one used for authentication.
The user name must be defined for both authorization and authentication.
The example below shows the security definitions which secure access to the EMPLOYEES file.
> adarba > adarba: dbid=nnn > adarba: ; ---------- USERS > adarba: list,user PUBLIC HR_userid > adarba: ; ---------- ROLES > adarba: list,role PUBLIC HR_department > adarba: ; ---------- USER-ROLE ASSIGNMENTS > adarba: list,assignment,user PUBLIC,PUBLIC HR_department,HR_userid > adarba: ; ---------- PERMISSIONS > adarba: list,assignment,permission ada.uti....,DBID.CURRENT,PUBLIC ada.uti....,DBID.CURRENT,PUBLIC ada.uti....,DBID.CURRENT,PUBLIC ada.dml.delete,FILE.00000011,HR_department ada.dml.insert,FILE.00000011,HR_department ada.dml.read,FILE.00000011,HR_department ada.dml.update,FILE.00000011,HR_department ada.dml.read,FILE.00000011,PUBLIC
This section describes how to secure access to an Adabas utility, for example the ADADBM utility.
In this example, you will create and modify the security definitions. By default, all users with the PUBLIC role have access to and can execute the ADADBM utility. In the end, only users assigned the database administrator role are able to execute the utility.
To achieve this, you need to:
Create a database administrator role;
Grant the role permission to execute the utility;
Create a user that is to be assigned the database administrator role;
Grant the user the database administrator role;
Revoke the permission to execute the utility from the role PUBLIC.
> adarba > adarba: dbid=nnn > adarba: create,role=database_administrator > adarba: grant,operation=ada.uti.dbm,to,role=database_administrator > adarba: create,user=dba_userid > adarba: grant,role=database_administrator,to,user=dba_userid > adarba: revoke,operation=ada.uti.dbm,from,role=PUBLIC
In this example, the following security definitions are created or modified:
Created:
Role: database_administrator
User credentials: dba_userid
Permission to operation: ada.uti.dbm
Modified:
Role: PUBLIC
Permission to operation: ada.uti.dbm
Note:
The role name and the user credentials are site-specific. The
user credentials used for authorization are local system credentials.
The example below shows the security definitions that secure access to the ADADBM utility.
> adarba > adarba: dbid=nnn > adarba: ; ---------- USERS > adarba: list,user PUBLIC dba_userid > adarba: ; ---------- ROLES > adarba: list,role PUBLIC database_administrator > adarba: ; ---------- USER-ROLE ASSIGNMENTS > adarba: list,assignment,user PUBLIC,PUBLIC database_administrator,dba_userid > adarba: ; ---------- PERMISSIONS > adarba: list,assignment,permission ada.uti....,DBID.CURRENT,PUBLIC ada.uti....,DBID.CURRENT,PUBLIC ada.uti....,DBID.CURRENT,PUBLIC ada.uti.dbm,DBID.CURRENT,database_administrator
The infrastructure security libraries are used to access the
authentication authority. The following sections contain configuration
templates for the SSX_CONFIGURATION parameters, organized by
type.
The security definitions for authentication type OS are managed by the local operating system.
[SSX_CONFIGURATION]
# This is a sample properties file for the case
# when authType is OS and the user database is
# the local operating system -
# On Unix Systems it is using PAM authentication
# On Windows a local LogonUser()
# Specifies the authentication type.
# Is Required: Yes
# Valid values: {"OS", "TEXT", "LDAP", "ADSI"}
# Default Value: None
authType=OS
# Specifies the explicit path of the privileged daemon process.
# Specify this parameter -
# if the sagssxauthd2 executable file is not in the current directory.
# Valid value is the valid path to the sagssxauthd2 module.
# Default Value: None
# Note: UNIX only.
##authDaemonPath
# Specify a default group name here to be returned
# with any of the group results that are returned by the repository manager.
# A valid value is any valid group name.
# Default Value: None
# Optional.
##defaultGroup
# If this parameter is specified, its value is used at authentication time
# when domain name is not specified by the user.
# If a domain name is specified, the value of this parameter is not used.
# A valid value is any valid domain name.
# Default Value: None
# Optional.
##defaultDomain
# Specifies how to access data.
# Valid values are:
# o true - Access is under the account of the running process.
# o false - Access is under the impersonated user ID of the logged on user.
# Default Value: FALSE
# Note: Windows only.
# Optional.
##noImpersonation
# Specifies the local machine name (on which the user is authenticated).
# The machine name is added before users and groups;
# for example,machine_name\user.
# Valid values are:
# o true - If set to TRUE (and there is no domain field), you are authenticated against the local machine only.
# o false - You are authenticated on the domain that you logged on.
# Default Value: FALSE
# Optional.
##unixAddMachineName
# Specifies the log level.
# Is Required: No
# Valid values:
# 0 - No logging
# Min: 1
# Max: 6
# Default Value: None
##nativeLogLevel=0
# Specifies the log file.
# Is Required: No
# Valid values:
# fully qualified file name
# Default Value: None
##nativeLogFile=SAGSSXCLIENTA_SSX.LOG
[SSX_CONFIGURATION-END]
The security definitions for authentication type TEXT are stored in a text file. The definitions can either be database-specific or be shared by multiple databases.
[SSX_CONFIGURATION]
# This is a sample properties file for the case
# when authType is TEXT and the user database is
# an SAG Internal User Repository
# created by the ssxtxtpasswd utility
# Specifies the authentication type.
# Is Required: Yes
# Valid values: {"OS", "TEXT", "LDAP", "ADSI"}
# Default Value: None
authType=TEXT
# Specifies the internal repository file
# which has been created with ssxtxtpasswd utility
# Is Required: No
# Valid values:
# fully qualified file name
# Default Value: None
internalRepository=<fullpath>/<filename>.<ext>
# Specifies the log level.
# Is Required: No
# Valid values:
# 0 - No logging
# Min: 1
# Max: 6
# Default Value: None
##nativeLogLevel=0
# Specifies the log file.
# Is Required: No
# Valid values:
# fully qualified file name
# No default value
##nativeLogFile=SAGSSXCLIENTA_SSX.LOG
[SSX_CONFIGURATION-END]
[SSX_CONFIGURATION]
# This is a sample properties file for the case
# when authType is LDAP and the user database is OpenLDAP
# Specifies the authentication type.
# Is Required: Yes
# Valid values: {"OS", "TEXT", "LDAP", "ADSI"}
# Default Value: None
authType=LDAP
# Specifies which server type will be used.
# Is Required: No
# Valid values: {"ActiveDirectory", "SunOneDirectory", "OpenLdap"}
# Default value: "OpenLdap"
serverType=OpenLDAP
# Property name that denotes a user entry.
# Is Required: No
# Valid values: (attribute name according to LDAP conventions)
# Default Value: None
userIdField=cn
# Enumeration of LDAP objectclasses that the user entries use in
# the target LDAP server.
# Is Required: No
# Valid values: (Comma separated list of objectclass names,
# according to LDAP conventions)
# Default value - depending on serverType:
# OpenLdap:
# "top,person"
# SunOneDirectory:
# "top,person,organizationalperson, inetorgperson"
# ActiveDirectory:
# "top,person,organizationalPerson,user"
personObjClass=inetOrgPerson
# Enumeration of LDAP objectclasses that the group entries use in
# the target LDAP server.
# Is Required: No
# Valid values: (Comma separated list of objectclass names,
# according to LDAP conventions)
# Default value - depending on serverType:
# OpenLdap:
# "top,groupOfUniqueNames"
# SunOneDirectory:
# "top,groupofuniquenames"
# ActiveDirectory:
# "top,group"
groupObjClass=groupOfUniqueNames
# Property name that denotes a group entry.
# Is Required: No
# Valid values: (attribute name according to LDAP conventions)
# Default value: cn
groupIdField=cn
# Property name of a user entry that points to the group that
# the user is member of.
# Is Required: No
# Valid values: (attribute name according to LDAP conventions)
# Default value:
# depending on serverType:
# OpenLdap:
# "ou"
# SunOneDirectory:
# NULL
# ActiveDirectory:
# "memberOf"
personGrpAttr=ou
# Property name of a group entry that points to users (members)
# Is Required: No
# Valid values: (attribute name according to LDAP conventions)
# Default value:
# depending on serverType:
# OpenLdap:
# "uniqueMember"
# SunOneDirectory:
# "uniqueMember"
# ActiveDirectory:
# "member"
groupPrsAttr=uniqueMember
# Seconds how long auth. user remains in cache.
# Is Required: No
# Valid values:
# 0 - No cache
# Min: 1, Max: No limit
# Default value: 180
cacheTime=12
# Specify the max. number of cached users that have been successfully
# authenticated. When the cache overflows, the oldest entry is removed.
# Is Required: No
# Valid values:
# 0 - No cache
# Min: 1, Max: No limit
# Default value: 300
cacheSize=4
# Time (in seconds) how long to ignore any further authentication
# requests for a particular User-Id.
# Is Required: No
# Valid values:
# Min: 1, Max: No limit
# Default value: 100
denyTime=4
# Number of invalid logon attempts.
# Is Required: No
# Valid values:
# Min: 1, Max: No limit
# Default value: 3
denyCount=3
# Specifies an output file for logging.
# Is Required: No
# Valid values: (Valid log file path)
# Default Value: None
logCallback=true
# Specifies the log level.
# Is Required: No
# Valid values:
# 0 - No logging
# Min: 1
# Max: 6
# Default Value: None
##nativeLogLevel=0
# Specifies the log file.
# Is Required: No
# Valid values:
# fully qualified file name
# No default value
##nativeLogFile=SAGSSXCLIENTA_SSX.LOG
# Default group to be automatically included for all requests
# that return any groups
# Is Required: No
##defaultGroup=DefGroup
# BaseBindDN where to find the users.
# Is Required: Yes
# and should contain the most detailed DN to find the users
# personBindDn=ou=User,o=Org,dc=mycom,dc=com
# BaseBindDN where to find the groups.
# Is Required: Yes
# and should contain the most detailed DN to find the groups
##groupBindDn=ou=Groups,o=Org,dc=mycom,dc=com
# Attribute name of the password.
# Required when changeing the password
# Is Required: Not always
# Default value:
# depending on serverType:
# OpenLdap:
# "userPassword"
# SunOneDirectory:
# "userPassword"
# ActiveDirectory:
# "unicodePwd"
##passwdField=userPassword
# Allow to pass a complete BaseBindDN
# via the domain parameter.
# Is Required: No
# Valid values: 0, 1
##allowdomainasbasebinddn=0
# Allow to specify which fields to search for as properties
# of a user entry
# Is Required: No
# Valid values: string, for example: "cn,sn,description"
##personPropAttr
# Allow to specify which fields to search for as properties
# of a group entry
# Is Required: No
# Valid values: string, for example: "cn,description"
##groupPropAttr
# Allow to use the special secure authentication using SASL,
# providing the directory supports this mechanism.
# Is Required: No
# Valid values: 0, 1 (default: 0)
##ldapSaslBind
# Allow to switch from a non-secure connection to a TLS connection,
# providing the directory supports this mechanism.
# of a group entry
# Is Required: No
# Valid values: 0, 1 (default: 0)
##ldapStartTls
# By default, the first "dc=" occurrence within the distinguished name
# name string denotes the domain name.
# If additional abbreviations want to be defined, one can use
# the following 2 parameter.
# Example: Short="RnD;Admins;board"
# with Long="ou=Rnd,ou=user,dc=mycom,dc=com;ou=Administrators,dc=mycom,dc=com;ou=VIP,dc=mycom,dc-com"
##ldapDomainShort
##ldapDomainLong
# If NOT the automatic domain name should be used to compose
# the canonical user id (SSXGetCanonicalUserId_A/W),
# specify this part of the ID here.
##canonicalDomainName
# Three algorithms are supported to find the groups of a user:
# "ru", recurse up: take the group pointer from the user entry
# and continue to search up for all groups
# found
# "rd", recurse down: search for all groups that have the
# user as member (no recursion)
# "cp", computed property: use a special field in the user
# entry to find all groups
# --> computedGroupProp retired
# Default: "ru"
##resolveGroups
# If resolveGroup is set to "cp", this parameter must provide
# the field name to look for in the user entry that denotes
# the user groups
# Default: None
##computedGroupProp=
# If the LDAP connection is protected by SSL/TLS, this
# parameter must be set.
# Valid Values: 0, 1
# Default: 0
##ldapSSLConnection=1
[SSX_CONFIGURATION-END]
[SSX_CONFIGURATION]
# This is a sample properties file for the case
# when authType is ADSI and the user database is Active Directory
# Specifies the authentication type.
# Is Required: Yes
# Valid values: {"OS", "TEXT", "LDAP", "ADSI"}
# Default Value: None
authType=ADSI
# Specifies the name of the AD Forest.
# Is Required: No, but should be specified
# Example: "dc=mycom,dc=com"
# (with a possible domain called "dc=eur,dc=mycom,dc=com")
# Default Value: None
##adsiForestDn
# Seconds how long auth. user remains in cache.
# Is Required: No
# Valid values:
# 0 - No cache
# Min: 1, Max: No limit
# Default value: 180
cacheTime=12
# Specify the max. number of cached users that have been successfully
# authenticated. When the cache overflows, the oldest entry is removed.
# Is Required: No
# Valid values:
# 0 - No cache
# Min: 1, Max: No limit
# Default value: 300
cacheSize=4
# Time (in seconds) how long to ignore any further authentication
# requests for a particular User-Id.
# Is Required: No
# Valid values:
# Min: 1, Max: No limit
# Default value: 100
denyTime=4
# Number of invalid logon attempts.
# Is Required: No
# Valid values:
# Min: 1, Max: No limit
# Default value: 3
denyCount=3
# Specifies an output file for logging.
# Is Required: No
# Valid values: (Valid log file path)
# Default Value: None
# nativeLogFile=SIN_SSX.log
logCallback=true
# Specifies the log level.
# Is Required: No
# Valid values:
# 0 - No logging
# Min: 1
# Max: 6
# Default Value: None
##nativeLogLevel=0
# Specifies the log file.
# Is Required: No
# Valid values:
# fully qualified file name
# No default value
##nativeLogFile=SAGSSXCLIENTA_SSX.LOG
# In case the scope for the node to access users needs to be limited,
# one can specify a particular subtree:
# Example: "ou=user,ou=Rnd,dc=mycom,dc=com"
##adsiPersonBindDn
# In case the scope for the node to access groups needs to be limited,
# one can specify a particular subtree:
# Example: "ou=groups,ou=Rnd,dc=mycom,dc=com"
##adsiGroupBindDn
# By default, the first "dc=" occurrence within the distinguished name
# name string denotes the domain name.
# If additional abbreviations want to be defined, one can use
# the following 2 parameter.
# Example: Short="RnD;Admins;board"
# with Dn="ou=Rnd,ou=user,dc=mycom,dc=com;ou=Administrators,dc=mycom,dc=com;ou=VIP,dc=mycom,dc-com"
##adsiDomainShort
##adsiDomainDn
# If NOT the automatic domain name should be used to compose
# the canonical user id (SSXGetCanonicalUserId_A/W),
# specify this part of the ID here.
##canonicalDomainName
# Three algorithms are supported to find the groups of a user:
# "ru", recurse up: take the group pointer from the user entry
# and continue to search up for all groups
# found
# "rd", recurse down: search for all groups that have the
# user as member (no recursion)
# "cp", computed property: use a special field in the user
# entry to find all groups
# --> computedGroupProp retired
# Default: "ru"
##resolveGroups
# If resolveGroup is set to "cp", this parameter must provide
# the field name to look for in the user entry that denotes
# the user groups
# Default: None
##computedGroupProp=
[SSX_CONFIGURATION-END]
The following section describes the creation and administration of the internal user repository file, which is used with Authorization Type TEXT.
You can create and/or modify internal user repository files with
the ssxtxtpasswd tool.
To start the ssxtxtpasswd tool, you use a command
prompt. When you start the tool, you enter a user name and a password which are
then encrypted (SHA512 and Base64) and provided in the result text file. The
tool adds new or replaces existing user credentials in the text file.
Note:
When you enter a user name, you can use only digits, Latin
letters, and the following characters: ! ( ) - . ? [ ] _ ~ . When you enter a
password, you can use only digits, Latin letters, and the following characters:
!"#$%&'()*+,-./:;<=>?[\]^_`{|}~.
Tool to create or update an entry in the SSX text file based
user repository.
Usage: ssxtxtpasswd [-f filename] [-c] [-p password] [-d | -e] userId
Use "-c" to create a new file.
Usually, the file should exist and user entries are
replaced/added.
Use "-p" to provide the password on the command line instead
via an extra prompt.
Use "-d" to remove the specified user entry from the text file.
Use "-e" to check, whether the userId is already stored in the text file.
Note: The password usually will be read via a non-echo command input.
When no filename is specified, a default of "ssx_user" is assumed.
ssxtxtpasswd -f SAGInternalUserRepository.txt -c -p mypsw myuid Hash: bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVkA== User entry for "myuid" successfully added
* * * SAG Internal User Repository * version:3.0 * user:myuid:$6a$bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVkA==