Product Notices

On this page:

Breaking Changes

This document explains several major changes that impact the Itential platform, especially when upgrading. For steps on how to upgrade your Itential software, see the Upgrade section of the admin guide.

BREAKING CHANGE for maintenance release 2018.3.21

The following are breaking changes for the 2018.3.21 maintenance release.

Important Note

It is the policy of Itential not to cause any breaking changes within the maintenance releases of a major release version; however, at times we have to do so and we extend our sincere apologies when those times occur. In this case, mitigating a security concern drives the need for this breaking change.

Replaced MongoDB Dependency for LocalAAA Adapter

Versions of IAP prior to the 2018.3.21 maintenance release contain a security vulnerability due to the Local AAA adapter's dependency on the MongoDB Node.js driver. Versions of MongoDB prior to 3.1.13 include a security vulnerability (Denial of Service). Consequently, that dependency was replaced with @itential/database, which requires a different set of database properties in the Local AAA service_config. Itential encourages everyone to install this patch to avoid the potential security risk.

The following is an example of the Local AAA service_config with database properties:

json { "id": "Local AAA", "type": "local_aaa", "properties": { "database": { "db": "LocalAAA", "url": "mongodb://", "ssl": { "enabled": true, "sslValidate": true, "sslCA": "/opt/data/mongodb/ssl/mongodb_rootCA.pem", "acceptInvalidCerts": false, "checkServerIdentity": true }, "replSet": { "enabled": true }, "credentials": { "dbAuth": true, "user": "<place_username_here>", "passwd": "<place_password_here" } } }, "brokers": [ "aaa" ] }

How to Configure Your Settings

Use the mongoProps settings from your environment to populate the settings object above within the LocalAAA service. Please note the db parameter must be set to "LocalAAA" as indicated above.

Itential only recommends the use of Local AAA adapter in non-production environments, which should further mitigate the impact of this change.

Breaking Changes in PH Core 6

Although Pronghorn (PH) Core 6.x provides new features, there are several breaking changes you must consider when upgrading the Itential Automation Platform (IAP) from Pronghorn Core 5.x to 6.x.

Node 8 is Required

All existing Pronghorn (Itential Automation Platform) implementations must upgrade to NodeJS 8.

Account, Group & Role APIs Removed/Replaced

The following APIs were removed because they are unable to support the richer Authorization Model in Pronghorn Core 6. With the richer model, the replacements listed are not direct replacements, but the closest analog. Moreover, the replacements do not represent the entirety of the new APIs around authorization structures.

Removed Replacement Notes
GET /config/users GET /accounts
GET /config/user/:user GET /accounts/:accountId
POST /config/user PUT /accounts/:accountId
POST /config/new/user Not Supported
POST /config/delete/user/:user Not Supported
GET /config/groups GET /groups
GET /config/group/:group GET /groups/:groupId
POST /config/group PUT /groups/:groupId Only for PH Groups
POST /config/new/group POST /groups Only for PH Groups
POST /config/delete/group/:group DELETE /groups/:groupId Only for PH Groups
GET /config/roles GET /roles

Note: Creating and deleting users are now functions of the AAA system. No attempt to expose those functions will be made by Pronghorn Core.

/whoAmI Schema Changed

For this schema:

  • groups now contains objects including group id, name, and provenance, which will indicate the AAA provider from which the group is derive, or Pronghorn (IAP) in the case of Pronghorn Groups.
  • roles are now prefixed by app export instead of app name.
  • routes only contains allowed views.

The following non-breaking change was applied:

  • Introduced provenance field, which will indicate the AAA provider from which the user is derived.

Audit Trail getUserObject() Schema Changed

For this schema:

  • groups now contains objects including group id, name, and provenance, which will indicate the AAA provider from which the group is derived, or Pronghorn (IAP) in the case of Pronghorn Groups.

The following non-breaking change was applied:

  • Introduced provenance field, which will indicate the AAA provider from which the user is derived.

Adapter Properties Schema is Required and Provider Properties are Validated at Load Time

For this schema:

  • Adapters must now include a propertiesSchema.json file alongside the pronghorn.json. This file must be a valid JSON schema based on draft-06 or draft-07 and must indicate the JSON Schema version by use of the $schema keyword.
  • Failure to include this will result in the adapter not being loaded, and an error will be printed in the pronghorn logs at startup.
  • Individual Provider properties documents will be validated against the associated Adapter Properties Schema at Provider startup.
  • Any validation failures will be logged and the Provider skipped (not loaded).

Note: Before upgrading, backup Mongo data and your /opt/pronghorn/current/properties.json file.

Corrected Workflow Engine Job Variable Validation

Versions of the Workflow Engine prior to the 2018.3.17 maintenance release contained a job variable validation flaw that prevented the user from being prompted for certain required job variables.

We have corrected this issue and now all required job variables must be supplied when a workflow is started, either from the UI or from the startJobWithOptionsAPI.

If your workflows contain either of the following two scenarios, you will need to correct the workflows before promoting this maintenance release to a production environment.

Please note that each scenario outlined below is now being properly validated.

  1. The first scenario involves two tasks connected by a failure transition.

    Failure Transition

    The first task registers a job variable when the task errors.

    Job Variable registered on Error

    The second task (connected by a failure transition) is attempting to consume the job variable; however, since the task emitted an error instead of a failure, the job variable has never been set.

    Job Variable consumed on the failure path

    Previously, the job would have started and failed if this particular transition were reached. Now that the job variable validation has been corrected, the job will not start without the variable provided as input.

    Workflow Engine Properly Prompts

    To correct this issue, review the transitions between the two tasks and assess the following solutions:

    Transition Solution
    The transition was erroneously built as a failure transition instead of an error transition. Change the transition to an error transition.
    The failure transition is correct and the job variable value should be provided by some other task in the workflow. Identify the task that should provide the job variable value.
    Both the failure transition and the job variable were built correctly. The job variable value will need to be provided by the initiator of the job.
  2. The second scenario involves a task which self-references a job variable in both the input and error screens.

    Error Transition

    The View Data task is consuming the job variable as input.

    Job Variable as input

    The same job variable is produced by the task on the error transition.

    Job Variable as input

    If this job variable is not defined anywhere else in the workflow, the validation should now properly fail and prompt the initiator to provide a value for the variable.

    Job Variable as input

    To correct this issue, review the workflow for usage of this job variable. Identify the task that is meant to produce a value for the variable.

    If no such task exists, use the newVariable task to provide a default value for the variable.