Getting Started with Access Manager Plus

Once done with setting up Access Manager Plus, the following links will guide you through the process of getting you started with Access Manager Plus:

  1. Starting and Shutting Down Access Manager Plus
  2. Launching the Access Manager Plus Web Client
  3. Using MS SQL Server as Backend Database
  4. Using MS SQL Cluster as Backend Database
  5. Rotating Encryption Key
  6. Managing the Database Password
  7. Updating Web Server Certificates
  8. Transferring Installations
  9. Migrating Database
  10. Troubleshooting Tip

1. Starting and Shutting Down Access Manager Plus

1.1 In Windows

Using the Start Menu Using the Tray Icon
  1. Navigate to Start >> Run [OR] press Win+r. The Run box appears. Type services.msc and hit Enter.
  2. Locate the AMP service in the Services console.
  3. You can start, stop or restart the service from the services console.
  1. Once you have successfully installed Access Manager Plus in your system, you will find the Access Manager Plus icon in the windows tray area on the far right end of your task bar.
  2. Right click the tray icon and click the desired operation:
    • Start the AMP Service
    • Stop the AMP Service
    • Launch the AMP web console

1.2 In Linux

Installing Access Manager Plus as a Startup Service Starting & Stopping the Server as a Service
  1. Login as root user.
  2. Open a console and navigate to <AMP_Home>/bin directory.
  3. Execute sh amp.sh install (In Ubuntu, execute as bash amp.sh install)
  4. To uninstall, execute the script sh amp.sh remove.

To Start Access Manager Plus as a service in Linux:

  1. Login as non- root user
  2. Execute /etc/rc.d/init.d/amp-service start.
  3. Access Manager Plus server runs in the background as service.

To Stop Access Manager Plus Server started as a service, in Linux:

  1. Execute /etc/rc.d/init.d/amp-service stop (as root user).

2. Launching the Access Manager Plus Web Client

There are different ways of connecting to the Access Manager Plus web client and they are:

2.1 Automatic Browser Launch

Once the server has started after the successful installation of Access Manager Plus, the Access Manager Plus Login screen shows up in a browser window. As Access Manager Plus uses the secured HTTPS connection, you will be prompted to accept the Security Certificate. Tap Yes, type the User name and Password in the login screen and press Enter. For an unconfigured setup, the default User name/Password is admin/admin. Every time you start the server, the browser will be automatically launched.

2.2 Launching the Web Client Manually

  • Windows:

Right-click the Access Manager Plus tray icon and click Access Manager Plus Web Console to launch the web client manually. The AMP Login screen shows up in a browser window. As AMP uses the secured HTTPS connection, you will be prompted to accept the Security Certificate. Hit Yes, type the User name and Password in the login screen and press Enter. For an unconfigured setup, the default User name/Password is admin/admin. Every time you start the server, the browser will be automatically launched.

  • Linux:

Open a browser and connect to the URL specified in the below box:

https://<hostname>:portnumber/
where,
<hostname> - the host where the AMP server is running.
<portnumber> - the default port is 9292.
Example: https://localhost:9292

2.3 Connecting the Web Client in Remote Hosts

To connect to the Access Manager Plus web client in a remote machine (different from the one where Access Manager Plus is running), open a browser and connect to the below URL:

https://<hostname>:port

As Access Manager Plus uses the secured HTTPS connection, you will be prompted to accept the Security Certificate. Hit Yes, type the user name and password in the login screen and press Enter. For an unconfigured setup, the default user name and password is admin and admin. Every time you start the server, the browser will be automatically launched.

3. Using MS SQL Server as Backend Database

Though Access Manager Plus supports both PostgreSQL and MSSQL databases as the backend, it is configured to run with PostgreSQL by default, and it comes bundled with the product. If you want to run Access Manager Plus using the MSSQL database, follow the steps below:

3.1 Steps to Run Access Manager Plus with MS SQL Server as the Backend Database

Note: To ensure high level of security, Access Manager Plus has been configured to connect to the SQL server only through SSL.

3.1.1 Create SSL Certificate and Install it in the Windows Certificate Store (in the machine where the SQL server is running)

Prior to connecting Access Manager Plus with the SQL server, you need to enable SSL encryption in the SQL Server. For this, you need to create an SSL Certificate and get it signed by either a Certificate Authority (CA) or self-sign it.

Generating the certificate and getting it signed by a third-party CA:

Create the certificate using openssl. This involves two steps - generating private key and generating certificate request.

  1. Generating Private Key: Execute the following command:

    openssl genrsa -des3 -out server.key 2048

  2. Generating Certificate Request: Follow the below steps:
    1. Use the server's Private Key to create a certificate request. Enter the Passphrase for the key, Common Name, Hostname or IP Address, when prompted. For the Common Name, specify the FQDN of the SQL Server.
      openssl req -new -key server.key -out server.csr
    2. Once the certificate is generated, get it signed by a third-party CA such as VeriSign, Thawte, RapidSSL, etc, or self-sign it, based on your environment's requirement. For more details on submitting the CSRs, refer the corresponding CA's documentation/website. Remember, this is a paid service. In a few days, you will receive your signed SSL certificate and the CA's root certificate as .cer files.
    3. Install the server certificate in the machine where the SQL server is running.
    4. Install the CA root certificate in the Access Manager Plus server.
  3. Installing the server certificate in the machine where the SQL server is running: Use MMC
    1. Click Start >> Run in the machine where the SQL server is running. In the Run dialog box type MMC.
    2. The MMC console is displayed.
    3. From the Console menu, click Add/Remove Snap-in. Click Add and then click Certificates. Click Add again. You will be prompted to open the snap-in for the current user account, the service account, or for the computer account. Select the Computer Account.
    4. Select Certificates (Local Computer) >> Personal >> Certificates.
    5. Right-click Certificates and click All Tasks >> Import.
    6. Browse and select the certificate to be installed.
  4. Installing the CA's root certificate in Access Manager Plus:
    1. Copy the CA's root certificate and paste it under <AMP Installation Folder >/bin directory.
    2. From <AMP Installation Folder>/bin directory, execute the following command:
      importCert.bat <name of the root certificate pasted as explained above>
    3. This adds the certificate to the Access Manager Plus certificate store.

Creating a self-signed certificate:

To create a self-signed certificate and use it, carry out the following steps in the machine where SQL server is installed:

  1. Create a self signed certificate using the certificate creation tool makecert.exe and install it in the machine where the SQL Server is running.
  2. Execute the following command from the machine where SQL server is installed:

    makecert.exe -r -pe -n "CN=amptestlab.manageengine.com" -a sha1 -b 01/01/2011 -e 01/01/2036 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange amptestlab.manageengine.com.cer

    Here, for CN, enter the FQDN of the SQL server, replacing the example entry amptestlab.manageengine.com.

The above command will install a self-signed certificate in your local store. It will also store the certificate in the file: amptestlab.manageengine.com.cer.

3.1.2 Import the SSL Certificate to Access Manager Plus

  1. Copy the server certificate and paste it under the <AMP Installation Folder>/bin directory.
  2. Execute the following command:
    importCert.bat <name of the server certificate>
    This adds the certificate to the AMP certificate store.

3.1.3 Enable SSL Encryption in SQL Server

  1. Click Start in the machine where the SQL server is running. From the Microsoft SQL Server program menu, click Configuration Tools >> SQL Server Configuration Manager.
  2. Expand the SQL Server Network Configuration, right-click the Protocols for the server you want, and then click Properties. (Remember to click the Protocols for section in the left pane of the tool and not the specific Protocols in the right pane.)
  3. In the Certificate window, configure the Database Engine to use the certificate.
  4. Set the ForceEncryption option for the Database Engine to Yes, so that all the client/server communication is encrypted and the clients that cannot support encryption are denied access (recommended). Set the ForceEncryption option for the Database Engine to No, if you want the encryption to be requested by the client application (not recommended).
  5. Restart the SQL Server.

For more details, refer to the section Configuring SSL for SQL Server in the Microsoft's knowledge base article.

3.1.4 Execute ChangeDB.bat in Access Manager Plus

Provide the details about the SQL server to Access Manager Plus by editing the file ChangeDB.bat (Windows) or ChangeDB.sh (Linux). Follow the below steps:

  1. Navigate to the <AMP Installation Folder>/bin folder and execute the file ChangeDB.bat (Windows) or sh ChangeDB.sh (Linux).
  2. In the window displayed, enter the below details:
    1. Select the Server Type as SQL Server.
    2. Host Name: The name or the IP address of the machine, where the MS SQL server is installed.
    3. Instance Name: Specify the named instance of the SQL server, to be used for Access Manager Plus. If the instance name is not specified, Access Manager Plus will try establishing connection with the default instance on port 1433.

      4. Note: Since Access Manager Plus connects to MS SQL only in SSL mode, it is recommended that you create a dedicated database instance running in a specific port for Access Manager Plus. If you want to specify a port number other than 1433, you can specify it in the Host Name parameter above as <hostname>:<port>.

    4. Database Name: Name of the Access Manager Plus database. Default is PassTrix. If you want to have a different database name, specify it here. Access Manager Plus will take care of creating the Master Key, Symmetric Key, etc.
    5. Authentication: The way by which you wish to connect to the SQL server. Choose Windows, if you are connecting to the SQL server from Windows. Make use of the Windows Single Sign On facility, provided the Access Manager Plus service is running with a service account, which has the privilege to connect to the SQL server. Otherwise, select the option SQL.

      Note: It is recommended to choose the option Windows, as the Username and Password used for authentication are not stored anywhere.

    6. User Name and Password: If you have selected the option SQL in step v, specify the user name and password with which Access Manager Plus can connect to the database.

      7. Notes: The User Name and Password entered here will be stored in the database_params.conf file in Access Manager Plus. So, take care of hardening the host.
      You can use even your Windows login credentials, if you are connecting to the database from Windows. In this case, you need to enter the User Name as <domain-name>\<username>.


    7. Encryption Key: The key to encrypt your data and store it in the SQL server. You may either leave it Default allowing Access Manager Plus to generate a key. If you want to have your custom key, select the option Custom.

      If you have selected the option Custom, do the following:

      Create Database - For details, refer to http://msdn.microsoft.com/en-us/library/aa258257(v=sql.80).aspx
      Create Master Key - For details, refer to http://technet.microsoft.com/en-us/library/ms174382.aspx
      Create Certificate - For details, refer to http://msdn.microsoft.com/en-us/library/ms187798.aspx
      Create Symmetric Key - For details, refer to http://msdn.microsoft.com/en-us/library/ms188357.aspx

    8. Provide the Certificate Name and Symmetric Key Name in the GUI.
    9. Finally, click Test to ensure that the connection settings are proper and then click Save.

      10. Note: After performing the above steps, navigate to the <AMP Installation Folder>/conf directory and move the masterkey.key file to a secure location. The SQL Server encrypts the data with a hierarchical encryption and key management infrastructure. Each layer encrypts the layer below it by using a combination of certificates, asymmetric keys, and symmetric keys. One among them is the Database Master Key, which in turn is created by the Service Master Key and a Password. This password is stored in Access Manager Plus under the <AMP Installation Folder>/conf directory in a file named masterkey.key. It is highly recommended that you move the masterkey.key file to a secure location. This is to ensure data security. Take care to keep this key safe. You will require it while performing Data Recovery. If you lose this key, you will have to configure MS SQL server setup all over again.

For more details on encryption and key management in MS SQL, refer to this MSDN document http://msdn.microsoft.com/en-us/library/ms189586.aspx.

4. Using MS SQL Cluster as the Backend Database

Click here for steps.

5. Rotating the Encryption Key

Even if you are sure of managing the encryption key securely outside of Access Manager Plus, one of the best practices is to periodically change the encryption key. Access Manager Plus provides an easy option to automatically rotate the encryption key.

5.1 How does the Key Rotation Process Work?

Access Manager Plus will look for the current encryption key present in the file amp_key.key, available in the path specified in the manage_key.conf file, present under the <AMP_HOME>/conf folder. Only if it is present in the specified path, the rotation process will continue. Before rotating the encryption key, Access Manager Plus will take a copy of the entire database. This is to avoid data loss, if anything goes wrong with the rotation process.

During the key rotation process, all passwords and sensitive data will be decrypted first using the current encryption key and subsequently encrypted with the new key. Later, the new key will be written in the amp_key.key file present in the location as specified in the manage_key.conf file. At the end of successful key rotation, Access Manager Plus will write the new encryption key in the same file that contains the old key. If any error occurs while writing the key, the rotation process will be aborted.

5.2 Steps to Rotate the Encryption Key

  1. Ensure that the current encryption key (amp_key.key file) is present in the location as specified in the manage_key.conf file. Also, ensure that Access Manager Plus gets the read/write permission while accessing the amp_key.key file.
  2. Stop the Access Manager Plus server.
  3. Open the command prompt and navigate to <AMP-Installation-Folder>/bin directory. Execute RotateKey.bat (in Windows) or RotateKey.sh (in Linux).
  4. Based on the number of passwords managed and other parameters, the rotation process will take a few minutes to complete.
  5. Start the Access Manager Plus server once you see the confirmation message.

6. Managing the Database Password

  1. Apart from AES encryption, the Access Manager Plus database is secured using a separate password, which is auto-generated and unique for every installation. The password for the database can be stored securely in Access Manager Plus itself. There is also an option to store the password at some other secure location, accessible by the Access Manager Plus server.
  2. By default, the database password is stored under <AMP Installation Folder>/conf/database_params.conf. If you choose to manage the database password by yourself, store the configuration file somewhere securely and instruct the location of the file to Access Manager Plus. Follow the below steps:
    1. If you are starting AMP as service, go to <AMP Installation Folder>/conf/wrapper.conf (in Windows) / <AMP Installation Folder>/conf/wrapper_lin.conf (in Linux) and edit the following entry under Java Additional Parameters
      wrapper.java.additional.9=-Ddatabaseparams.file=<full path of the database_params.conf file location>

    2. If you are starting Access Manager Plus from command line or through the tray icon, you need to edit the file system_properties.conf present in <AMP Installation Folder>/conf directory. In this file, edit the following entry under Splash Screen default Properties
      databaseparams.file=<full path of database_params.conf file>

    3. Note: If you misplace the conf file or lose it, Access Manager Plus will not start. So, take care to save it in a secure location.

7. Updating Web Server Certificates

If you want to use Access Manager Plus web console to update the web server certificates, follow the below steps:

  1. Navigate to Admin >> Server Settings >> Access Manager Plus Server.
  2. In the Access Manager Plus Server page that opens,
    1. Install your keystore file belonging to the SSL certificate and/or change the default Access Manager Plus server port.
    2. To update your SSL certificate, select the type of the keystore file (JKS, PKCS12 or PKCS11) from the Keystore Type drop down menu.
    3. Browse the keystore file from your system and upload it in the Keystore Filename field.
    4. Enter the password of your keystore file in the Keystore Password field.
    5. If you want to change the default Access Manager Plus server port, enter the port number against the Server Port field.
    6. Click Save.
  3. Restart Access Manager Plus after saving the changes.

8. Transferring Installation

If you want to move the Access Manager Plus installation from one machine to another, or to a different location within the same machine, follow the procedure detailed below:

8.1 Prerequisites

Do not remove the existing installation of Access Manager Plus until the new installation works fine. This is to ensure a backup and to overcome any disaster/data corruption during the movement.

8.2 Steps Required

  1. Take a backup of the current database and install Access Manager Plus in the new machine.
  2. Restore the backup data in the new installation.

9. Migrating Database

Click here for steps.

10. Troubleshooting Tip

10.1 The PostgreSQL server is not starting up. What should I do?

Error Scenarios:

  • During Upgrade:

    • 'Trying to start PostgresSQL server failed' error in the command prompt after choosing the PPM file.

  • During Service Start up:
    1. Access Manager Plus service start failure after the upgrade.
    2. Access Manager Plus service start failure after updating the Access Manager Plus service account in Services console.
    For the above two cases, do the following:
    Open the <AMP-HOME>\logs\wrapper file with notepad/Notepad++ and move to the very bottom of the file (i.e. most recent time frame) and check if we get the 'Trying to start PostgresSQL server failed' error.

Possible Causes: 

The following causes are explained with respect to the above error scenarios:

The 'Trying to start PostgresSQL server failed' error occurs when,

  1. Access Manager Plus is unable to access few sub-folders inside Access Manager Plus (i.e appropriate permission not given).
  2. The PostgreSQL DB fails to start because of a background process that was not terminated properly.
  3. The instant DB port might be occupied by a different process.

Solution:

The solution given below applies to all the above error scenarios. To fix this issue, follow the below steps to provide permission,

  1. Start the Task Manager and kill all Postgres process (make sure "show process from all users" is selected - For Access Manager Plus).  
  2. Update the Access Manager Plus service with a privileged account in the services console.
  3. Open command prompt using administrator and execute the below query:
    1. icacls "installation path" /q /c /t /grant Users:F
      • installation path - Provide the Manage_Engine folder location. 
      • Users - Provide the Access Manager Plus service account in the following format:  <DomainName\user name> or <username@domainname>.
      • Example:  icacls "C:\ProgramFiles\ManageEngine\AMP" /q /c /t /grant ManageEngine\svcamp:F
    2. If the key is placed outside the Access Manager Plus folder, kindly provide permission for the key's locations using icacls command.
    3. In the same way, provide full control permission for <AMP>\pgsql\data folder. 
    4. Check the <AMP_Installation_Directory>/pgsql/data folder and ensure if it has inherited that permission.
  4. Navigate to <AMP_Installation_Directory>/pgsql/data and open pg_hba.conf and search NULL. If you find any, remove the entire line that contains NULL.
  5. Rename the logs folder present inside the <AMP_Installation_Directory> as logs.old and create a new folder as logs.
  6. Rename the Patch folder present inside the <AMP_Installation_Directory> as Patch.old and create a new folder as Patch. 
  7. Navigate to <AMP_Installation_Directory>/bin directory and look for files named .lock or lockfile. If present, move both these files to any other directory.
  8. Go to <AMP_Installation_Directory>/pgsql/data directory and look for files named recovery.conf and postmaster.pid. If present, move this file to any other directory.
  9. Now, try to apply the PPM or try starting the service.

If the issue still persists, zip and send us the logs from the <AMP_HOME> and also the <AMP-HOME>\pgsql\data\pg_log folder along with the above screen shots to accessmanagerplus-support@manageengine.com.

 
Top