PingIntelligence

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.

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

    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.

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 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  <your_CA_cerficate.crt>  -inkey  <your_certificate_key.key>  -out abs.p12 -name  <alias_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 <your_CA_certificate>.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 <alias_name> -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:

        $ ../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