(Feature available only in Premium Edition. Procedure applicable only for PMP Builds 6200 onwards)
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.
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:
a comprehensive application API based on XML-RPC over HTTPS and
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.
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:
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,
Click "Add API User" button in "Admin >> Users" tab
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
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
'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.
Select an appropriate access level for the API user being added - Administrator/Password Administrator/Password User
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.
Some of the prominent CAs are Verisign (http://verisign.com), Thawte (http://www.thawte.com), RapidSSL (http://www.rapidssl.com). Check their documentation / website for details on submitting CSRs and this will involve a cost to be paid to the CA
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
Save them both in the same
working folder where files from steps 1 and 2 are stored
-OR-
The procedure for self-signing the certificate involves the following steps:
Use the following command to create private key:
openssl
genrsa -des3 -out server.key
1024
This command generates output like this:
Generating
RSA private key, 1024 bit long modulus
.....++++++
.............
.++++++
e is 65537 (0x10001)
Enter pass phrase for ca.key: password
Verifying - Enter pass phrase for ca.key: confirm_password
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.
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
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,
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.
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.
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] [-l
login_name] 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 automatic A-to-A password management, you need to use the following commands in your application invoking the API.
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
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
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
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 TipsWhen 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. |
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:
Go to <PMP_Primary_Installation_Folder> and copy the 'sshd' directory
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.
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:
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.
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,
The root of the CA is recorded in
server.xml file present under
<PMP_Installation_Folder>/conf directory. For some reason, if you want
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, PMP 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 >> General >> Proxy Server Setting.
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:
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.
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)
{
}
}
}
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)
{
}
}
}
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)
{
}
}
}
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)
{
}
}
}
Refer to this document for details.
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:
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:
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.
© 2009, ZOHO Corp. All Rights Reserved.