Authenticating to SugarCRM
To authenticate the provider to SugarCRM, the following must be set to valid SugarCRM user credentials:
- User: The user of the SugarCRM account.
- Password: The password of the SugarCRM account.
Connecting to SugarCRM
Additionally, specify the following to establish a connection to SugarCRM:
- URL: Set this to the URL associated with the SugarCRM account in the form 'http://{sugar crm instance}.com'.
- Platform: If you're encountering a login conflict during authentication, set this to one of the platforms that you have created in the SugarCRM UI.
Note that retrieving SugarCRM metadata can be expensive. It is advised that you store the metadata locally as described in Caching Metadata.
Using OAuth Authentication
SugarCRM uses the OAuth 2.0 authentication standard. It uses the "password" grant type to retrieve the access token, therefore it does NOT open a browser tab during the authentication process. This makes it easy to connect from both a Desktop Application or a Web Application.
You can authenticate with your SugarCRM account using your user-credentials.
Authenticating from an application
After setting the following properties, you are ready to connect:
- User: Set this to the username of the SugarCRM account you're trying to access.
- Password: Set this to the password of the SugarCRM account you're trying to access.
- Url: Set this to the URL of the SugarCRM instance you're trying to access.
In addition to the above 3 properties you can (optionally) specify your own OAuth Consumer Keys to be used during the authentication process. This is done using properties OAuthClientId and OAuthClientSecret. To create a new set of OAuth Consumer Keys you must first be logged in as an admin. After that, follow the below steps:
- Open SugarCRM on your browser and navigate to the Admin Dashboard.
- On the top-right of the site click on your profile and then click on "Admin".
- In the "System" section select "OAuth Keys". Now all your default Consumer Keys will appear.
- On the main navigation bar (on top of the site) find "OAuth Keys" and click the arrow to open the dropdown list.
- Click on "Create OAuth Key".
- Fill the required fields. Set "OAuth Version" to "OAuth 2.0". The values you'll be filling for "Consumer Key" and "Consumer Secret" are your OAuthClientId and OAuthClientSecret, respectively.
- Hit "Save" and your new OAuth Consumer Key will be created.
When you connect the provider the driver automatically:
- Extracts the access token from the response and authenticates requests.
- Refreshes the access token when it expires.
- Saves OAuth values in OAuthSettingsLocation to be persisted across connections.
Persisting OAuth Values
You do not need to reauthenticate when you open a new connection: The provider saves the temporary tokens resulting from the OAuth exchange into OAuthSettingsLocation to be persisted across connections.
This property is also useful if you need to connect with multiple SugarCRM accounts simultaneously, as it enables you to save the authentication values for each in a different file.
Customizing the SSL Configuration
By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.
Connecting Through a Firewall or Proxy
HTTP Proxies
To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.
In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.
Other Proxies
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
- The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.