Managing APIs in Password Manager Pro

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 Password Manager Pro 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.

At the end of this document you will have learnt the following:

Prerequisites to Configure the APIs
Workflow of the Steps involved in API Management
Initial Configurations to Create API Users in Password Manager Pro
Types of APIs Supported
Command Line Interface (CLI) for scripts over secure shell (SSH)
Comprehensive application API based on XML-RPC over HTTPS
RESTful API

1. Prerequisites to Configure the APIs

The following are the important points to be assured before configuring and using the APIs, from version 6.2:

User accounts that use only the Password Manager Pro APIs have to be created in Password Manager Pro. 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 any of the API types such as XML-RPC, SSH CLI, and RESTful API.
The XML-RPC and SSH CLI users are authenticated using PKI authentication. So, the following should be supplied to each user, depending on the type of API used:

A X.509 format SSL certificate that has the user name as the common name for using XML-RPC API.
An OpenSSH format public key, corresponding to the private key of user@host, for using SSH CLI.

Password Manager Pro has built in XML-RPC and SSH servers that can be configured to run on specific ports.
Once the API users are created and the respective servers (XML-RPC and/or SSH) are enabled, Password Manager Pro 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 Password Manager Pro:

3. Initial Configurations to Create API Users in Password Manager Pro

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 Password Manager Pro 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.

Click to Expand

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 Password Manager Pro.
Enter the name of the host from where the API user would access Password Manager Pro 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 Password Manager Pro 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. To make use of the SSH CLI access, browse and select the open SSH format public key of the CLI user.
1. 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 and 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. To store them in a different location, import the id_rsa.pub. Now, it will be stored in Password Manager Pro under <PMP_HOME>/<user name>/.ssh/authorized_keys]
  4. 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 every time 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 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.
To make use of XML-RPC API access, enter the X.509 format SSL certificate of the XML-RPC API user. Certificates can be created using OpenSSL and it can either be signed by a Certificate Authority (CA) or it could be self-signed.
8a. Generating a Certificate
1. Creating a certificate using openssl involves two steps - generating private key and generating certificate. Use the following commands to create the certificate.
2. Use the following command to Generate private key.
  - openssl genrsa -des3 -out server.key 2048
3. Generate a certificate request.
4. Use the server private key to create a certificate request. Enter the passphrase for the key, Common Name, hostname or IP address, when prompted:
  - openssl req -new -key server.key -out server.csr
5. After generating the certificate, you need to get it signed by a CA. Here, you have the option to get it signed by a third-party CA such as Verisign, Thawte, RapidSSL, etc or you may self-sign the certificate.
Procedure for both have been explained below. Choose one based on your environment:

8b. Signing the Certificate
1. Getting the Certificate Signed by third-party CA (like Verisign)
  1. Some of the prominent CAs are Verisign, Thawte, RapidSSL. Check their documentation / website for details on submitting CSRs and this will involve a cost to be paid to the CA.
  2. This process usually takes a few days time and you will be returned your signed SSL certificate and the CA's root certificate as .cer files.
  3. Save them both in the same working folder where files from steps 1 and 2 are stored.
    (or)
2. Self-Signing the Certificate
  The procedure for self-signing the certificate involves the following steps:
  1. Creating Private Key
    1. Use the following command to create private key:
      - openssl genrsa -des3 -out server.key 2048
    2. This command generates output like this:
      Generating RSA private key, 2048 bit long modulus
      .....++++++
      .............
      .++++++
      e is 65537 (0x10001)
    3. Enter pass phrase for ca.key: password
    4. Verifying - Enter pass phrase for ca.key: confirm_password
  2. Creating Public Key Without CA
    1. Use the following command to create public key without using CA:
      - openssl req -new -x509 -key server.key -out server.crt -days 1095
    2. The output from this command looks like this:
      - Enter pass phrase for ca.key: password
      - Country Name (2 letter code) [AU]: US
      - State or Province Name (full name) [Some-State]: CA
      - Locality Name (eg, city) []: Pleasanton
      - Organization Name (eg, company: Zoho Corporation
      - Organizational Unit Name (eg, section) []: Manage Engine Password Manager Pro
      - Common Name (eg, YOUR name) []: localhost
      - Email Address []: email

8c. Generate PKCS12 Certificate File

The procedure for self-signing the certificate ends with the above step. However, you require to generate PKCS12 file for use in the calling application in A-to-A password management. Use OpenSSL to convert an x509 certificate and/or RSA key to a Public-Key Cryptography Standard #12 (PKCS#12) format:

openssl pkcs12 -export -clcerts -in server.crt -inkey server.key -out server_cert.p12 -name "PMP"

Enter the department to which the user belongs (optional).

Enter the location of the user. This would be helpful for future reference (optional).

Click Save. The required API user with desired access restriction has been created.

Notes:

You can make use of either or both XML-RPC API & SSH CLI API. The API user creation process is the same for both.
The API user creation is specific to the host from where the application would contact Password Manager Pro 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. Types of APIs Supported

Password Manager Pro provides three API flavors:

Command Line Interface (CLI) for Scripts Over Secure Shell (SSH)
Comprehensive Application API based on XML-RPC Over HTTPS
RESTful API

The XML-RPC and SSH CLI use PKI authentication for allowing access to the Password Manager Pro application through the API. The XML-RPC API also comes with a Java Wrapper API to make it easy for integrating it with Java applications.

5. Command Line Interface (CLI) for Scripts Over Secure Shell (SSH)
(Feature available in both Premium and Enterprise Editions)

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

Creating an API user
Configurations on the Server Side and Starting the SSH Server.
Configurations on the Client Side to Enable Applications Access to Password Manager Pro.

5.1 Create an API User

Click here to learn about creating an API user.

5.2 Configurations on the Server Side and Starting the SSH Server

Password Manager Pro comes with an inbuilt SSH server. By default, it occupies 5522. 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 options listed on the left hand side.

Change the SSH-CLI server port, if you want to.
Click Start SSHD Server.

5.3 Accessing Password Manager Pro from the Application

Once you have created API users and also started SSH server in Password Manager Pro, API users can access Password Manager Pro for the passwords that are allotted to them. Note that the ownership and sharing mechanism of Password Manager Pro 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 <PMP_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 Password Manager Pro for various password operations

As explained above, the API users will be allowed to access Password Manager Pro 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 Password Manager Pro for password management operations. The API user will be allowed to access Password Manager Pro 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 Password Manager Pro. The SSH server, in turn, connects to Password Manager Pro 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 Password Manager Pro-specific commands to carry out the required password management operations.

ssh -q [-p port] user@hostname [-i private_key] [Password Manager Pro specific command]

Example:

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

For MSP Edition use the below command:

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

Example:

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

5.3.i Password Manager Pro 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 PMP> --account=<ACCOUNT NAME As Present in PMP> --reason=<REASON For Password Access> --ticketid=<TICKET ID For Password Access>

Example:

ssh -q -p 5522 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 PMP> --account=<ACCOUNT_NAME As Present in PMP> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset>

Example:

ssh -q -p 5522 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 PMP> --account=<ACCOUNT_NAME As Present in PMP> --newpassword=<NEW PASSWORD> --reason=<Reason for Password Reset> --ticketid=<TICKET ID For Password Reset>

Example:

ssh -q -p 5522 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 5522 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. After executing the above command, I did not receive any response from Password Manager Pro.

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

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

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

Contact Password Manager Pro support with the message you see on the screen.

2. When I tried to retrieve a password from Password Manager Pro Secondary Server in High Availability mode, I did not get the requested password.

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

5.3.ii Accessing Password Manager Pro Secondary for A-to-A Password Management (HA Mode - SSH CLI)

If you have configured high availability setup in Password Manager Pro, 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:

Navigate to <PMP_Primary_Installation_Folder>.
Copy the 'sshd' directory and paste it under <PMP_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, Password Manager Pro comes with an inbuilt SSH server. It has to be started in the Password Manager Pro secondary installation as explained below:

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

5.3.iii Commands for accessing Password Manager Pro 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@PMP_Secondary_hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As presentin PMP> --account=<ACCOUNT NAME As Present in PMP> --reason=<REASON For Password Access>

Example:

ssh -q -p 5522 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.

6. Configuring Application API based on XML-RPC Over HTTPS

(Feature available in both Premium and Enterprise Editions)

Create an API user.
Configurations on the Server-Side.
Configurations on the Client-Side to Enable Applications Access Password Manager Pro.

Option to use Java Wrapper provided by Password Min the calling application (OR) you may make use of XML-RPC client (using other programming languages as existing in your environment)If you decide to use the Java Wrapper provided by Password Manager Pro, download API jars and place them on the hosts from where applications would connect to Password Manager Pro.
Edit entries in configuration file that is bundled with the jar
Include the PMP-specific commands in the calling application
If you decide to use XML-RPC client with other programming languages as existing in your environment, include PMP-specific commands in the calling application

6.1 Create an API User

Click here to learn about creating an API user.

6.2 Configurations on the Server-Side

6.2.i Configuring the XML-RPC Server Port

Password Manager Pro comes with an inbuilt XML-RPC server. By default, it occupies 7070. You can configure it to run on any other desired port.

To configure the XML-RPC server port,

Navigate to Admin >> Configuration >> Password Management API.
Now, select XML-RPC from the left pane.

Click to Expand

Mention the desired XML-RPC Server Port and click Save.
Restart the Password Manager Pro server to apply the changes.

6.2.ii Configuring Self-Signed Certificates or Own Certificates

Note: Skip the following step if you are using a certificate signed by third-party CA.

While creating the API user, in case, you have self-signed SSL certificate (step 8 in prerequisite above) or if you have used an already available internal certificate (your own certificate), you need to specify the root of the CA:

To specify the SSL root certificate,

Navigate to <PMP_Installation_Folder>/bin directory.
Execute the following commands:

In Windows:

In the case of Self-signed certificates:

importCert.bat <absolute path of the Self-signed certificate>

In the case of your own certificates or already available internal CAs:

importCert.bat <absolute path of the root of the CA>

In Linux:

In the case of Self-signed certificates:

sh importCert.sh <absolute path of the Self-signed certificate>

In the case of your own certificates or already available internal CAs:

sh importCert.sh<absolute path of the root of the CA>

Restart the Password Manager Pro server.

Once you execute the above, the root of the CA will be recorded in Password Manager Pro. All the certificates signed by the particular CA will henceforth be automatically taken.

Notes: The root of the CA is recorded in server.xml file present under <PMP_Installation_Folder>/conf directory. To change it or if you want to enter a specific root directory, you may edit the file as explained below:

In server.xml file, look for the following line (hint: you need to look for the line containing the entry clientAuth="true")
<Connector URIEncoding="UTF-8" useBodyEncodingForURI="true" acceptCount="100" clientAuth="true" port="7070"connectionTimeout="-1" debug="0" disableUploadTimeout="true" enableLookups="false" keystoreFile="conf/server.keystore" keystorePass="passtrix" truststoreFile="jre/lib/security/cacerts" maxSpareThreads="75" maxThreads="150" minSpareThreads="25" port="7070" scheme="https" secure="true" sslProtocol="TLS"/>

By default, the root of the CA will be jre/lib/security/cacerts. If you want to edit this, you need to change value for the entry truststoreFile as shown above.

If Online Certificate Status Protocol (OCSP) is enabled in your client certificate, Password Manager Pro will carry out authentication through it. Authentication through OCSP will require access to the Internet. In enterprise network setup, you might need to go through a proxy server to access the Internet. You may specify proxy server settings through Admin >> Settings >> Proxy Server Setting.

6.3 Configurations on the Client-Side

Once you have created API users and also started XML-RPC server in Password Manager Pro, API users can access Password Manager Pro for the passwords that are allotted to them. Note that the ownership and sharing mechanism of Password Manager Pro 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.

Password Management API is XML-RPC based. You have two options here:

Password Manager Pro provides a Java wrapper over XML-RPC. You may use it in the calling application.
You may make use of XML-RPC client (using other programming languages).

6.3.i Using the Java Wrapper Provided by Password Manager Pro

Step 1: Download Java Wrapper Jar from Password Manager Pro

Go to Admin >> Configuration >> Password Management API.
In the UI that opens, select XML-RPC from the left pane.

Click to Expand

Download Java Password Manager Pro API Package in the form of a zip named 'JavaWrapper.zip'
Put the zip in the host from where the application would contact Password Manager Pro. Unzip JavaWrapper.zip
You will get two folders named 'docs' and 'lib' inside the main folder 'JavaWrapper'

Step 2: Edit Entries in the Configuration File

Inside the 'lib' folder of JavaWrapper, you will find a configuration file named 'JAVA_API.conf'
Edit the entries in the configuration file as per the details below:
1. ServerName: The name of the host where the XML-RPC server is running. This will be same as the host where Password Manager Pro is running. The value is entered by default and hence there is no need to edit this value.
2. ServerPort: By default, the XML-RPC server occupies 7070.
3. SecondaryServerName: The name of the host where the Password Manager Pro Secondary server is running. If high availability had been configured prior to setting up A-to-A Password Management, secondary server name is taken by default. In case, you configure high availability afterwards, you need to manually specify the Password Manager Pro Secondary Server's host name here. If you do not intend to use high availability, leave this field blank.
4. SecondaryServerPort: This represents XML-RPC server's port in Password Manager Pro Secondary installation. By default, it occupies 7070.
5. KeyStorePath: Path of PKCS12 format keystore.
6. KeyStorePassword: Password of PKCS12 format keystore, if applicable.
Example:
- ServerName: testserver
- ServerPort: 7070
- SecondaryServerName: test_workstation_secondary
- SecondaryServerPort: 7070
- KeyStorePath: C:\\openssl\\bin\\file.p12
- KeyStorePassword: passtrix

The calling application should present a SSL certificate when using the Password Management API. The jar provided by Password Manager Pro contains the required certificates.

Step 3: Include Password Manager Pro Specific commands in the calling application

Commands to be included (Refer to Javadocs for details)

1. For Password Retrieval

1.1 If password retrieval does not require a reason to be entered

To retrieve the password of a resource, enter the respective name of the resource and the account name exactly as present in Password Manager Pro.

retrievePassword (String resourceName, String accountName)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        System.out.println(PasswordManagerPro.getInstance().retrievePassword("test-server","administrator"));        }
        catch (PMPException pmpEx)
        {
        }
    }
}

1.2 If password retrieval requires reason to be entered

In case, the Password Manager Pro settings in your environment mandate entering a reason for password retrieval, you need to enter the respective name of the resource and the account name exactly as present in Password Manager Pro. Also, you must provide 'reason' for password retrieval.

retrievePassword (String resourceName, String accountName, String reason)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        System.out.println(PasswordManagerPro.getInstance().retrievePassword("test-server","administrator","testing"));        }
        catch (PMPException pmpEx)
        {
        }
    }
}

1.3 If password retrieval requires ticket ID to be entered

In case, the Password Manager Pro settings in your environment mandate entering a ticket ID for password retrieval, you need to enter the respective name of the resource and the account name exactly as present in Password Manager Pro. Also, you must provide 'ticketId' for password retrieval.

retrievePassword (String resourceName, String accountName, String reason, String ticketId)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        System.out.println(PasswordManagerPro.getInstance().retrievePassword("test-server","administrator","testing","7"));        }
        catch (PMPException pmpEx)
        {
        }
    }
}

2. For Password Reset

2.1 Local Password Reset

To reset the password of a resource locally, enter the respective name of the resource and the account name exactly as present in Password Manager Pro. Providing 'reason' for password reset is optional. For resetting the password locally, specify 'false' for the boolean updateRemote.

changePassword (String resourceName, String accountName, String reason, String updateRemote) (This will assign a new, random password)

OR

changePassword (String resourceName, String accountName, String reason, String newPassword, String updateRemote) (This will assign the new password specified by you)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        PasswordManagerPro.getInstance().changePassword("test-server","administrator","testing","false" );
        }
        catch (PMPException pmpEx)
        {
        }
    }
}

2.2 Remote Password Reset

To carry out remote password reset, enter the respective name of the resource and the account name exactly as present in Password Manager Pro. Specify 'true' as the value for the boolean updateRemote to indicate remote password reset. Optionally, you may include the reason for password reset as a string.

changePassword (String resourceName, String accountName, String reason, String updateRemote) (This will assign a new, random password)

OR

changePassword (String resourceName, String accountName, String reason, String newPassword, String updateRemote) (This will assign the new password specified by you)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        PasswordManagerPro.getInstance().changePassword("test-server","administrator","testing","true");
        }
        catch (PMPException pmpEx)
        {
        }
    }
}

2.3 If password reset requires ticket ID to be entered

2.3.i Local Password Reset

To reset the password of a resource locally, enter the respective name of the resource and the account name exactly as present in Password Manager Pro. Providing 'reason' and 'ticketId' for password reset is optional. For resetting the password locally, specify 'false' for the boolean updateRemote.

changePassword (String resourceName, String accountName, String reason, String updateRemote, String ticketId) (This will assign a new, random password)

OR

changePassword (String resourceName, String accountName, String reason, String newPassword, String updateRemote, String ticketId) (This will assign the new password specified by you)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        PasswordManagerPro.getInstance().changePassword("test-server","administrator","testing","false","7");
        }
        catch (PMPException pmpEx)
        {
        }
    }
}

2.3.ii Remote Password Reset

changePassword (String resourceName, String accountName, String reason, String updateRemote, String ticketId) (This will assign a new, random password)

OR

changePassword (String resourceName, String accountName, String reason, String newPassword, String updateRemote, String ticketId) (This will assign the new password specified by you)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        PasswordManagerPro.getInstance().changePassword("test-server","administrator","testing","true","7");
        }
        catch (Password Manager ProException pmpEx)
        {
        }
    }
}

3. Creating New Resource & User Account

To create a new resource and a user account, enter the name of the resource and the account to be added and the account name exactly as present in Password Manager Pro. Specify 'true' as the value for the boolean updateRemote to indicate remote password reset. Optionally, you may include the notes to serve as reference.

createResource (String resourceName, String resourceType, String accountName, String notes) (This will assign a new, random password for the account being created)

OR

createResource (String resourceName, String resourceType, String accountName, String newPassword, String notes) (This will assign the specific password for the account being created)

Example:

import com.manageengine.pmp.PasswordManagerPro;
import com.manageengine.pmp.PMPException;

class Sample
{
    public static void main(String args[])
    {
        try
        {
        PasswordManagerPro.getInstance().createResource("Mail-Server","Windows","administrator","testing");
        }
        catch (PMPException pmpEx)
        {
        }
    }
}

6.3.ii Making use of XML-RPC Client (using other programming languages)

Refer to this document for details.

6.3.iii Accessing Password Manager Pro in High Availability Mode (XML-RPC)

If you have configured high availability setup in Password Manager Pro, when the Primary Server goes down, applications can seamlessly connect to the Secondary for A-to-A Password Management.

Case 1: If you have configured High Availability setup prior to configuring A-to-A password management through XML-RPC

If you are using a certificate signed by a third-party CA, you need not carry out any specific configuration for accessing secondary server when primary is down. Everything is automatically taken care of.
If you are using self-signed certificate or using your own certificate, you need to import the SSL root certificate in Password Manager Pro Secondary Server by following the steps as explained in one of the sections above .

As mentioned earlier, Password Manager Pro comes with an inbuilt XML-RPC server. By default, it occupies the port 7070 in Password Manager Pro Secondary installation. To change it to some other desired value, you may do so as explained below:

Stop Password Manager Pro Primary Server
Connect to Password Manager Pro Secondary's Web-Interface
Navigate to Admin >> Configuration >> Password Management API
In the UI that opens, select XML RPC from the options on the left hand side.
Mention the XML-RPC port (by default it occupies 7070) and click Save.
Restart Password Manager Pro Secondary Server for this change to take effect.

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.

Case 2: If you configure High Availability setup after configuring A-to-A password management through XML-RPC

In this case, you need to make the following configurations:

Step 1:

Inside the 'lib' folder of JavaWrapper, you will find a configuration file named 'JAVA_API.conf'. You will find an entry named "SecondaryServerName". Against that, specify the host name of the secondary server.

SecondaryServerName=<The name of the host where the Password Manager Pro Secondary server is running>

As mentioned earlier, Password Manager Pro comes with an inbuilt XML-RPC server. By default, it occupies the port 7070 in Password Manager Pro Secondary installation. If you want to change it to some other desired value, you may do so as explained below:

Stop Password Manager Pro Primary Server.
Connect to Password Manager Pro Secondary's Web-Interface
Navigate to Admin >> Configuration >> Password Management API.
In the UI that opens, select "XML RPC" from the options on the left hand side.
Mention the XML-RPC port (by default it occupies 7070) and click Save.
Restart Password Manager Pro Secondary Server for this change to take effect.

Also, specify the new port in 'JAVA_API.conf' against the textfield "SecondaryServerPort".

SecondaryServerPort=<This represents XML-RPC server's port in Password Manager Pro Secondary installation. By default, it occupies 7070>

Step 2:

If you are using self-signed certificate or using your own certificate, you need to import the SSL root certificate in Password Manager Pro Secondary Server by following the steps as explained in one of the sections above. (If you are using a certificate signed by a third-party CA, you need not carry out any specific configuration for accessing secondary server when primary is down. Everything is automatically taken care of).

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.

Managing APIs in Password Manager Pro

1. Prerequisites to Configure the APIs

2. Workflow of the Steps involved in API Management

3. Initial Configurations to Create API Users in Password Manager Pro

8a. Generating a Certificate

8b. Signing the Certificate

(or)

8c. Generate PKCS12 Certificate File

4. Types of APIs Supported

5. Command Line Interface (CLI) for Scripts Over Secure Shell (SSH) (Feature available in both Premium and Enterprise Editions)

5.1 Create an API User

5.2 Configurations on the Server Side and Starting the SSH Server

5.3 Accessing Password Manager Pro from the Application

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

API User Contacting Password Manager Pro for various password operations

For MSP Edition use the below command:

5.3.i Password Manager Pro specific commands to be included in your application for application-to-application password management

1. For Password Retrieval

2. For Password Reset

2.1 For Local Password Reset

2.2 For Remote Password Reset

3. For Creating a New Resource and a User Account

Troubleshooting Tips

5.3.ii Accessing Password Manager Pro Secondary for A-to-A Password Management (HA Mode - SSH CLI)

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

5.3.iii Commands for accessing Password Manager Pro Secondary Server

1. For Password Retrieval

6. Configuring Application API based on XML-RPC Over HTTPS

(Feature available in both Premium and Enterprise Editions)

6.1 Create an API User

6.2 Configurations on the Server-Side

6.2.i Configuring the XML-RPC Server Port

6.2.ii Configuring Self-Signed Certificates or Own Certificates

6.3 Configurations on the Client-Side

6.3.i Using the Java Wrapper Provided by Password Manager Pro

Step 1: Download Java Wrapper Jar from Password Manager Pro

Step 2: Edit Entries in the Configuration File

Example:

Step 3: Include Password Manager Pro Specific commands in the calling application

1. For Password Retrieval

1.1 If password retrieval does not require a reason to be entered

Example:

1.2 If password retrieval requires reason to be entered

Example:

1.3 If password retrieval requires ticket ID to be entered

Example:

2. For Password Reset

2.1 Local Password Reset

OR

Example:

2.2 Remote Password Reset

OR

Example:

2.3 If password reset requires ticket ID to be entered

2.3.i Local Password Reset

OR

Example:

2.3.ii Remote Password Reset

OR

Example:

3. Creating New Resource & User Account

OR

Example:

6.3.ii Making use of XML-RPC Client (using other programming languages)

6.3.iii Accessing Password Manager Pro in High Availability Mode (XML-RPC)

Case 1: If you have configured High Availability setup prior to configuring A-to-A password management through XML-RPC

Case 2: If you configure High Availability setup after configuring A-to-A password management through XML-RPC

Step 1:

Step 2:

5. Command Line Interface (CLI) for Scripts Over Secure Shell (SSH)
(Feature available in both Premium and Enterprise Editions)