C Working with the SSH Connector

This appendix describes Oracle Privileged Account Manager's SSH Connector, and how to work with different SSH targets using the SSH Connector in the following sections:

C.1 About the SSH Connector

Network devices such as routers and firewalls can also have privileged accounts that manage the device. Network administrators will require a password management solution to periodically rotate passwords of the accounts and also use password checkout capability to gain access when required.

Network devices that provide SSH interface for communication can be managed with the SSH connector through the Identity Connector Framework (ICF). Using the SSH connector, Oracle Privileged Account Manager can manage the network devices.

Even though network devices provide SSH connectivity, the shell environment and commands used by various targets can be different from each other. Therefore, customizations are required to ensure that the SSH connector can work with different devices.

This appendix describes the use cases in which the SSH Connector is used and how it works with different devices (routers, firewalls, hypervisors, etc) through the SSH connection.

The SSH Connector makes use of scripts to perform operations on the Target. Each script is a simple sequence of commands. Oracle Privileged Account Manager uses these scripts to search for accounts and update passwords of accounts on the network device. Refer to Section C.2, "Creating Scripts" for more information about how to create these scripts.

The network devices, in addition to different commands, also have different formats of listing out the accounts that are available for management within the device. A regular expression needs to be defined for the SSH connector to parse and understand the search results provided by the device. Refer to Section C.3, "Framing the Search Regex" for more information about how to create a regular expression.

This appendix also provides details on how to customize the configuration for the SSH connector. After the customization is complete, the SSH target and accounts can be added to Oracle Privileged Account Manager. Refer to Section 6.2.2.6, "Configuring the SSH Target Type" for detailed information about configuring the SSH target in Oracle Privileged Account Manager.

C.2 Creating Scripts

A script is a sequence of commands that is executed on the target to perform a desired operation. The script structure for the SSH Connector is a sequence of the COMMAND, EXPECT, and ERROR entries. These tags are not case sensitive, but the order in which they are specified must be precise, as described in the following list:

  • Command: This is the first entry in the SSH Connector script. It is used to specify the command that must be executed on the remote target.

  • Expect: This is the second entry in the SSH Connector script. It used to identify the successful execution of the command.

    Executing a command generates some output on the screen. The "EXPECT" section is used to specify the output that signifies the successful execution and completion of the command. Once the output mentioned in the "EXPECT" section is seen, the script moves to the next "COMMAND" in the script. For example, this can be a prompt symbol indicating that the command has finished and is awaiting the next command, or this can be a success message printed by the command.

  • Error: This is the third entry in the SSH Connector script. It is used to specify any error that may be expected to occur due to unsuccessful execution of commands on a target.

    This entry is mandatory for any command that you specify in the script. Though specifying a value of the "ERROR" entry is optional, the tags of the error that you wish to specify must be provided. If you do not expect an error, then this entry can be specified without any expected value as described in the following example:

    Sample value: ERROR:

    In the preceding example, the "ERROR" entry has be specified without any value following the colon(:) punctuation mark.

$__UID__ and $__PASSWORD__ are the placeholders for the "user" and "password" variables respectively. These placeholders are replaced by the user name and password dynamically. The SSH Connector supports only these two variables.

Note:

There are two underscores (__) before and after the UID and PASSWORD placeholders.

The following examples describe the procedure to write different SSH Connector scripts for a Cisco target:

  1. To create a script for the Search Users operation, perform the following steps:

    1. Specify a sequence of commands to execute the Search Users operation in the Cisco router, such as the enable, and show run | in username commands, as described in the following screenshot:

      Surrounding text describes cisco_c_2_a.gif.

    2. You must translate this sequence into a script that can be understood by the connector. To do so, specify the entries and their values as described in the following sample script in a text file and save the .txt file:

      COMMAND:enable
EXCEPT:#
ERROR: 

COMMAND:show run | in username
EXCEPT:#
ERROR:

  2. To create a script for the Change Password operation, perform the following steps:

    1. Specify a sequence of commands to execute the Change Password operation in the Cisco router, such as the enable, config terminal, and username <user> secret <password> commands, as described in the following screenshot:

      Surrounding text describes cisco_c_2_2_a.gif.

    2. You must translate this sequence into a script that can be understood by the connector. To do so, specify the entries and their values as described in the following sample script in a text file and save the .txt file:

      COMMAND:enable
EXCEPT:#
ERROR:

COMMAND:configure terminal
EXCEPT:(config)#
ERROR:

COMMAND:username $__UID__ secret $__PASSWORD__
EXCEPT:(config)#
ERROR:Invalid Password length - must contain 1 to 25 characters. Password configuration failed|Checking.

      Note:

      In the preceding sample script, multiple expected outputs can be provided for an error. These outputs must be separated by the vertical bar or pipe (|) symbol.

  3. Create a .properties file that is used to map the operation code (that is used to identify the operation) and the script location. The .properties file contains the location, which are the absolute paths of the scripts, preceded by their operation ID. The absolute path to the scripts must be provided in the .properties file. The SSH Connector supports the three following operations:

    Name Operation ID Description
    search user SEARCH_ACCOUNT This script is used to search for an account on the SSH target.
    update password UPDATE_PASSWORD This script is used to update the password of an account's password. The operation ID for update account.
    update account UPDATE_ACCOUNT This script is used only for Cisco devices and it is used to update the privileged mode account password.

    The following is an example of the entries in the .properties file used for the Cisco target:

    /scripts/cisco-nxos/cisco.properties containing

    SEARCH_ACCOUNT=/scripts/cisco-nxos/CiscoSearchUser.txt
UPDATE_PASSWORD=/scripts/cisco-nxos/CiscoUpdatePassword.txt
UPDATE_ACCOUNT=/scripts/cisco-nxos/CiscoUpdateAccount.txt

    Note:

    For more information about the UPDATE_ACCOUNT operation specific to Cisco, refer to Section C.4.1, "Sample Scripts for a Cisco Router With the NX Operating System."

  4. Provide the location of the .properties file in the SSH target configuration for the properties file path parameter. Oracle Privileged Account Manager runtime through the SSH connector will use the .properties file to identify and run the scripts corresponding to the operations.

C.3 Framing the Search Regex

The "Search Regex" operation is used to parse the output buffer of a "search account" command in the "search account" script, and fetch the users, roles, or both.

The command used to search for accounts in each device is different depending on the device, therefore resulting in different outputs. The output contains the list of user accounts and roles available on the device with different formatting depending on the system. The SSH connector uses a regular expression to parse the output and understand the user accounts and roles available on the device.

OPAM will parse each line of the output using the search regex. Patterns are separated with the vertical bar or pipe (|) symbol. If a line within an output matches one of the patterns, it will be parsed. The string corresponding to %u will be parsed as the user name and the string corresponding to %r will be parsed as the role name. If you do not want some lines of the content to be parsed, add them within square brackets [].

For example:

username %u privilege %r password|username %u privilege %r secret

In this example, %u is used to fetch USERNAME and %r is used to fetch the ROLE or PRIVILEGE_LEVEL. The pipe symbol separates two different formats of output produced by the same device. The connector first checks each line for the first format, if it does not match, then it checks for the next format mentioned after the pipe symbol.

Consider the following cases to frame the Search Regex:

C.3.1 Case 1: Red Hat Target

In a Red Hat target, when either the user name or the role is present in a single line, the Search Regex is framed as described in this section.

Consider the following example showing the search accounts output from a Red Hat target:

Surrounding text describes c_4_1_redhat.gif.

In this example, USER %u returns the words after "USER" as the user name, and ROLE %r PARTITION returns the words between "ROLE" and "PARTITION" as the role.

Therefore, in a Red Hat target, when either the user name or the role is present in a single line, the Search Regex is framed as "USER %u|ROLE %r PARTITION".

C.3.2 Case 2: Cisco Target

In a Cisco target, when both the user name and the role is present in a single line, the Search Regex is framed as follows:

Note:

A single target may present the output in different formats. So, to support all the formats for a target, each regex pattern is appended by a vertical bar (|) symbol as shown in the sample pattern in this example.

Consider the following examples showing the search accounts output from a Cisco target:

Example 1:

Surrounding text describes c_4_2_cisco.gif.

Example 2:

Surrounding text describes c_4_2_cisco_a.gif.

In these examples, username %u privilege %r password returns the string between "username" and "privilege" as the user name, and the string between "privilege" and "password" as the role.

Therefore, in a Cisco target, when the user name and the role is present in a single line, the Search Regex is framed as "username %u privilege %r password|username %u privilege %r secret".

C.3.3 Case 3: Juniper Target

In a Juniper target, some sections of the output may need to be excluded using the exclude tag [ ]. This tag is used to filter the undesirable parts of the output buffer. It will exclude all the lines that include the words specified within the exclude tag.

This is an optional field and must be mentioned at the beginning of the regex if needed. This will exclude the extra labels and prompts from appearing as part of the result. Multiple exclude parameters are separated by a slash (/) symbol. In this example, it is used when there are no words before or after, to fetch the desired values.

Consider the following example showing the search accounts output from a Juniper target:

Surrounding text describes c_4_3_juniper.gif.

In this example, USER %u returns the words after "USER" as the user name, and ROLE %r PARTITION returns the words between "ROLE" and "PARTITION" as the role.

The Search Regex in a Juniper target is framed as "[Name/adc-lab/----]|%u %r".

C.4 Sample Scripts

The following sections provide sample scripts for various targets:

C.4.1 Sample Scripts for a Cisco Router With the NX Operating System

This section provides a table with sample values for JSON and sample scripts for the Cisco target.

Note:

Refer to Section 6.2.2.6, "Configuring the SSH Target Type" for detailed information about configuration parameters.

Table C-1 Sample Values For the Configuration Parameters for the Cisco Router

Parameter Name Sample Values

targetType

SSH

targetName

Cisco-nxos-router

PasswordPolicy

Default Password Policy

passwordrollover

false

managePrivilegeModePassword

false

Host

host

Domain

IT

Description

Cisco Router

Port

22

propertiesFilePath

/scripts/cisco-nxos/ciscoscript.properties

loginShellPrompt

[$#%>~]

searchResultRegex

username %u password|username %u secret|username %u privilege|username %u

privilegeModePassword

password

loginUserpassword

loginpassword

loginUser

username

C.4.1.1 Contents Of the Script Files

The "SEARCH_ACCOUNT," "UPDATE_PASSWORD," and "UPDATE_ACCOUNT" operations can be configured in the "ciscoscript.properties" file. You must change the path of these three files in the cisco.properties file and provide the absolute path of these files in your environment.

The following sections provide sample content of the .txt files for these operations:

Contents of the CiscoSearchUser.txt File

COMMAND:show run | in username
EXPECT:[>#]
ERROR:

Contents of the CiscoUpdatePassword.txt File

COMMAND:config terminal
EXPECT:\(config\)#
ERROR:

COMMAND:username $__UID__ password $__PASSWORD__
EXPECT:\(config\)#
ERROR:password is weak

COMMAND:exit
EXPECT:[#]
ERROR:

Contents of the CiscoUpdateAccount.txt File

COMMAND:enable
EXPECT:#
ERROR:Password:|Bad secrets

COMMAND:config terminal
EXPECT:\(config\)#
ERROR:

COMMAND:enable secret $__ENABLEPASSWORD__
EXPECT:\(config\)#
ERROR:

COMMAND:exit
EXPECT:#
ERROR:

C.4.2 Sample Scripts for a Juniper Router With the M7I Operating System

This section provides a table with sample values for JSON and sample scripts for the SSH target.

Note:

Refer to Section 6.2.2.6, "Configuring the SSH Target Type" for detailed information about configuration parameters.

Table C-2 Sample Values for the Configuration Parameters for the Juniper Router

Parameter Name Sample Values

targetType

SSH

targetName

Juniper-m7i-router

PasswordPolicy

Default Password Policy

passwordrollover

false

managePrivilegeModePassword

false

Host

host

Domain

IT

Description

Juniper Router

Port

22

propertiesFilePath

/scripts/juniper_m7i/juniperscript.properties

loginShellPrompt

[$#%>~]

searchResultRegex

set system login user %u uid

privilegeModePassword

  

loginUserpassword

password

loginUser

username

C.4.2.1 Contents Of the Script Files

The "SEARCH_ACCOUNT" and "UPDATE_PASSWORD" operations can be configured in the "juniperscript.properties" file. The following sections provide sample content in the .txt files for these operations:

Contents of the JuniperSearchUser.txt File

COMMAND:show configuration | display set | match uid
EXPECT:[>]
ERROR:

Contents of the JuniperUpdatePassword.txt File

COMMAND:configure
EXPECT:#
ERROR:

COMMAND:set system login user $__UID__ authentication plain-text-password
EXPECT:New password:
ERROR:

COMMAND:$__PASSWORD__
EXPECT:Retype new password:
ERROR:error: require change of case, digits or punctuation

COMMAND:$__PASSWORD__
EXPECT:#
ERROR:

COMMAND:commit
EXPECT:#
ERROR:

COMMAND:exit
EXPECT:>
ERROR:

C.4.3 Sample Scripts for Oracle Integrated Lights Out Manager (ILOM)

This section provides a table with sample values for JSON and sample scripts for the Oracle Integrated Lights Out Manager (ILOM).

Note:

Refer to Section 6.2.2.6, "Configuring the SSH Target Type" for detailed information about configuration parameters.

Table C-3 Sample Values for the Configuration Parameters for the ILOM Target Type

Parameter Name Sample Values

targetType

SSH

targetName

ILOM

PasswordPolicy

Default Password Policy

passwordrollover

false

managePrivilegeModePassword

false

Host

host

Domain

IT

Description

ILOM Target

Port

22

propertiesFilePath

/scripts/ILOM/ILOMscript.properties

loginShellPrompt

[$#%>~]

searchResultRegex

[SP/Targets:/->]|%u

privilegeModePassword

  

loginUserpassword

password

loginUser

username

C.4.3.1 Contents Of the Script Files

The "SEARCH_ACCOUNT" and "UPDATE_PASSWORD" operations can be configured in the "ILOMscript.properties" file. The following sections provide sample content in the .txt files for these operations:

Contents of the ILOMSearchUser.txt File

COMMAND:show -d targets /SP/users
EXPECT:->
ERROR:

Contents of the ILOMUpdatePassword.txt File

COMMAND:set /SP/users/$__UID__ password=$__PASSWORD__
EXPECT:Enter
ERROR:set: Password length must be between 8 and 16 characters

COMMAND:username $__UID__ password $__PASSWORD__
EXPECT:\(config\)#
ERROR:password is weak

COMMAND:$__PASSWORD__
EXPECT:->
ERROR: