Password Management API for Application-to-Application Password Management

(Feature available only in Premium Edition. Procedure applicable only for PMP Builds 6200 onwards)

 

Overview

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

Password Management APIs

Note: The mechanism used to configure and use the API till version 6.1 stands deprecated and will eventually be removed.

From version 6.2 onwards, PMP provides two flavors of the API:

  1. a comprehensive application API based on XML-RPC over HTTPS and

  2. a command line interface for scripts over secure shell (SSH)

 

Both the forms use PKI authentication for allowing access to the PMP 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.     

 

Configuring Password Management APIs - Summary of Activities

The following is the summary of the activities involved on configuring and use the API from version 6.2

 

The following diagram better illustrates the summary of steps involved in Application-to-Application Password Management:

 
 

 

Step-by-step Procedure

Prerequisites

1. Create API User Accounts in PMP

 

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 PMP 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 as user@hostname)

 

To create an API user account,

  1. Click "Add API User" button in "Admin >> Users" tab

  2. In the "Add API User" UI that opens up, 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 'Comman Name'(CN), the Organization Name (O) in the certificate should be same as the organization display name in PMP

  3. Enter the name of the host from where the API user would access PMP 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

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

  5. Select an appropriate access level for the API user being added - Administrator/Password Administrator/Password User

  6. If you are adding a user as "Administrator" or "Password Administrator", you can specify the 'Access Scope'. If you select the option, "Passwords Owned and Shared", the administrator/password administrator will be able to view the passwords owned by them and those shared to them by others. You can choose to make the administrator/password administrator a super administrator, you need to select the option "All Passwords in the System". When you do so, the administrator or the password administrator will be able to access all passwords in PMP without any restriction.

  7. 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,
  8. If you wish to make use of  XML-RPC API access, enter the X.509 format SSL certificate of the XML-RPC API user

    Step 2: Getting the certificate signed by third-party (like Verisign) CA

     

                                                            -OR-

    Self-Signing the certificate

    The procedure for self-signing the certificate involves the following steps: 

Creating Private Key

Use the following command to create private key:

 

openssl genrsa -des3 -out  server.key 2048
  
This command generates output like this:

 

Generating RSA private key, 2048 bit long modulus
.....++++++
.............
.++++++
e is 65537 (0x10001)
Enter pass phrase for ca.key: password
Verifying - Enter pass phrase for ca.key: confirm_password
 

 

Creating Public Key Without CA:

Use the following command to create public key without using CA:

 

openssl req -new -x509 -key server.key -out server.crt -days 1095

 

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

 

Note: If you enter '.', the field will be left blank.

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"

 
Important Note:
 

Steps to Configure SSH CLI Access

Summary of Steps Involved

  1. Create API user (as explained in the Pre-requisite above)
  2. Configurations on the server-side
  3. Starting SSH server
  4. Configurations on the client-side to enable applications access PMP

Configurations on the server-side

PMP 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,

 

  1. Go to "Admin >> General >> Password Management API >> SSH CLI"
  2. Change the SSH-CLI  server port, if you want to
  3. Click "Start SSHD Server"

Accessing PMP from the Application

Once you have created API users and also started SSH server in PMP, API users can access PMP for the passwords that are allotted to them. Note that the ownership and sharing mechanism of PMP 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 access workflow on the client-side: How does it 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 PMP for various password operations

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

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

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

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

 

PMP-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 the following commands in your application invoking the API.

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>

 

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

For Password Reset

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>

 

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

 

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>

 

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

 

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

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

 

Solution

 

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 PMP> --account=<ACCOUNT NAME As Present in PMP> --reason=<REASON For Password Access>

 

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

 

 

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

 

Solution

 

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.

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

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

 

 

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

 

Starting SSH Server in PMP Secondary

 

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

 

  1. Stop PMP Primary Server
  2. Connect to PMP Secondary's Web-Inteface
  3. Go to "Admin >> General >> Password Management API >> SSH CLI"
  4. Change the SSH-CLI  server port, if you want to (by default it occupies 5522)
  5. Click "Start SSHD Server"

Commands for accessing PMP Secondary Server

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

 

For Password Retrieval

 

ssh -q [-p port] user@PMP_Secondary_hostname [-i private_key] RETRIEVE --resource=<RESOURCE NAME As present in 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.

Steps to Configure XML-RPC API

Summary of Steps Involved

  1. Create API user (as explained in the Pre-requisite above)
  2. Configurations on the server-side
  3. Configurations on the client-side to enable applications access PMP
 

Configurations on the server-side

Step 1

Configure XML-RPC Server Port 

 

PMP comes with an inbuilt XML-RPC server. By default, it occupies 7070. You may configure it to run on any other desired port, if you wish to do so.

To configure the XML-RPC server port,

 

  1. Go to "Admin >> General >> Password Management API >> XML-RPC"
  2. Change the XML-RPC  server port, if you want to
  3. Click "Save"
  4. Restart PMP server to give effect to this setting

Step 2:  (If you have self-signed the certificate or using your own certificate, carry out the following configuration; if you are using a certificate signed by third-party CA, skip this step)

While creating the API user, in case, you have self-signed SSL certificate (step 8 in pre-requisite 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,

  1. Navigate to "PMP_Installation_Folder>/bin directory 
  2. Execute importCert.bat (in Windows) or importCert.sh (in Linux) as follows

    (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>  
  3. Restart PMP server

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

Note:

Step 3: Configurations on the client-side

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


Option 1: Using the Java Wrapper Provided by PMP

Step 1: Download Java Wrapper Jar from PMP

  1. Go to "Admin >> General >> Password Management API >> XML-RPC"
  2. Download "Java PMP API Package" in the form of a zip named 'JavaWrapper.zip'
  3. Put the zip in the host from where the application would contact PMP. Unzip JavaWrapper.zip
  4. You will get two folders named 'docs' and 'lib' inside the main folder 'JavaWrapper'

Step 2: Edit Entries in the Configuration File

 

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 PMP contains the required certificates.

Step 3: Include PMP-specific commands in the calling application

Commands to be included  (Refer to Javadocs for details)

For Password Retrieval

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

 

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)
        {
        }
    }
}

If password retrieval requires reason to be entered

 

In case, the PMP 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 PMP. 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)
        {
        }
    }
}

For Password Reset

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 PMP.  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, Boolean updateRemote)  (This will assign a new, random password)

-- OR --


changePassword (String resourceName, String accountName, String reason, String newPassword, Boolean 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)
        {
        }
    }
}

Remote Password Reset

To carry out remote password reset, enter the respective name of the resource and the account name exactly as present in PMP.  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, boolean updateRemote)  (This will assign a new, random password)

 

-- OR --

 

changePassword (String resourceName, String accountName, String reason, String newPassword, Boolean 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)
        {
        }
    }
}

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 PMP.  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)
        {
        }
    }
}

 

Option 2 Making use of XML-PRC client (using other programming languages)

Refer to this document for details.

 

Accessing PMP in High Availability Mode (XML-RPC)

If you have configured high availability setup in PMP, 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 PMP Secondary Server by following the steps as explained in one of the sections above.

 

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

 

    1. Stop PMP Primary Server
    2. Connect to PMP Secondary's Web-Inteface
    3. Go to "Admin >> General >> Password Management API >> XML-RPC"
    4. Change the XML-RPC port, if you want to (by default it occupies 7070)
    5. Click "Save"
    6. Restart PMP 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 PMP Secondary server is running>

 

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

 

    1. Stop PMP Primary Server
    2. Connect to PMP Secondary's Web-Inteface
    3. Go to "Admin >> General >> Password Management API >> XML-RPC"
    4. Change the XML-RPC port, if you want to (by default it occupies 7070)
    5. Click "Save"
    6. Restart PMP 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 PMP 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 PMP 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.

 


© 2014, ZOHO Corp. All Rights Reserved.