Configuring Different APIs

For applications and scripts in your infrastructure that communicate with other applications using a password, you no longer have to hard-code the password in a configuration file or a script. They can securely query PAM360 to retrieve the password whenever they need, so that administrators are free to apply good practices like periodic rotation to such passwords as well, without worrying about having to update them manually in many places.

Here in this document you will learn about the following topics:

Prerequisites to Configure the APIs
Workflow of the Steps involved in API Management
Types of APIs Supported
Command Line Interface (CLI) for Scripts Over Secure Shell (SSH)
RESTful API

1. Prerequisites to Configure the APIs

The following are the important points to be assured before configuring and using the APIs:

User accounts that use only the PAM360 APIs have to be created in PAM360. Every API user account should be attached to a single endpoint (server or desktop from where the API is used, so the user accounts are uniquely identified as user@hostname).
An API user can use either the SSH CLI, or the RESTful APIs.
The SSH CLI users are authenticated using PKI authentication. So, the following should be supplied to each user, depending on the type of API used:

An OpenSSH format public key, corresponding to the private key of user@host, for using SSH CLI.

PAM360 has built in SSH server that can be configured to run on specific ports.
Once the API users are created and the SSH servers is enabled, PAM360 is ready to serve the API users.
Administrators can provide access to passwords to API users in the same way as it is done for other users. API users can only access passwords that they have permission to, through the API.

2. Workflow of the Steps involved in API Management

The following diagram illustrates the summary of steps involved in API management in PAM360:

3. Types of APIs Supported

PAM360 provides two API flavors:

Command Line Interface (CLI) for scripts over secure shell (SSH)
RESTful API

The SSH CLI use PKI authentication for allowing access to the PAM360 application through the API.

4. Command Line Interface (CLI) for Scripts Over Secure Shell (SSH)

Setting up CLI for Scripts over SSH involves the following steps:

Creating API User Accounts in PAM360.
Configurations on the Server Side and Starting the SSH Server.
Configurations on the Client Side to Enable Applications Access to PAM360.

4.1 Creating API User Accounts in PAM360

This is the first step in the process to configure and use password management APIs for Application-to-Application Password Management. As mentioned above, user accounts have to be created in PAM360 to those who will use only the password management API. Every API user account should be attached to a single endpoint (server or desktop from where the API is used, so the user accounts are uniquely identified - for example, as user@hostname)

To create an API user account:

Navigate to Users tab.
Click Add User and select Add API User from the drop down.

Enter the user name in the respective text field. This name identifies the API user. It is important that the same name should be used as the 'Common Name' (CN) in the corresponding SSL certificate. In MSP edition, in addition to the 'Common Name'(CN), the Organization Name (O) in the certificate should be same as the organization display name in PAM360.
Enter the name of the host from where the API user would access PAM360 for password management operations. Internally, the user name and the host together is used to uniquely identify the API user. For example, a user with the name 'test' from the host 'test-server' will be considered as 'test@test-server' to uniquely identify the API user.
'Full Name' refers to the name with which the API user would be identified in the external world. That means, in reports, audit trails and such other places where activities are traced to users. By default, the 'User Name' - 'Host Name' combination with the suffix "API User" is used as 'Full Name'. In the above example, it will be test@test-server - API User. However, if you want to have a different name, you are free to define that.
You can use Access Scope to change an Administrator/Password Administrator/Privileged Administrator into a Super Administrator by choosing the option All Passwords in the system. When you do so, they will be able to access all passwords in PAM360 without any restriction. Conversely, a Super Administrator can be changed to his earlier role of Administrator/Password Administrator/Privileged Administrator by choosing the option Passwords Owned and Shared.
SSH connects and logs into the specified host with user name specified above. The user must prove his identity to the remote machine using public key authentication. If you wish to make use of the SSH CLI access, browse and select the open SSH format public key of the CLI user.
1. If you want to create SSH format private-public key afresh,
  1. Open a command prompt and run the command ssh-keygen.
  2. By default, the private key is stored in id_rsa file. The public key is stored in id_rsa.pub. These two files are stored under the directory specified in the command prompt by default.
  3. If you want, you can store them under a different location. You need to import the id_rsa.pub. It will be stored in PAM360 under <PAM360_HOME>/<user name>/.ssh/authorized_keys]
  4. If you want to have an extra layer of security, you can use passphrase on the SSH key. Once you enter and confirm a passphrase, the passphrase is added to the key. You will have to enter the passphrase everytime when you use the SSH key.
  5. Once you generate the key, specify the location of the public key. (browse and locate in the user addition GUI)
  6. The following snapshot explains the above sequence:
  The above example shows how to generate the key pair using open SSH. You may use any other standard tool to generate the keys as you wish.

Note: The API user creation is specific to the host from where the application would contact PAM360 for passwords, That means, user and host are tied with other. If you want to make use of Password Management API from more than one host, you need to create as many API users as the number of hosts. Conversely, if you wish to have many users on a single host, then again you need to create as many API users as needed.

4.2 Configurations on the Server Side and Starting the SSH Server

PAM360 comes with an inbuilt SSH server. By default, it occupies 6622. You may configure it to run on any other desired port, if you wish to do so. You need to start the SSH server.

To configure the SSH server port and to start it,

Navigate to Admin >> Configuration >> Password Management API.
In the UI that opens, select SSH-CLI from the left pane.

Edit the SSH-CLI server port and click Start SSHD Server.

4.3 Configurations on the Client Side to Enable Applications Access to PAM360

Once you have created API users and also started SSH server in PAM360, API users can access PAM360 for the passwords that are allotted to them. Note that the ownership and sharing mechanism of PAM360 applies in the case of API users too. That means, the API users will be able to access only those passwords that are allotted to them. Using Password Management APIs, users can retrieve, modify and create accounts.

How does Password access workflow on the client-side work?

Each user creates SSH public-private key pair for authentication purposes. The server knows the public key and the user knows the private key. The file <PAM360_HOME>/<user name>/.ssh/authorized_keys lists the public keys that are permitted for logging in. When the user logs in, the SSH program tells the server which key pair it would like to use for authentication. The server checks if this key is permitted, and if so, sends the user a challenge, a random number, encrypted by the user's public key. The challenge can only be decrypted using the proper private key. The user's client then decrypts the challenge using the private key, proving that user knows the private key but without disclosing it to the server. Once the authentication is successful, the user is permitted to do password management operations.

API User Contacting PAM360 for various password operations

As explained above, the API users will be allowed to access PAM360 for password retrieval and other operations only from the host in which they were configured to function. That is, during user creation, you would have entered the name of the host from where the API user would access PAM360 for password management operations. The API user will be allowed to access PAM360 only from the specified host.

To retrieve passwords or to do any other password management operation, the applications running in the host should access the SSH server that runs with PAM360. The SSH server, in turn, connects to PAM360 for password operations.

The SSH server can be accessed using any standard openSSH command. As explained below, along with the command, you need to append PAM360-specific commands to carry out the required password management operations.

ssh -q [-p port] user@hostname [-i private_key] [PAM360 specific command]

Example:

ssh -q -p 6622 test@test-server -i /home/guest/id_rsa [PAM360 specific command]

For MSP Edition use the below command:

ssh -q [-p port] ORGNAME/user@hostname [-i private_key] [PAM360 specific command]

Example:

ssh -q -p 6622 MANAGEENGINE/test@test-server -i /home/guest/id_rsa [PAM360 specific command]

4.3.1 PAM360 specific commands to be included in your application for application-to-application password management:

For automatic A-to-A password management, you need to use specific commands in your application invoking the API. Use the give commands for the following operations:

For Password Retrieval
For Password Reset
For Creating a New Resource and a User Account

1. For Password Retrieval

ssh -q [-p port] user@hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=<REASON For Password Access> --ticketid=<TICKET ID For Password Access>

Example:

ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RETRIEVE --resource=test-server --account=root --reason=Testing password retrieval using ssh client API --ticketid=7

2. For Password Reset

2.1 For Local Password Reset:

ssh -q [-p port] user@hostname [-i private_key] RESET_LOCAL --resource=<RESOURCE NAME AS PRESENT IN PAM360> --account=<ACCOUNT_NAME As Present in PAM360> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset>

Example:

ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RESET_LOCAL --resource=test-server --account=root--newpassword=rootnew --reason=Rotating Password --ticketid=7

2.2 For Remote Password Reset:

ssh -q [-p port] user@hostname [-i private_key] RESET_REMOTE --resource=<RESOURCE NAME AS PRESENT IN PAM360> --account=<ACCOUNT_NAME As Present in PAM360> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset>

Example:

ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RESET_REMOTE --resource=test-server --account=root --newpassword=rootnew --reason=Rotating Password --ticketid=7

3. For Creating a New Resource and a User Account

ssh -q [-p port] user@hostname [-i private_key] CREATE --resource=<RESOURCE NAME To Be Created> --account=<ACCOUNT NAME to be created>--newpassword=<PASSWORD of the Account being added> --resourcetype=<Type of the Resource Being Added> --notes=<Reference Notes>

Example:

ssh -q -p 6622 test@test-server -i /home/guest/id_rsa CREATE --resource=testresource --account=testaccount --newpassword=test password--resourcetype=Windows --notes=A New resource is added

Refer this document for more details.

Troubleshooting Tips

1. When I executed the above command, I did not get any response from PAM360.

Remove the -q option in the above commands. You will receive warning/error messages on the screen.

For example, to retrieve password, execute the command as:

ssh [-p port] user@hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=≪REASON For Password Access>

Contact PAM360 support with the message you see on the screen.

2. When I try to retrieve a password from PAM360 Secondary Server in High Availability mode, I do not get the required password

Every time after adding a new API user, the entire sshd folder available under <PAM360_Primary_Installation_Folder> has to be copied and pasted under <PAM360_Secondary_Installation_Folder>. If this is done, you will be able to access the passwords from PAM360 Secondary.

4.3.2 Accessing PAM360 Secondary for A-to-A Password Management (HA Mode - SSH CLI)

If you have configured high availability setup in PAM360, when the Primary Server goes down, applications can seamlessly connect to the Secondary for A-to-A Password Management. For this to work, you need to make the following simple configuration:

Go to <PAM360_Primary_Installation_Folder>.
Copy the 'sshd' directory and paste it under <PAM360_Secondary_Installation_Folder>.

Important Note: The sshd folder has to be copied and pasted as explained above every time you create a new API user.

As mentioned earlier, PAM360 comes with an inbuilt SSH server. It has to be started in the PAM360 secondary installation as explained below:

Stop PAM360 Primary Server.
Connect to PAM360 Secondary's Welch-Interface.
Go to Admin >> Configuration >> Password Management API >> SSH CLI.
Change the SSH-CLI server port, if you want to (by default it occupies 6622).
Click Start SSHD Server.

4.3.3 Commands for accessing PAM360 Secondary Server

For automatic A-to-A password management, you need to use the following commands in your application:

1. For Password Retrieval:

ssh -q [-p port] user@PAM360_Secondary_hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=<REASON For Password Access>

Example:

ssh -q -p 6622 test@test-secondary-server -i /home/guest/id_rsa RETRIEVE --resource=test-server --account=root --reason=Testing password retrieval using ssh client API

Once the above configuration is done, password access in high availability mode will be seamless. However, as write operations are not permitted when Primary Server is down,applications would only be able to RETRIEVE passwords. They will not be allowed to carry out password reset and resource/account creation.


Configuring Different APIs For applications and scripts in your infrastructure that communicate with other applications using a password, you no longer have to hard-code the password in a configuration file or a script. They can securely query PAM360 to retrieve the password whenever they need, so that administrators are free to apply good practices like periodic rotation to such passwords as well, without worrying about having to update them manually in many places. Here in this document you will learn about the following topics: Prerequisites to Configure the APIs Workflow of the Steps involved in API Management Types of APIs Supported Command Line Interface (CLI) for Scripts Over Secure Shell (SSH) RESTful API 1. Prerequisites to Configure the APIs The following are the important points to be assured before configuring and using the APIs: User accounts that use only the PAM360 APIs have to be created in PAM360. Every API user account should be attached to a single endpoint (server or desktop from where the API is used, so the user accounts are uniquely identified as user@hostname). An API user can use either the SSH CLI, or the RESTful APIs. The SSH CLI users are authenticated using PKI authentication. So, the following should be supplied to each user, depending on the type of API used: An OpenSSH format public key, corresponding to the private key of user@host, for using SSH CLI. PAM360 has built in SSH server that can be configured to run on specific ports. Once the API users are created and the SSH servers is enabled, PAM360 is ready to serve the API users. Administrators can provide access to passwords to API users in the same way as it is done for other users. API users can only access passwords that they have permission to, through the API. 2. Workflow of the Steps involved in API Management The following diagram illustrates the summary of steps involved in API management in PAM360: 3. Types of APIs Supported PAM360 provides two API flavors: Command Line Interface (CLI) for scripts over secure shell (SSH) RESTful API The SSH CLI use PKI authentication for allowing access to the PAM360 application through the API. 4. Command Line Interface (CLI) for Scripts Over Secure Shell (SSH) Setting up CLI for Scripts over SSH involves the following steps: Creating API User Accounts in PAM360. Configurations on the Server Side and Starting the SSH Server. Configurations on the Client Side to Enable Applications Access to PAM360. 4.1 Creating API User Accounts in PAM360 This is the first step in the process to configure and use password management APIs for Application-to-Application Password Management. As mentioned above, user accounts have to be created in PAM360 to those who will use only the password management API. Every API user account should be attached to a single endpoint (server or desktop from where the API is used, so the user accounts are uniquely identified - for example, as user@hostname) To create an API user account: Navigate to Users tab. Click Add User and select Add API User from the drop down. Enter the user name in the respective text field. This name identifies the API user. It is important that the same name should be used as the 'Common Name' (CN) in the corresponding SSL certificate. In MSP edition, in addition to the 'Common Name'(CN), the Organization Name (O) in the certificate should be same as the organization display name in PAM360. Enter the name of the host from where the API user would access PAM360 for password management operations. Internally, the user name and the host together is used to uniquely identify the API user. For example, a user with the name 'test' from the host 'test-server' will be considered as 'test@test-server' to uniquely identify the API user. 'Full Name' refers to the name with which the API user would be identified in the external world. That means, in reports, audit trails and such other places where activities are traced to users. By default, the 'User Name' - 'Host Name' combination with the suffix "API User" is used as 'Full Name'. In the above example, it will be test@test-server - API User. However, if you want to have a different name, you are free to define that. You can use Access Scope to change an Administrator/Password Administrator/Privileged Administrator into a Super Administrator by choosing the option All Passwords in the system. When you do so, they will be able to access all passwords in PAM360 without any restriction. Conversely, a Super Administrator can be changed to his earlier role of Administrator/Password Administrator/Privileged Administrator by choosing the option Passwords Owned and Shared. SSH connects and logs into the specified host with user name specified above. The user must prove his identity to the remote machine using public key authentication. If you wish to make use of the SSH CLI access, browse and select the open SSH format public key of the CLI user. If you want to create SSH format private-public key afresh, Open a command prompt and run the command ssh-keygen. By default, the private key is stored in id_rsa file. The public key is stored in id_rsa.pub. These two files are stored under the directory specified in the command prompt by default. If you want, you can store them under a different location. You need to import the id_rsa.pub. It will be stored in PAM360 under <PAM360_HOME>/<user name>/.ssh/authorized_keys] If you want to have an extra layer of security, you can use passphrase on the SSH key. Once you enter and confirm a passphrase, the passphrase is added to the key. You will have to enter the passphrase everytime when you use the SSH key. Once you generate the key, specify the location of the public key. (browse and locate in the user addition GUI) The following snapshot explains the above sequence: Generating public/private rsa key pair. Enter file in which to save the key (/home/xyz/.ssh/identity): /home/xyz/.ssh/pam360_identity Enter passphrase (empty for no passphrase): enter your passphrase here Enter same passphrase again: repeat your passphrase Your identification has been saved in /home/xyz/.ssh/pam360_identity. Your public key has been saved in /home/xyz/.ssh/pam360_identity.pub. The key fingerprint is: 22:71:3c:ff:7e:df:59:ad:72:47:d1:16:bd:e2:e9:2d xyz@xyz The above example shows how to generate the key pair using open SSH. You may use any other standard tool to generate the keys as you wish. Note: The API user creation is specific to the host from where the application would contact PAM360 for passwords, That means, user and host are tied with other. If you want to make use of Password Management API from more than one host, you need to create as many API users as the number of hosts. Conversely, if you wish to have many users on a single host, then again you need to create as many API users as needed. 4.2 Configurations on the Server Side and Starting the SSH Server PAM360 comes with an inbuilt SSH server. By default, it occupies 6622. You may configure it to run on any other desired port, if you wish to do so. You need to start the SSH server. To configure the SSH server port and to start it, Navigate to Admin >> Configuration >> Password Management API. In the UI that opens, select SSH-CLI from the left pane. Edit the SSH-CLI server port and click Start SSHD Server. 4.3 Configurations on the Client Side to Enable Applications Access to PAM360 Once you have created API users and also started SSH server in PAM360, API users can access PAM360 for the passwords that are allotted to them. Note that the ownership and sharing mechanism of PAM360 applies in the case of API users too. That means, the API users will be able to access only those passwords that are allotted to them. Using Password Management APIs, users can retrieve, modify and create accounts. How does Password access workflow on the client-side work? Each user creates SSH public-private key pair for authentication purposes. The server knows the public key and the user knows the private key. The file <PAM360_HOME>/<user name>/.ssh/authorized_keys lists the public keys that are permitted for logging in. When the user logs in, the SSH program tells the server which key pair it would like to use for authentication. The server checks if this key is permitted, and if so, sends the user a challenge, a random number, encrypted by the user's public key. The challenge can only be decrypted using the proper private key. The user's client then decrypts the challenge using the private key, proving that user knows the private key but without disclosing it to the server. Once the authentication is successful, the user is permitted to do password management operations. API User Contacting PAM360 for various password operations As explained above, the API users will be allowed to access PAM360 for password retrieval and other operations only from the host in which they were configured to function. That is, during user creation, you would have entered the name of the host from where the API user would access PAM360 for password management operations. The API user will be allowed to access PAM360 only from the specified host. To retrieve passwords or to do any other password management operation, the applications running in the host should access the SSH server that runs with PAM360. The SSH server, in turn, connects to PAM360 for password operations. The SSH server can be accessed using any standard openSSH command. As explained below, along with the command, you need to append PAM360-specific commands to carry out the required password management operations. ssh -q [-p port] user@hostname [-i private_key] [PAM360 specific command] Example: ssh -q -p 6622 test@test-server -i /home/guest/id_rsa [PAM360 specific command] For MSP Edition use the below command: ssh -q [-p port] ORGNAME/user@hostname [-i private_key] [PAM360 specific command] Example: ssh -q -p 6622 MANAGEENGINE/test@test-server -i /home/guest/id_rsa [PAM360 specific command] 4.3.1 PAM360 specific commands to be included in your application for application-to-application password management: For automatic A-to-A password management, you need to use specific commands in your application invoking the API. Use the give commands for the following operations: For Password Retrieval For Password Reset For Creating a New Resource and a User Account 1. For Password Retrieval ssh -q [-p port] user@hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=<REASON For Password Access> --ticketid=<TICKET ID For Password Access> *Example:* ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RETRIEVE --resource=test-server --account=root --reason=Testing password retrieval using ssh client API --ticketid=7 2. For Password Reset 2.1 For Local Password Reset: ssh -q [-p port] user@hostname [-i private_key] RESET_LOCAL --resource=<RESOURCE NAME AS PRESENT IN PAM360> --account=<ACCOUNT_NAME As Present in PAM360> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset> *Example:* ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RESET_LOCAL --resource=test-server --account=root--newpassword=rootnew --reason=Rotating Password --ticketid=7 2.2 For Remote Password Reset: ssh -q [-p port] user@hostname [-i private_key] RESET_REMOTE --resource=<RESOURCE NAME AS PRESENT IN PAM360> --account=<ACCOUNT_NAME As Present in PAM360> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset> Example: ssh -q -p 6622 test@test-server -i /home/guest/id_rsa RESET_REMOTE --resource=test-server --account=root --newpassword=rootnew --reason=Rotating Password --ticketid=7 3. For Creating a New Resource and a User Account ssh -q [-p port] user@hostname [-i private_key] CREATE --resource=<RESOURCE NAME To Be Created> --account=<ACCOUNT NAME to be created>--newpassword=<PASSWORD of the Account being added> --resourcetype=<Type of the Resource Being Added> --notes=<Reference Notes> Example: ssh -q -p 6622 test@test-server -i /home/guest/id_rsa CREATE --resource=testresource --account=testaccount --newpassword=test password--resourcetype=Windows --notes=A New resource is added Refer this document for more details. Troubleshooting Tips 1. When I executed the above command, I did not get any response from PAM360. Remove the -q option in the above commands. You will receive warning/error messages on the screen. For example, to retrieve password, execute the command as: ssh [-p port] user@hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=≪REASON For Password Access> Contact PAM360 support with the message you see on the screen. 2. When I try to retrieve a password from PAM360 Secondary Server in High Availability mode, I do not get the required password Every time after adding a new API user, the entire sshd folder available under <PAM360_Primary_Installation_Folder> has to be copied and pasted under <PAM360_Secondary_Installation_Folder>. If this is done, you will be able to access the passwords from PAM360 Secondary. 4.3.2 Accessing PAM360 Secondary for A-to-A Password Management (HA Mode - SSH CLI) If you have configured high availability setup in PAM360, when the Primary Server goes down, applications can seamlessly connect to the Secondary for A-to-A Password Management. For this to work, you need to make the following simple configuration: Go to <PAM360_Primary_Installation_Folder>. Copy the 'sshd' directory and paste it under <PAM360_Secondary_Installation_Folder>. Important Note: The sshd folder has to be copied and pasted as explained above every time you create a new API user. As mentioned earlier, PAM360 comes with an inbuilt SSH server. It has to be started in the PAM360 secondary installation as explained below: If you have configured high availability setup in PAM360, when the Primary Server goes down, applications can seamlessly connect to the Secondary for A-to-A Password Management. For this to work, you need to make the following simple configuration: Stop PAM360 Primary Server. Connect to PAM360 Secondary's Welch-Interface. Go to Admin >> Configuration >> Password Management API >> SSH CLI. Change the SSH-CLI server port, if you want to (by default it occupies 6622). Click Start SSHD Server. 4.3.3 Commands for accessing PAM360 Secondary Server For automatic A-to-A password management, you need to use the following commands in your application: 1. For Password Retrieval: ssh -q [-p port] user@PAM360_Secondary_hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in PAM360> --account=<ACCOUNT NAME As Present in PAM360> --reason=<REASON For Password Access> *Example:* ssh -q -p 6622 test@test-secondary-server -i /home/guest/id_rsa RETRIEVE --resource=test-server --account=root --reason=Testing password retrieval using ssh client API Once the above configuration is done, password access in high availability mode will be seamless. However, as write operations are not permitted when Primary Server is down,applications would only be able to RETRIEVE passwords. They will not be allowed to carry out password reset and resource/account creation.