Authentication

#Credentials There are 6 request arguments that are needed to authenticate to a Sugar 7 REST API via the oauth2/token endpoint. However with the SugarCRM REST PHP Client, only 5 are needed to be configured since the the grant_type is specific to the current OAuth 2.0 action.

The SugarAPI Client is pre-configured with the following credentials.

array(
   'client_id' => 'sugar',
   'client_secret' => '',
   'platform' => 'api',
   'username' => '',
   'password' => ''
)

Although it is pre-configured with a client_id of 'sugar' and client_secret of '', and these will work for any Sugar 7 application instance, it is recommended that you create new OAuth 2.0 Keys as outlined in the SugarCRM documentation.

The SugarAPI Client is also setup so that the setCredentials() method does not overwrite the credentials stored on the Client, but instead merges the credentials array passed into the method, with the currently configured. This is outlined in the Client architecture overview, however the following code example showcases the usage.

To set the credentials on the SugarAPI Client you can use the following methods:

1. Provide credentials on instantiation

$server = 'localhost';
$credentials = array(
        'username' => 'admin'
        'password' => 'password'
);
$SugarClient = new SugarAPI\SDK\SugarAPI($server,$credentials);

2. Provide credentials via setCredentials()

$server = 'localhost';
$credentials = array(
        'username' => 'admin'
        'password' => 'password'
);
$SugarClient = new SugarAPI\SDK\SugarAPI($server);
$SugarClient->setCredentials($credentials);

Both methods shown above will result in the same Client configuration. The following code, will output the current authentication credentials on the SugarAPI Client, and for both examples reveal the same settings.

$credentials = $SugarClient->getCredentials();
print_r($credentials);

Output

Array (
    'client_id' => 'sugar',
    'client_secret' => '',
    'platform' => 'api',
    'username' => 'admin',
    'password' => 'password'
)

#Authentication There are three main methods on the SugarAPI Client for managing the authentication to the Sugar REST API.

##Login Once the authentication credentials are configured on the SugarAPI Client, you can use the login() method to authenticate the Sugar REST API.

try{
    if ($SugarClient->login()){
        //do stuff
    }
}catch(SugarAPI\SDK\Exception\Authentication\AuthenticationException $ex){
    //catch authentication error
    print $ex->getMessage();
}

The login() method utilizes the OAuth2Token Endpoint and if successful authentication occurs with the Sugar REST API, stores the authentication token on the Client. Please review the Token Management section to understand how the Client utilizes the token and understands if the Client is still authenticated.

Please note, since authentication is crucial to usage of the Sugar REST PHP Client an Exception will be thrown on failure of the OAuth Request. The above example illustrates the recommended usage of a try-catch block, to handle any authentication exception that might occur.

##Refresh Token When using the SugarAPI Client in your code, you may need to refresh the OAuth Token being used, so the client can continue use other Endpoints. Use the refreshToken() method on the SugarAPI Client to refresh the authentication token.

try{
    if ($SugarClient->refreshToken()){
        //do stuff
    }
}catch(SugarAPI\SDK\Exception\Authentication\AuthenticationException $ex){
    //catch authentication error
    print $ex->getMessage();
}

The refreshToken() method utilizes the OAuth2Refresh Endpoint and if successful authentication occurs with the Sugar REST API, the Token on the Client is updated to reflect the new authentication token.

##Logout Lastly when finished with the SugarAPI Client in your code, you can use the logout() method on the Client to clear the current token, and let the Sugar application know you are logged out.

try{
    if ($SugarClient->logout()){
        //do stuff
    }
}catch(SugarAPI\SDK\Exception\Authentication\AuthenticationException $ex){
    //catch authentication error
    print $ex->getMessage();
}

The logout() method utilizes the OAuth2Logout Endpoint and if successful logout occurs with the Sugar REST API, the Token on the Client is set to NULL and removed from storage.

#Token Management ##Authentication Token The oauth2/token REST API Endpoint, returns the following data on successful login:

{
   "access_token":"802b64c0-5eac-8431-a541-5342d38ac527",
   "expires_in":3600,
   "token_type":"bearer",
   "scope":null,
   "refresh_token":"85053198-24b1-4521-b1a1-5342d382e0b7",
   "refresh_expires_in":1209600,
   "download_token":"8c9b5461-0d95-8d87-6084-5342d357b39e"
}

After successful authentication via the login() method, as mentioned above, this returned data is converted to a \StdClass Object and set on the Client as the $token property. When it is set on the Client, two extra pieces of data are added to the Token Object:

1. expiration

• This is calculated based on the 'expires_in' property that is returned during login

2. refresh_expiration

• This is calculated based on the 'refresh_expires_in' property that is returned during login

Once the Token is set on the Client it can be retrieved via the getToken() method as follows:

$SugarAPI = new \SugarAPI\SDK\SugarAPI($server,$credentials);
$SugarAPI->login();
$Token = $SugarAPI->getToken();

Once you have retrieved the Token, you can view the calculated expiration data as follows:

print date('Y-m-d h:i:s',$Token->expiration);
print date('Y-m-d h:i:s',$Token->refresh_expiration);

##Check Authentication It is not entirely necessary to retrieve the token to view the expiration data, however. The Sugar REST PHP Client also provides an easy method to determine if the Client is still authenticated based on the calculated expiration properties.

You can use the authenticated() method to determine if the Client still has a valid authentication token.

$SugarAPI = new \SugarAPI\SDK\SugarAPI($server,$credentials);
if ($SugarAPI->authenticated()){
    //token is still good, do stuff
}

##Storage The Sugar REST PHP Client also provides three helper methods for storing the Token so that when using the Client in different areas of the same PHP process, you do not need to re-authenticate or worry about passing the same Client object or Token from one area of code to the next. All three methods are Static Methods, and utilize Late Static Binding to 'store' a Token in regards to a Client. You can also look at extending the Client and customizing these methods to to provide a true storage implementation so that authentication tokens can be persistent across multiple PHP processes. See the Customization documentation for a details.

The storeToken() method is called after successful Login via the login() method. Token's are 'stored' in the static property $_STORED_TOKENS, and by default use the 'client_id', 'platform', and 'username' in the Client credentials as a unique identifier.

You can retrieve a stored token via the getStoredToken() method by passing in the corresponding set of credentials for the Client. By default when the setCredentials() method is called on the Client, it will utilize the getStoredToken() method and configure the Token on the Client, so that authentication does not need to be done again.

Lastly you can use the removeStoredToken() method by passing in the corresponding credentials, when you wish to clear out an authentication token.