Unknown platforms to be restricted in Winter '18 release

In Sugar 8 / Spring '18, Sugar administrators can now configure API platforms using the Administration panel. The Platform extension is still available if you want to register a custom API platform as part of a Module Loadable Package.

Sugar uses platforms to support the needs of multiple Sugar clients.  The Sugar REST API uses the platform parameter to indicate which platform is being used.  If you’d like a refresher on what the platform parameter is and how to use it, check out this blog post.  In Sugar 7.9, we added a new Platform extension that we advised developers to start using in the Sugar 7.9 Migration Guide.  The Platform extension allows you to indicate a particular custom platform should be allowed when the disable_unknown_platforms configuration setting is on.

Changes coming in Winter '18 release

In the Winter '18 release, we will be preventing REST API access to Sugar from unknown platform types. Sugar has a configuration setting disable_unknown_platforms that controls whether or not unregistered platforms are allowed to be used when logging in using the REST API. The current default value for disable_unknown_platforms is false. In the Winter '18 release, we will be changing the default to true, which is how it is already reflected in the documentation. If your integration uses a custom platform, this custom platform will need to be registered in each Sugar instance or your integration will break!

How do I know if I'm affected? New

In order to avoid conflicting with end-user sessions, some REST API integrations specify a different “platform” during login. Developers have often employed this technique to prevent integrations from interrupting or conflicting with active end-user sessions.

Below is an example of a login request that uses a custom platform:

POST /rest/v10/oauth2/token
{
  "grant_type":"password",
  "client_id":"sugar",
  "client_secret":"",
  "username":"{{username}}",
  "password":"{{password}}",
  "platform":"<SOME VALUE>"
}

Registering a new platform for an integration

Integrations must register any custom platforms they plan to use. For compatibility with Sugar On-Demand, we recommend creating a Module Loadable package that includes a simple Platform extension.

./custom/Extension/application/Ext/Platforms/<integration name>.php

<?php

/*

* A valid platform name requires:

* - Max length of 127 characters

* - Valid characters are: a-z, A-Z, 0-9 - (hypen) _ (underscore)

*/


$platforms[] = '<integration platform name>';

We recognize that is a change in assumption since it involves an installation of a package where previously no package had to be installed at all. We are working on an alternative approach as we roll out additional Identity Management (IdM) functionality that would allow for more convenient configuration of integrations.

Example Module Loadable Package

An example module loadable package has been added to the UnCon github repository. This package can be used as a template for those needing help understanding how to construct a package that will enable their API integration.

https://github.com/sugarcrm/uncon/tree/2017/custom-platform

  • They removed the ability to install modules in SugarCRM trials. Only way to test now is to have a partner account and request a demo instance.

    We'd love to have the ability to install modules again in trial instances though. It's a lot easier on the end-customer to see how add-ons and integrations work with their test data. It let's them play with the customizations on their own time as they are looking at which CRM they want to go with. I'd guess there's a much higher chance they'll stick with Sugar if they can use their trials like this. 

  • I have a question if there is option to upload plugin with custom platform name configuration into trial account (to test if it works well)?

    I see a notice 'New uploads for Module Loader are disabled. Installable modules are restricted to the modules pre-loaded below.' when I enter to Developers Tools ->  Module Loader. 

    In the article there is information 'We are working on an alternative approach as we roll out additional Identity Management (IdM) functionality that would allow for more convenient configuration of integrations.'

    Do you have some estimates when these improvements will be available for end users? Could you provide some details how this will work ?

  • Unfortunately, we don't have a way to view the custom platforms that are registered through the Admin page or an API call.  If the custom platform has been registered, the file that sets the platform will be located at sugardirectory/custom/Extension/application/Ext/Platforms/profm.php.  The other thing you can do is set disable_unknown_platformsto true and then try to authenticate using the custom platform.

    POST /rest/v10/oauth2/token
    {
      "grant_type":"password",
      "client_id":"sugar",
      "client_secret":"",
      "username":"{{username}}",
      "password":"{{password}}",
      "platform":"<SOME VALUE>"
    }

     

  • Unfortunately, we don't have a great way for you to see what custom platforms are being used in On-Demand instances.  We recommend you contact the people who wrote any customizations you have installed in your On-Demand instance so they can check if they are using custom platforms in their customizations.

  • Is there a way to view which platforms are added to a Sugar instance?

    Ex. I just installed a module that has a custom platform, I want to be able to go somewhere on the Administration page and confirm it was added correctly (or via an API call).

    Is there a way to do this?