--- title: API Publish Service description: The API Publish Service publishes the changes made to the discovered APIs from the PingIntelligence Dashboard to the AI engine. component: pingintelligence version: 5.2 page_id: pingintelligence:installing_pingintelligence_for_apis:pingintelligence_api_publish_service canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/installing_pingintelligence_for_apis/pingintelligence_api_publish_service.html revdate: April 3, 2024 section_ids: about-this-task: About this task installing-the-api-publish-service: Installing the API Publish Service before-you-begin: Before you begin about-this-task-2: About this task steps: Steps choose-from: Choose from: example-tar-zxvf-pi-api-abs-5-1-tar-gz: Example:# tar –zxvf pi-api-abs-5.1.tar.gz default-settings: Default settings obfuscating-passwords: Obfuscating passwords before-you-begin-2: Before you begin about-this-task-3: About this task steps-2: Steps next-steps: Next steps importing-existing-ca-signed-certificates: Importing existing CA-signed certificates before-you-begin-3: Before you begin about-this-task-4: About this task steps-3: Steps example: Example: example-2: Example: starting-and-stopping-the-api-publish-service: Starting and stopping the API Publish Service before-you-begin-4: Before you begin about-this-task-5: About this task steps-4: Steps choose-from-2: Choose from: choose-from-3: Choose from: --- # API Publish Service The API Publish Service publishes the changes made to the discovered APIs from the PingIntelligence Dashboard to the AI engine. ## About this task Complete the following steps to install the API Publish Service in your environment. ## Installing the API Publish Service Install the API Publish Service. ### Before you begin Before installing the API Publish Service: * Install OpenJDK 11.0.2 on a 64-bit architecture machine. To verify the Java version, run the following command: ``` # java -version ``` * Verify the supported operating systems.PingIntelligence supports RHEL 7.9 and Ubuntu 18.04 LTS. ### About this task You can install the API Publish Service as a root user or as a non-root user. The installation path in the steps below assumes that you are root user. The installation works in a similar way for a non-root user. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The download site has a link to the consolidated build for ABS and API Publish. When extracting the tar in the `pingidentity` folder, there will be two folders:- `abs` - `apipublish` | ### Steps 1. Go to the [Ping Identity Product Downloads site](https://www.pingidentity.com/en/resources/downloads.html). 2. Under PingIntelligence for APIs, click **View Now**. 3. Click **Download** under **PingIntelligence for APIs Software**. 4. Under **Download AI Engine and Tools**, click **AI Engine 5.1.0.1**. 5. After downloading: #### Choose from: * If you are installing as a root user, copy the build file to the `/opt` directory. * If you are installing as a non-root user, choose any other location. 6. At the command prompt, enter `# tar –zxvf .` #### Example:`# tar –zxvf pi-api-abs-5.1.tar.gz` ## Default settings The API Publish configuration file (`apipublish.properties`) is located in the `/pingidentity/apipublish/config/` directory. The following table explains the parameters and provides recommended values. You can change the default values based on your requirements. | Parameter | Description | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pi.apipublish.ssl.enabled-protocols` | The supported SSL protocols. The default value is `TLSv1.2`. | | `pi.apipublish.ssl.ciphers` | The supported `.ssl` ciphers. For the list of valid cipher names, see .oracle.com/en/java/javase/11/docs/specs/security/standard-names.html//\[]. For multiple cipher names, use a comma to separate names in the list. For example: `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384`,`TLS_DHE_RSA_WITH_AES_256_CBC_SHA256`. | | `pi.apipublish.ssl.key-store` | The directory path of the key store. The default value is `config/ssl/apipublish.jks`. | | `pi.apipublish.ssl.key-store-type` | The key store type. The default value is `JKS`. | | `pi.apipublish.ssl.key-store-password` | The password of the JKS key store. PingIntelligence ships with a default obfuscated password. You can reset the password and obfuscate it. | | `pi.apipublish.ssl.key-alias` | Alias for the SSL key. The default value is `pingidentity`. | | `pi.apipublish.server.port` | Port for the API Publish Service and PingIntelligence Dashboard communication. The default value is `8050`. | | `pi.apipublish.server.timezone` | Set the time zone to `utc` or `local`. The default timezone is `utc`. | | `pi.apipublish.server.deployment_type` | The API Publish Service deployment mode. Valid values are `cloud` or `onprem`. The default value is `onprem`. | | `pi.apipublish.datasource.data_dbname` | The MongoDB data database name. The default value is `abs_data`. | | `pi.apipublish.datasource.metadata_dbname` | The MongoDB metadata database name.The default value is `abs_metadata`. | | `pi.apipublish.datasource.mongo_rs` | Comma separated MongoDB replica set URI. | | `pi.apipublish.datasource.mongo_ssl` | Set to `true` if MongoDB is configured to use SSL connections. The default value is `false`. | | `pi.apipublish.datasource.mongo_auth_mechanism` | Defines the method in which MongoDB authenticates. The possible values are:- `NONE`: Set to `NONE` if authentication is not configured in MongoDB. - `DEFAULT`: Set to `DEFAULT` if you want to use a native MongoDB username and password. Provide the values in the next two variables. - `PLAIN`: Set to `PLAIN` if you want to use LDAP authentication. In this case, provide the LDAP username and password in the next two variables. | | `pi.apipublish.datasource.mongo_certificate` | Set to true if you want to verify MongoDB SSL server certificate when the API Publish Service connects to MongoDB. The default value is `false`. Make sure pi.apipublishservice.datasource.mongo\_ssl is set to true before setting pi.apipublishservice.datasource.mongo\_certificate to true. | | `pi.apipublish.datasource.username` | MongoDB username. The default value is `absuser`. | | `pi.apipublish.datasource.password` | MongoDB password. The default value is `abs123`. | ## Obfuscating passwords Using the command line interface (CLI), you can obfuscate the keys and passwords configured in `apipublish.properties`. ### Before you begin ### About this task The API Publish Service is shipped with a default `apipublish_master.key`, which is used to obfuscate the various keys and passwords. It is recommended to generate your own `apipublish_master.key`. A default `jks_password` is configured in the `apipublish.properties` file. The following keys and passwords are obfuscated: * `mongo_password` * `jks_password` | | | | - | ------------------------------------------------------------------------------------------------ | | | During the process of obfuscation of keys and password, the API Publish Service must be stopped. | The following diagram summarizes the obfuscation process. ![A diagram of the API Publish Service obfuscation flow.](../_images/vxw1636544066014.png) ### Steps 1. To generate the `apipublish_master.key`, run the `generate_obfkey` command in the CLI: ``` /pingidentity/apipublish/bin/cli.sh generate_obfkey -u admin -p admin ``` The new `apipublish_master.key` is used to obfuscate the passwords in `apipublish.properties` file. 2. Enter the keys and passwords in clear text in the `apipublish.properties` file. 3. Run the `obfuscate_keys` command to obfuscate keys and passwords: ``` /pingidentity/apipublish/bin/cli.sh obfuscate_keys -u admin -p admin ``` 4. After the passwords are obfuscated, start the API Publish Service. ### Next steps | | | | - | ------------------------------------------------------------------------------------------------------------ | | | After the keys and passwords are obfuscated, the `apipublish_master.key` must be moved to a secure location. | ## Importing existing CA-signed certificates Import existing CA-signed certificates. ### Before you begin To import the certificate authority (CA)-signed certificate, stop the API Publish Service if it is already running. ### About this task You can import your existing CA-signed certificate in the API Publish Service. Complete the following steps to import the CA-signed certificate. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The API Publish Service is shipped with a default self-signed certificate with the Java key store at `/config/ssl/apipublish.jks`. The default password is set in the `apipublish.properties` file. The default password is obfuscated in the file. It is recommended to change the default passwords and obfuscate the new passwords. See [Obfuscating passwords](pingintelligence_api_publish_service_obfuscating_passwords.html) for steps to obfuscate passwords. | ### Steps 1. Export your CA-signed certificate to the PKCS12 store by entering the following command: ``` # openssl pkcs12 -export -in -inkey -out abs.p12 -name ``` #### Example: ``` # openssl pkcs12 -export -in ping.crt -inkey ping.key -out abs.p12 -name exampleCAcertificate Enter Export Password: Verifying - Enter Export Password: ``` | | | | - | ------------------------------------------------------------------------------------------------------------------- | | | If you have an intermediate certificate from a CA, then append the content to the `.crt` file. | 2. Import the certificate and key from the PKCS12 store to the Java key store by entering the command below. ``` # keytool -importkeystore -destkeystore apipublish.jks -srckeystore abs.p12 -srcstoretype PKCS12 -alias -storetype jks ``` The command requires the destination key store password. The destination key store password entered in the command should be same that is configured in the `apipublish.properties` file. The following is a snippet of the `apipublish.properties` file where the destination key store password is stored. The password is obfuscated. ``` # Java Keystore password jks_password=OBF:AES:Q3vcrnj7VZILTPdJnxkOsyimHRvGDQ==:daYWJ5QgzxZJAnTkuRlFpreM1rsz3FFCulhAUKj7ww4= ``` #### Example: ``` # keytool -importkeystore -destkeystore apipublish.jks -srckeystore abs.p12 -srcstoretype PKCS12 -alias exampleCAcertificate -storetype jks Importing keystore apipublish.p12 to abs.jks... Enter destination keystore password: Re-enter new password: Enter source keystore password: ``` 3. Copy the `apipublish.jks` file created in step 2 to `/config/ssl` directory. 4. Start the API Publish Service by running the following command: ``` # ./bin/start.sh ``` ## Starting and stopping the API Publish Service Start and stop the API Publish Service. ### Before you begin For the API Publish Service to start, the `apipublish_master.key` must be present in the `apipublish/config` directory. If you have moved the master key to a secured location for security reasons, copy it to the `config` directory before starting the service. ### About this task You can start the API Publish Service in one of the following two ways: * Using a service script available in the `bin` directory * Using the `start.sh` script available in the `bin` directory ### Steps 1. Start API Publish. #### Choose from: * To start API Publish as a service: 1. Navigate to the `bin` directory and run the following command to install API Publish as a service: ``` #sudo ./install-systemctl-service.sh pi-apipublish ``` 2. Start the service by entering the following command: ``` systemctl start pi-apipublish.service ``` * To start API Publish using the `start.sh` script: 1. Run the `start.sh` script located in the `/pingidentity/apipublish/bin` directory: ```shell $ ../bin/start.sh ``` 2. Stop API Publish. #### Choose from: * To stop API Publish using a service script: 1. Run the following command to stop the API Publish Service: ``` systemctl stop pi-apipublish.service ``` * To stop API Publish using the `stop.sh` script: 1. Run the `stop.sh` script available in the `bin` directory: ``` # ../bin/stop.sh ```