Skip to main content

idapitool

Use the idapitool program for testing API Service (idapi) dynamic-link/shared-object library loading and the login function. If the login succeeds, the program also prints the encrypted login password for further use.

This tool is used to simultaneously change the password of an API profile and generate an AES-encrypted version of it, to use in remote clients.

The Windows executable program is located in the <instance>\lib' directory.

The Unix version is located in the addon/transparent-synch/idapi/ directory of the psunix archive.

Usage
idapitool.exe [option] -psw <password> -user <userID> -url <url>

Argument

Description

-ca <directory—certStore>

On Unix, this is the directory that holds CA certificates, or a file that holds CA certificates to trust.

On Windows, this is the certificate store.

-cert <file[:password]—serialNo>

On Unix, this is the client certificate used for client authentication. The certificate must be in PEM format. The password is optional.

On Windows, this is the serial number of the client certificate used for client authentication.

-ignore

Ignore all server certificate warnings.

-lib <libcurl-path>

For Unix, this is the full path of libcurl, given 0 to disable using the libcurl. This argument suppresses the environment variable HI_CURL_PROV setting if both are given.

-proxy <proxy>

The proxy server to access IDAPI URL.

-proxypass <proxypass>

The user password for proxy server authentication.

-proxyuser <proxyuser>

The user name for proxy server authentication.

-psw <password>

The plain text password of the idapi login user (required)

-q

Quiet mode, prints out the encrypted password only.

-url <url>

The idapi URL. (required)

-user <user>

The idapi login user ID. (required)

Examples

  1. From any client operating system, to test the password for the API user (and get an encrypted version of it), via the SOAP API, if the API endpoint certificate is trusted on the system where idapitool is executed:

    idapitool -psw password -url https://host.domain.com/default/idapi2 -user _API_USER

    The above also works if the API endopoint is not configured for SSL (though such a configuration is not safe, so not recommended).

  2. To retrieve the encrypted password on a Unix/Linux client, for the API user from an instance with the SOAP API configured for SSL, and the endpoint certificate is not trusted:

    idapitool -ca /etc/pki/CA/certs/ -lib /usr/lib/libcurl.so.4 -psw password -url https://host.domain.com/default/idapi2 -user _API_USER

    The above provides:

    • via the -ca argument, an alternative Certificate Authority,

    • via the -lib argument, the direct path to a specific libcurl library for cases where the default libcurl does not work with idapitool.

Troubleshooting notes

  • The URL must be used as seen from the remote API client (either the Bravura Security Fabric server or its Load-Balancer address.)

  • From the remote server the API endpoint has to be accessible and the connection trusted; verify that:

    • The URL is available by opening in a browser the wsdl of that service URL, for example:

      https://server.domain.tld/instancename/idapi/wsdl

    • Or if only command-line interface is available, by calling it with :

      curl -vvI https://server.domain.tld/instancename/idapi

  • The TLS certificate of that URL has to be valid (see digicert.com/help/ ) to check for all types of certificate failure):

    • Check for such failures in the browser's certificate validation: click the icon in the address bar right before the URL > Connection is secure > Certificate is valid .

    • If the certificate is not trusted on the remote server where idapitool is used, the certificate and the cert store it can be found in must also be provided on the idapitool command line.

  • The AES encryption that Bravura Security Fabric uses can change from version to version; the same encryption key must be used both at the server and client.

    If the API client has its own encryption tools use those instead of idapitool, with the plaintext version of the API USER's password.

  • Do not set a password for the default _API_USER that the application UI uses; doing so could break application UI functionality.

    In case you do add a password for that API profile by mistake, use the adm_set tool to remove the existing _API_USER and create a new one with the same name but without a password, and with only local CIDR mask (127.0.0.1/32,::1/128).

  • If the old _API_USER was included in any UserGroups, check if the new one is still added to those groups, or add it back.

  • If the idapitool binary fails and does not report the reason for the failure, check the operating system Event log for the reason.

    • When it runs on a different server (like a Phone Password Manager server), it needs the Encryption files; copy from the Bravura Security Fabric server C:\Program files\Common files\Bravura Security\ all files and directories to the same location on the remote server.

    • The tool can run successfully on Windows only if the server contains a registry key for a Bravura Security Fabric tool, with a COMMKEY value, and the instance.cfg from the instance directory that contains the lib\ directory where idapitool runs, points to that registry key.

In this section: