Cerb (9.1) is a feature upgrade released on December 27, 2018. It includes more than 73 new features and improvements from community feedback.

• Important Release Notes
• Connected Services
  • Service Providers
    • Amazon Web Services
    • Cerb API (Legacy Signatures)
    • Facebook Pages
    • HTTP Basic Authentication
    • LDAP
    • OAuth1
    • OAuth2
    • OpenID Connect
    • SAML
    • Token Bearer
• Security
  • Single Sign-On (SSO) Integration
    • Single-click SSO options on the login form
    • Multiple LDAP providers for SSO
  • Multi-Factor Authentication (MFA)
    • Require MFA per worker
    • Remember trusted devices
    • Enforce passwordless logins for SSO
  • Simplified logins
    • Default page after login
  • Minimum password length
  • Simplified account invites
  • Hardened account recovery
• API
  • OAuth2 authentication in the API
  • Custom scopes for OAuth2 apps
• Geolocation
  • Geolocation custom fields
  • Geolocation data queries
  • Map widgets for visualizing geolocation data
• Custom Fields
  • Add new custom field types with plugins
• Dashboards
  • Simplified dashboard-wide filters
• Profiles
  • Simplified tab management on profile pages
• Bots
  • Scripting
    • Improved the usability of single-record searches
    • Improved empty placeholders tests
• Records
  • Improved usability on the worker editor
  • Automatically add empty fieldsets to tickets
• Platform
  • Requirements
  • Dependencies
  • Plugin Developers
• Retired Plugins

Important Release Notes

• Always make a backup before upgrading!

• Cerb 9.1 requires PHP 7.0+ and MySQL 5.6+.

• Cerb now requires the yaml PHP extension.

• To upgrade your installation, follow these instructions.

Connected Services

Connected services introduce a new layer of integration for connected accounts.

Previously, connected accounts were their own service providers. For instance, a Twitter-based connected account knew how to connect to their API, authenticate, etc. Each connected account was self-contained.

This was simple to use, but it led to several disadvantages:

• Most integrations were limited to a single instance of each service. While you could have multiple Twitter or Facebook accounts, they had to authenticate against the same ‘client’ application registered at those services. This caused problems for teams that support multiple brands; or during mergers/acquisitions when multiple implementations were in use.

• New connected account service providers had to be added using plugins. There are thousands of APIs to integrate with and creating/managing those plugins became untenable.

• For OAuth2-based services (the vast majority), the requested “scopes” (permissions for the application) were often hardcoded by each plugin and were shared across all of its connected accounts. This made it difficult to integrate with APIs like Google where dozens of services each has its own scopes. This would require one plugin for Google Maps, another for Google Translate, another for Google Calendar, etc.

• Services were configured in multiple places – on the connected account, in Setup » Services, etc.

• Some services didn’t need connected accounts at all. For instance, a SAML-based identity provider can be configured by admins and used directly without any connected accounts being created. Adding these options to the connected accounts list made things more confusing.

Now, each connected account has a service provider as a distinct parent record. This cleanly allows multiple integrations with the same service, and new services can be added entirely through the browser without the use of plugins. Certain services, like identity providers, can be used directly as connected services and don’t show up when creating connected accounts.

Service providers themselves are based on reusable “types” to minimize the need for future plugins. For instance, you can now integrate with any OAuth-based service by picking that type and providing a few details. You have full control of the “scopes” that your bot behavior will request when connected accounts are created for that service. We can share connected service records as importable packages rather than plugins.

This improvement has allowed us to retire many plugins. Their data/functionality has automatically been migrated to connected service records.

Service Providers

We’ve included a wide variety of service provider types.

Amazon Web Services

The Amazon Web Services service provider enables connected accounts to use AWS API signatures for authentication.

Cerb API (Legacy Signatures)

The Cerb API (Legacy Signatures) service provider enables accounts to connect to Cerb instances using older-style API signatures. We recommend using OAuth2 for authentication going forward.

Facebook Pages

The Facebook Pages service provider enables connected accounts to use a time-limited Page token for API authentication while automatically refreshing the token from an existing Facebook connected account. This removes the need to refresh each page token separately.

HTTP Basic Authentication

The HTTP Basic Authentication service provider enables connected accounts to use HTTP Basic authentication for any external API (e.g. Twilio, Stripe, JIRA). This secures the username and password rather than including them directly in bot behaviors.

LDAP

The LDAP service provider enables workers to log in using authentication details from a corporate directory. This functionality is now built in and the LDAP plugin has been retired. Existing LDAP configurations are automatically migrated to new connected service records.

OAuth1

The OAuth1 service provider enables connected accounts to use OAuth 1.0a to authenticate against any external API (e.g. Twitter, Freshbooks).

OAuth2

The OAuth2 service provider enables connected accounts to use OAuth2 to authenticate against any external API (e.g. Slack, GitHub). [#309]

OpenID Connect

The OpenID Connect (OIDC) service provider enables workers to log in using an existing identity at any OIDC-enabled provider (e.g. AWS Cognito, G Suite, Salesforce). OpenID Connect providers can be configured as “one-click” single sign-on (SSO) methods in the login form. When configuring an OIDC service, auto-discovery by issuer URL and JSON Web Keys (JWKS) are supported.

SAML

The SAML (Security Assertion Markup Language) service provider enables SSO (single sign-on) functionality using any SAML2-compatible Identity Provider (IdP); G Suite, Salesforce, etc. [#820]

Token Bearer

The Token Bearer service provider allows connected accounts to authenticate against any API that uses bearer tokens (e.g. HipChat).

Security

Single Sign-On (SSO) Integration

The improvements to connected services have made it much simpler to implement Single sign-on (SSO) functionality for authenticating worker logins.

This enables authentication from an existing identity provider (IdP) with SAML2, OpenID Connect, or LDAP.

New SSO providers can be added through connected services without requiring plugins.

Single-click SSO options on the login form

SSO providers can now be configured from Setup » Security » Authentication.

These options are displayed as buttons on the login page above the email/password form, enabling a single-click login when a worker has an existing session at the identity provider (e.g. G Suite, Salesforce, AWS Cognito).

This change also makes it possible to implement auto-provisioning for new workers in a future update based on an existing corporate directory. This is particularly useful for environments with 100+ workers.

Multiple LDAP providers for SSO

Multiple LDAP providers may now be configured to authenticate worker logins. [#85]

Multi-Factor Authentication (MFA)

Multi-Factor Authentication (MFA) is now built-in to the standard login process. Previously this required the ‘Two-Factor Authentication’ plugin which prompted for a security code and email/password at the same time.

In the new process, a worker authenticates first (e.g. password, SSO, LDAP) and then is prompted for a one-time security code from an authorized device (like their mobile phone). This improves security by requiring a malicious party to know someone’s password as well as having physical access to one of their devices.

This also improves the user experience when using a password manager (e.g. 1Password), as the temporary security code is automatically copied to the clipboard after authenticating.

Require MFA per worker

MFA may now be required or optional for each worker account. This can be quickly configured by admins by using the ‘bulk update’ feature on a worker worklist.

When MFA is optional, workers may enable/disable it from the Settings » Security tab on their profile.

If MFA is required and is not set up, a worker is prompted to configure it on their next login before proceeding.

Remember trusted devices

When using multi-factor authentication for worker logins, a worker can enable ‘Remember this device’ to avoid having to answer subsequent MFA challenges for a certain period.

This improves the usability of MFA for daily workers, which makes it more likely to be used. The challenge is still enforced for any unfamiliar devices.

This functionality can be enabled/disabled by admins in Setup » Security » Authentication. Admins can also configure the “remember” duration from 0-60 days.

Enforce passwordless logins for SSO

On worker records, password-based authentication can be disabled to force logins using a SSO (single sign-on) identity provider. This can be enabled per-worker.

Simplified logins

The initial /login page now prompts for email address and password in a single form again.

Previously, the email field was asked first in order to determine the appropriate authentication method per-worker. This is now better handled with single sign-on (SSO) functionality.

Additionally, this approach leaks less information about valid accounts to an attacker.

Default page after login

After a worker logs in, they are now redirected to their default page rather than their profile.

Minimum password length

Worker passwords must now be at least 8 characters in length. Ideally they should be much longer, random, and in a password manager.

Simplified account invites

When creating a new worker account, or re-enabling password access on an existing worker, an invite URL is sent to their email address. The URL contains a long, time-limited token. When clicked, the link will prompt the worker to create a password.

If multi-factor authentication or security questions exist on their account they’ll be prompted to verify their identity first.

Hardened account recovery

During a worker login, when recovering an account (i.e. forgot password), multi-factor authentication (MFA) is now required when enabled.

Without MFA, a worker’s secret questions are used to verify their identity instead.

If a worker forgets their password and loses their MFA device, an admin can disable and re-enable MFA on their account to reset it.

API

OAuth2 authentication in the API

The Cerb API can now be accessed using industry-standard OAuth2 Bearer tokens in the ‘Authorization:’ header rather than request signatures. [#310] This simplifies integrations and allows the use many OAuth-based client libraries and development/testing tools. The legacy request signatures are also still supported for backwards compatibility, but may be deprecated in a future update.

Admins can create new ‘OAuth App’ records to generate a client id/secret for third-party tools and services to use.

When a worker connects to their account from a third-party service, Cerb will first authenticate them, and then request consent for the app’s requested scopes (permissions).

Successful authentication returns a short-lived ‘access token’ and a longer-lived ‘refresh token’. The access token is sent with each subsequent request. The refresh token can be used to request a new access token without re-authenticating the worker.

Currently only the three-legged authorization_code grant type of OAuth2 is supported, but other grant types (e.g. client_credentials) will follow shortly.

Custom scopes for OAuth2 apps

When configuring OAuth2 Apps for use with the API, each app may define (in YAML) its own ‘scopes’ to control the available API endpoints. Additionally, each endpoint may include allowed verbs (e.g. GET/POST/PUT/DELETE). [#838]

This makes it easy to offer read-only scopes to applications that don’t need to modify data (e.g. knowledgebase search).

When creating credentials for a new OAuth App, a default scopes policy is provided.

Geolocation

Geolocation custom fields

Added a new ‘Geo: Latitude/Longitude’ custom field type. This stores geographical coordinates for plotting points of interest (POIs) on maps. [#808]

In this near future, this functionality will also support proximity searches, etc.

Geolocation data queries

Added type:worklist.geo.points data queries for retrieving records based on a latitude/longitude field. This is used to plot data on map widgets.

See Data Queries: Worklist Geo Points in the documentation.

Map widgets for visualizing geolocation data

Added “Map: Geo Points” widgets to profile and workspace dashboards. These take a geo-based data query and plot coordinates on a map.

Currently these support U.S. (States) and World (Countries) variations, with more options on the way.

Custom Fields

Add new custom field types with plugins

New custom field types can be implemented in plugins using the cerb.custom_field extension point. [#488]

Previously, custom field types were built-in.

This improvement will allow us to implement a lot of custom field based feature requests while avoiding feature bloat.

Dashboards

Simplified dashboard-wide filters

On workspace dashboards, the ‘Prompted placeholders’ feature now uses YAML rather than JSON to describe the fields. This is more human-readable than JSON while still retaining structure. Existing dashboards have been automatically migrated to the new format.

Profiles

Simplified tab management on profile pages

Profile tabs are now much easier to add and manage.

Previously this was handled with a chooser. It wasn’t immediately obvious how to add new tabs, or that they could be dragged into a specific order.

Now there’s simply a list of available tabs, with checkboxes and drag handles.

There’s also an obvious ‘Add’ button above the list to create new tabs.

Bots

Scripting

Improved the usability of single-record searches

In bot behaviors, when using the records API to search, adding limit:1 to the search query directly returns a single record object rather than an array containing one record.

Previously an array was always returned, which tediously required a filter like {{results|first}} or a second placeholder.

Improved empty placeholders tests

In bot scripting, fixed an issue where lazy-loaded placeholders failed the defined and empty tests. This led to unexpected behavior on filters like |default.

Records

Improved usability on the worker editor

On worker editor popups, the previously long form is now divided into more manageable sections: Profile, Groups, Authentication, Localization, and Availability.

Automatically add empty fieldsets to tickets

Using the records API, empty custom fieldsets can be added to ticket records with the fieldsets key. The value is either a comma-delimited string or an array of fieldset IDs.

This allows fieldsets to be attached to records before any values are set.

People use this to optimize common workflows; without requiring workers to manually add fieldsets for every new ticket. [#813]

This functionality will be expanded to all record types in a near future update.

Platform

Requirements

• The PHP yaml extension is now required. This is a more human-friendly format than JSON when directly input by end-users.

Dependencies

• Added guzzlehttp/guzzle for PSR-7 compliant HTTP requests and responses. This allows Cerb to interoperate much more easily with other PSR-7 HTTP middleware (e.g. OAuth). This will replace all direct usage of cURL throughout the code.

• Added league/oauth2-client for the OAuth2 service provider.

• Added league/oauth2-server for accepting OAuth2 bearer tokens in the API.

• Added onelogin/php-saml for SAML service providers.

• Added phpseclib/phpseclib for converting JSON Web Keys (JWKS) to RSA public keys for OpenID Connect integration.

Plugin Developers

• Added a DevblocksPlatform::parseGeoPointString() utility. This parses geolocation points (latitude/longitude) in various formats and returns an array with latitude and longitude keys.

• Added an http service to Devblocks. This handles the creation of PSR-7 compliant HTTP requests, defaults, registration of HTTP middleware, execution of HTTP requests, and special handling of HTTP responses. It is accessed from DevblocksPlatform::services()->http(). This should replace all direct usage of cURL.

• In the validation service, a $validation->validateAll($values,&$error) helper is now available for validating arbitrary values (e.g. configuration forms). Previously, validation was only used by record editor popups.

Retired Plugins

Due to recent improvements in the platform, many plugins have become unnecessary and have been retired. Their data is automatically migrated to newer features.

• The Asset management plugin has been retired. Asset record data is migrated to a custom record of the same name.

• The Api.ai plugin has been retired. This service was rebranded as Dialogflow.

• The Amazon Web Services plugin has been retired. Connected accounts are automatically migrated to a new AWS service provider.

• The Campfire plugin has been retired. This service has been merged into Basecamp 3.

• The Clickatell plugin has been retired. Connected accounts and bot actions are automatically migrated to a token-bearer service provider.

• The Dropbox plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Facebook plugin has been retired. Connected accounts and bot actions are automatically migrated to OAuth2 and Facebook Pages service providers.

• The Freshbooks plugin has been retired. Connected accounts are automatically migrated to an OAuth1 service provider.

• The GitHub plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The GitLab plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Google plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The HipChat plugin has been retired. Plugin settings and bot actions are automatically migrated to a token-bearer connected account. HipChat was acquired by Slack, and accounts will transition after February 15, 2019.

• The LinkedIn plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Nest plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The OpenID plugin has been retired. Any OpenID Connect (OIDC) provider can be used now.

• The Salesforce plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Shiftplanning plugin has been retired. The service is now called Humanity and their API supports OAuth2 rather than API keys.

• The Slack plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Spotify plugin has been retired. Connected accounts are automatically migrated to an OAuth2 service provider.

• The Stripe plugin has been retired. Connected accounts are automatically migrated to an HTTP Basic Auth service provider.

• The Twilio plugin has been retired. Connected accounts are automatically migrated to an HTTP Basic Auth service provider.

• The Two-Factor Authentication plugin has been retired. Multi-factor authentication is now built into Cerb for all authentication methods (e.g. password, LDAP, SSO). Existing two-factor configuration on worker accounts is automatically migrated to the new format.

• Retired Extension_LoginAuthenticator extensions. The disparate functionality like SSO (single sign-on), LDAP, and multi-factor authentication has been unified in the core login system. New SSO providers can be implemented with connected services.