Adabas Role-Based Security (ADARBA)

#### Search Results

Search

# Adabas Role-Based Security (ADARBA)

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.

- Adabas Role-Based Security Model

- Security Definitions

- Authentication

- Authorization

- Audit Trail

- Configuration

- Administration

- Performance Considerations

- Application Development

- Getting Started

- Infrastructure Security Library

## Adabas Role-Based Security Model

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.

## Security Definitions

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.

### Initial Security Definitions

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.

### PUBLIC User

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.

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

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.

- Architecture

- Credentials

- Default State

### Architecture

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.

### Credentials

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.

#### Adabas Direct Call Interface

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.

#### Adabas Utilities

Currently, the supported credentials are the local system credentials, which have been authenticated by the operating system.

- Linux: 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.

### Default State

By default, authentication is not enabled.

The configuration and usage of the authentication feature are described in Configuration > Authentication below.

## Authorization

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.

- Adabas Direct Call Interface

- Adabas Utilities

- Protection on Utility Control Parameter Level

- Default State

### Adabas Direct Call Interface

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

### Adabas Utilities

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.

### Protection on Utility Control Parameter Level

This part of authorization allows you to secure specific functions in the Adabas utilities ADADBM and ADAOPR. This is a fine- grained extension of the utility authorization. The following table shows the specific operations on Adabas utilities; all values are case-sensitive:

Operation Name | Utility Operation
--- | ---
ada.uti.dbm.add_container | ADADBM add_container
ada.uti.dbm.add_fields | ADADBM add_fields
ada.uti.dbm.allocate | ADADBM allocate
ada.uti.dbm.bt | ADADBM bt
ada.uti.dbm.change | ADADBM change
ada.uti.dbm.change_fields | ADADBM change_fields
ada.uti.dbm.deallocate | ADADBM deallocate
ada.uti.dbm.define_refint | ADADBM define_refint
ada.uti.dbm.del_cp | ADADBM del_cp
ada.uti.dbm.delete | ADADBM delete
ada.uti.dbm.delete_database | ADADBM delete_database
ada.uti.dbm.drop_fields | ADADBM drop_fields
ada.uti.dbm.drop_lobfile | ADADBM drop_lobfile
ada.uti.dbm.drop_refint | ADADBM drop_refint
ada.uti.dbm.extend_container | ADADBM extend_container
ada.uti.dbm.newwork | ADADBM newwork
ada.uti.dbm.pgm_refresh | ADADBM pgm_refresh
ada.uti.dbm.recordspanning | ADADBM recordspanning
ada.uti.dbm.reduce_container | ADADBM reduce_container
ada.uti.dbm.refresh | ADADBM refresh
ada.uti.dbm.remove_container | ADADBM remove_container
ada.uti.dbm.remove_replication | ADADBM remove_replication
ada.uti.dbm.rename | ADADBM rename
ada.uti.dbm.renumber | ADADBM renumber
ada.uti.dbm.replication_files | ADADBM replication_files
ada.uti.dbm.reset | ADADBM reset
ada.uti.dbm.reset_replication_target | ADADBM reset_replication_target
ada.uti.dbm.reuse | ADADBM reuse
ada.uti.dbm.security | ADADBM security
ada.uti.dbm.syfmax | ADADBM syfmax
ada.uti.opr.abort | ADAOPR abort
ada.uti.opr.add_replication | ADAOPR add_replication
ada.uti.opr.bfio_parallel_limit | ADAOPR bfio_parallel_limit
ada.uti.opr.cancel | ADAOPR cancel
ada.uti.opr.change_replication | ADAOPR change_replication
ada.uti.opr.cluster_log_level | ADAOPR cluster_log_level
ada.uti.opr.delete_replication | ADAOPR delete_replication
ada.uti.opr.delui | ADAOPR delui
ada.uti.opr.ext_backup | ADAOPR ext_backup
ada.uti.opr.feof | ADAOPR feof
ada.uti.opr.free_clq | ADAOPR free_clq
ada.uti.opr.lock | ADAOPR lock
ada.uti.opr.logging | ADAOPR logging
ada.uti.opr.nishnq | ADAOPR nishnq
ada.uti.opr.options | ADAOPR options
ada.uti.opr.response_check | ADAOPR response_check
ada.uti.opr.shutdown | ADAOPR shutdown
ada.uti.opr.stop | ADAOPR stop
ada.uti.opr.stopi | ADAOPR stopi
ada.uti.opr.tnaa | ADAOPR tnaa
ada.uti.opr.tnae | ADAOPR tnae
ada.uti.opr.tnax | ADAOPR tnax
ada.uti.opr.tt | ADAOPR tt
ada.uti.opr.unlock | ADAOPR unlock
ada.uti.opr.wcharset | ADAOPR wcharset
ada.uti.opr.write_limit | ADAOPR write_limit

### Default State

By default, authorization is not enabled.

The configuration and usage of the authorization feature are described in Configuration > Authorization below.

## Audit Trail

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.

- Authentication

- Authorization for Adabas Direct Call Interface

- Authorization for Adabas Utilities

- Default State

### Authentication

The location and layout of the audit trail log file is described in the section Authorization for Adabas Direct Call Interface.

### Authorization for Adabas Direct Call Interface

#### Location

The audit trail log is database-specific and is located in the database directory. The file name is NUCADT.log.

#### Layout of Audit Trail Entry

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 |
ISN | ISN accessed in Adabas file |
Authority | Authentication or Authorization authority | SSX RBAC
Response Code | Adabas response code |
Subcode | Adabas subcode |
SSX Response | SSX response |
SSX Message | SSX message |

An ISN can only be displayed for commands that require an ISN input. These commands are `A1`, `E1`, `HI`, `L1`, `L2`, `L3`, `L4`, `L5`, `L6`, `N2` and `RI` and in case of multi fetch `BT` and `ET`, as well. For all other commands and in case of a failed authentication or authorization, the value 0 will be displayed.

### Authorization for Adabas Utilities

The location of the audit trail file is defined in the RBAC security definition file, which is stored in the RBAC system file of the database.

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.

- Layout of Audit Trail Entry
- Logging of Administrative Operations
- Example

#### Layout of Audit Trail Entry

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 | RESULT= | OK FAIL

#### Logging of Administrative Operations

The administrative changes made in ADARBA are also logged in the audit trail.

Operation | Syntax
--- | ---
initialize | OPERATION=ada.uti.rba.initialize,<file>
create_user | OPERATION=ada.uti.rba,create_user,<user>
drop_user | OPERATION=ada.uti.rba,drop_user,<user>
create_role | OPERATION=ada.uti.rba,create_role,<role>
drop_role | OPERATION=ada.uti.rba,drop_role,<role>
create_operation | OPERATION=ada.uti.rba,create_operation,<operation>
drop_operation | OPERATION=ada.uti.rba,drop_operation,<operation>
create_object | OPERATION=ada.uti.rba,create_object,<object>
drop_object | OPERATION=ada.uti.rba,drop_object,<object>
grant_role | OPERATION=ada.uti.rba,grant_role,<role>,<user>
revoke_role | OPERATION=ada.uti.rba,revoke_role,<role>,<user>
grant_permission | OPERATION=ada.uti.rba,grant_permission,<operation>,<object>,<role>

#### Example

The following example shows an audit trail entry for a failing ADARBA create_user=newuser command.

    2025-01-01T00:00:00Z %AUTHORIZATION-E HOST=redada6c OS="Linux x86_64" USER=user OPERATION=ada.uti.rba.create_user.newuser DBID=189 RESULT=FAIL

### Default State

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.

## Configuration

This section describes the configuration of the Adabas Role-based Security feature.

- Initial Security Configuration

- Authentication

- Authorization

- Audit Trail

### Initial Security Configuration

An initial security configuration is created during installation.

- Authentication is not enabled;

- Authorization is not enabled;

- Audit Trail is not enabled.

### Authentication

Important
Database security cannot be disabled once it has been activated.

#### Enable Authentication

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, we strongly recommend 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.

#### Configure Authentication Authority

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.

### Authorization

#### Enable Authorization

Use the INITIALIZE function with the RBAC_FILE parameter of the ADARBA utility to load the RBAC system file.

#### Define Security Definitions

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.

### Audit Trail

#### Authentication and Authorization for Direct Call Interface

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:

> ACTION

>   Enable or disable Audit Trail logging for authentication and authorization.

> FILTER

>   Log ALL audit trail entries or just the entries for REJECTED authentications and authorizations.

> MAXFILESIZE

>   Create a new audit file with the next sequential number if the current NUCADT log file exceeds the value given to MAXFILESIZE. The default value of MAXFILESIZE is 100 MB.

> TIMEZONE

>   Choose the timestamp layout in Universal Coordinated Time (UTC) or local time.

>   The possible options are UTC and LOCAL. If you do not specify TIMEZONE or you provide an invalid option, the system uses the default setting `TIMEZONE=UTC`.

Please refer to the section Configuration Files in Adabas Extended Operation for further information on AUDIT_TRAIL settings .

#### Authorization for Utilities

The configuration settings for the audit trail log file are stored in the database.

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.

## Administration

The utilities required to configure and administer the authorization feature are:

- ADADBM

- ADAINI

- ADAREP

- ADARBA

### ADADBM

- Use the SECURITY function to enable Adabas RBAC Security;

Note
These functions require that the database is offline.

### ADAINI

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

### ADAREP

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

### ADARBA

- Use the CREATE, DROP, GRANT, REVOKE functions to create, modify and delete security definitions;

- Use the LIST functions to display the security definitions.

- Use the RBAC_FILE function to create the RBAC system file.

Note
These functions require that the database is online.

## Performance Considerations

### Authentication

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.

### Authorization for Direct Call Interface

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.

### Authorization for Adabas Utilities

This feature only has minimal impact on the overall system performance.

### Audit Trail

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

## Application Development

This section covers the following topics:

- Developing Applications

- Modifying Legacy Applications

- Error Handling

- Messages and Codes

### Developing Applications

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.

### Modifying Legacy Applications

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.

### Error Handling

#### Security Mode Active

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

#### Security Mode WARN

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.

### Messages and Codes

The following Adabas nucleus response codes indicate that a security issue has occurred:

#### Authentication

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.

#### Authorization

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.

## Getting Started

This section covers the following topics:

- Prerequisites

- Configuration

- Authentication

- Authorization for Direct Call Interface

- Authorization for Adabas Utilities

### Prerequisites

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.

### Configuration

This section describes how to configure Adabas role-based security (ADARBA).

#### Authentication

The following steps describe how to enable authentication.

1. Ensure the database is offline.

2. Configure the authentication authority for the database.

3. Enable authentication by setting the SECURITY mode.

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

#### Example: Create Credential in an Internal User Repository

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.

#### Example: Configure the Authentication Authority

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.

#### Example: Enable Security Mode

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

#### Authorization

The following steps describe how to enable authorization.

1. Ensure the database is offline.

2. Load the RBAC system file.

3. Start the database.

#### Example: Load the RBAC System File

Use the INITIALIZE function of the ADARBA utility to load the RBAC system file. The RBAC_FILE function of the ADADBM utility, which was previously used to load the RBAC system file, has been deprecated.

    > adarba dbid=190 initialize rbac_file=250
    %ADARBA-I-STARTED,      05-JUN-2023 10:35:21, Version 7.2.0.0 (Linux 64Bit)
    %ADARBA-I-INP, dbid=190
    %ADARBA-I-DBON, database 190 accessed online
    %ADARBA-I-INP, initialize,rbac_file=250
    %ADARBA-I-LOADED, file 250, "RBAC-FILE" loaded
    %ADARBA-I-STATCMD, 0 error(s) occurred
    Restore files dumped on 27-JUL-2018 09:00:19
    %ADARBA-I-TERMINATED,   05-JUN-2023 10:35:22, elapsed time: 00:00:01

Please refer the section Validating the Configuration for an example of how to display the RBAC system file information.

#### Audit Trail

#### Authentication and Authorization Adabas Direct Call Interface

The audit trail log file for authentication and authorization for 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.

1. Configure the audit trail for authentication and authorization for Adabas direct call interface.

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

#### Authorization Adabas Utilities

The modification of the audit trail configuration file settings is described in the section Configuration for Authorization for Adabas Utilities.

#### Example: Display Audit Definitions

The example shows the initial values for audit of utility authorization. Start the database and display the audit definitions.

    > adarba db=nnn audit,display

    %ADARBA-I-STARTED,      26-MAR-2024 14:58:52, Version 7.3.0.0 (Linux 64Bit)
    %ADARBA-I-INP, dbid=nnn
    %ADARBA-I-DBON, database nnn accessed online
    %ADARBA-I-INP, audit,display

    AUDIT=YES
    FORMAT=TEXT
    SEPARATOR=;
    LOGFILE=${ADADATADIR}/dbnnn/adaaudit.log

    %ADARBA-I-STATCMD, 0 error(s) occurred
    %ADARBA-I-TERMINATED,   26-MAR-2024 14:58:52, elapsed time: 00:00:00

#### Validating the Configuration

The following examples show how you can validate the configuration of authentication and authorization.

#### Example: Database Report - Security Configuration

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

#### Example: Display Authentication Configuration

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

#### Display Audit Trail Configuration

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

#### Example: Security Infrastructure Initialized

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

#### Example: Display Security Definitions

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.

### Authentication

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.

#### Example: Use ADATST to validate 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.

#### Example: Use ADATST to validate the usage of Nucleus user exit 21

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.

### Authorization for Direct Call Interface

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.

#### Example: Secure access to 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.

#### List Security Definitions

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

### Authorization for Adabas Utilities

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.

#### Example: Secure access to the ADADBM utility

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

#### Example: List Security Definitions

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

## Infrastructure Security Library

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.

- Authentication Type OS (Operating System)

- Authentication Type TEXT (Internal User Repository)

- Authentication Type LDAP

- Authorization Type ADSI

- Creating Internal User Repository Files

### Authentication Type OS (Operating System)

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 Linux 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: Linux 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.

    ##linuxAddMachineName

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

### Authentication Type TEXT (Internal User Repository)

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]

### Authentication Type LDAP

    [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]

### Authorization Type ADSI

    [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]

### Creating Internal User Repository Files

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: !"#$%&'()*+,-./:;<=>?[\]^_`{|}~.

#### Example: Usage of ssxtxtpasswd tool

    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.

#### Example: Add User and Password

    ssxtxtpasswd -f SAGInternalUserRepository.txt -c -p mypsw myuid

    Hash: bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVkA==
    User entry for "myuid" successfully added

#### Contents of SAGInternalUserRepository.txt

    *
    *
    * SAG Internal User Repository
    *
    version:3.0
    *
    user:myuid:$6a$bOEOAPEEEJBKv+4zOELiYcFqY7qFhlLZz1ha7Ztf7j/drJHGy2ML0LXEu/kX7TD52Aj7XfwiZ+vpIl9DqRbVkA==

### On this page

- Adabas Role-Based Security Model
- Security Definitions
- Authentication
- Authorization
- Audit Trail
- Configuration
- Administration
- Performance Considerations
- Application Development
- Getting Started
- Infrastructure Security Library