You can create and/or modify internal user repository files that contain user names and their respective encrypted passwords. Currently, there are two Software AG Security Infrastructure tools that you can use for this purpose: Internal User Repository Command Line Tool and the ssxtxtpasswd tool. Software AG recommends the usage of Internal User Repository Command Line Tool.
The information is organized under the following headings:
The start scripts of the tool,
internaluserrepo.bat and
internaluserrepo.sh, are in the
<SoftwareAG_directory>/common/bin directory. At a
later stage, you can use the user repositories files with login modules that
have a property for using such files (for now, these login modules are
InternalLoginModule and
SSXLoginModule).
To create and/or modify an internal user repository file
Use the command prompt to open the <SoftwareAG_directory>/common/bin directory.
Depending on the operating system, start the tool using one of the following commands:
Windows
internaluserrepo.bat [-f <filename>] [-c] [-p
<password>] [-d | -e] <userId>
UNIX
./internaluserrepo.sh [-f <filename>] [-c] [-p
<password>] [-d | -e] <userId>
where
| Argument | Description |
|---|---|
-h,
-help |
Prints guidelines for using the tool. |
-f,
-file |
Specifies the user repository file. |
-c,
-create |
Creates a text repository file. You can
specify the location and file name with the -f argument
followed by the wanted URL (path and name of the file to be created). If only
the -c option is specified, a file, named
users.txt, is created in the execution directory of the
tool. If you do not use the -c argument and the
specified text file does not exist, an error is returned. If you specify
-c and the file already exists, the new information is
added at the end of the repository file.
|
-p,
-password |
Provides the specified password on the
command line.
Note: |
-d,
-delete |
Deletes the credentials for the specified user from the text repository file. If you do not specify a file and a users.txt file exists in the directory of the tool, the user is removed from this file. |
-e,
-existing |
Checks whether the specified user exists in
the text repository file. You should provide a URL to the file using the
-f argument.
|
| <userId> | Contains the user name for the text
repository file operation. If you call the tool only with this option and a
users.txt file exists in the directory of the tool, a new
user with a user name <userId> is added in the
file. Then, a prompt asks for the user password. If a user with this userId
already exists in the repository file, the password is changed.
Note: |
Note:
The only required parameter is
userId.
Internal User Repository Command Line Tool returns exit codes that define the result of the execution. If the command is executed successfully, no exit status is returned.
You can see the descriptions of the exit codes in the following table:
| Exit code | Description |
|---|---|
| -1 | The specific
userId that is searched for (option
-e) does not exist in the repository file.
|
| 1 | The password is not set. Please specify a password. |
| 2 | The userId is too
long. The maximal length for a userId is 128
characters.
|
| 3 | The userId
contains an invalid character.
|
| 4 | The password contains an invalid character. |
| 5 | The password is too long. The maximal length for a password is 128 characters. |
| 6 | The repository file is inconsistent. Multiple version occur in the repository file. |
| 7 | The repository file is inconsistent. The version is invalid. |
| 8 | The repository file is inconsistent. The repository version is not specified. |
| 9 | The repository file cannot be opened or created. |
| 10 | The userId is
missing.
|
| 11 | The specified parameter is conflicting or invalid. |
Software AG Security Infrastructure provides also another tool
(ssxtxtpasswd.exe, ssxtxtpasswd) with
which you can create internal user repository files. At a later stage, you use
these files with the SSXLoginModule. By default, the
tool is available in the following directory on the file system:
Software AG_directory\
common\runtime\security\bin. 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:
!"#$%&'()*+,-./:;<=>?[\]^_`{|}~.
To create and/or modify an internal user repository file
Using the command prompt, open the following directory:
Software AG_directory\ common\runtime\security\bin
You cannot start the tool from a different location on the file system.
Depending on the operating system, start the tool using one of the following commands:
Windows
ssxtxtpasswd.exe [-c] [–f <result file
name>] [-p <password>] [-d]
<user ID>
UNIX
./ssxtxtpasswd [-c] [–f <result file
name>] [-p <password>] [-d]
<user ID>
To customize the invocation of the tool in the means of invocation parameters, you can use a set of pre-defined optional arguments. The available arguments and the respective descriptions are as follows:
| Argument | Description |
|---|---|
-f |
Provide a name for the result text file which contains the user credentials. If you do not use this argument the tool creates a default result file called ssx_user. |
-c |
Using this parameter, you create a text repository file with a
specified name ( |
-p |
Provide a password directly on the command line. Thus, the tool does not invoke a non-echo input of the password in the next steps. |
-d |
Remove credentials data for a particular user from the text
repository file. When you use the |
user ID |
Provide user name which you want to add or replace in the text file. |
Press Enter and then provide the password.
The following examples provide information about more typical use cases of the tool:
ssxtxtpasswd.exe –c –f
internalUser.txt –p pass
myUser
ssxtxtpasswd.exe –c –f
internalUser.txt –p
newpass myUser
ssxtxtpasswd.exe –d –f
internalUser.txt
myUser
The tool creates a text file, which contains the encrypted internal
user repository credentials, and stores it in the same directory in which you
started it. As a next step, you can provide the file to the
SSXLoginModule and search for INTERNAL users.
