Authentication

Credentials

There are 6 request arguments that are needed to authenticate to a Sugar 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 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 updateAuthCredentials() method does overwrite the credentials stored on the Client.

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 \Sugarcrm\REST\Client\SugarApi($server,$credentials);

2. Update credentials via updateAuthCredentials()

$server = 'localhost';
$credentials = array(
        'username' => 'admin'
        'password' => 'password'
);
$SugarClient = new \Sugarcrm\REST\Client\SugarApi($server);
$SugarClient->updateAuthCredentials($credentials);

Both methods shown above will result in the same Client configuration.

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($username = null, $password = null) method to authenticate the Sugar REST API. Notice that you can override username and password when triggering it.

try {
    if ($SugarAPI->login()) {
        //do stuff
    } else {
        //login failed
        echo "Could not login.";
        pre($SugarAPI->getAuth()->getActionEndpoint('authenticate')->getResponse());
    }
} catch (Exception $ex) {
    echo "Error Occurred: ";
    pre($ex->getMessage());
    pre($ex->getTraceAsString());
}

The login($username = null, $password = null) method utilizes the OAuth2Token Endpoint and if successful authentication occurs with the Sugar REST API, stores the authentication token on the Client. If username and password are passed as parameter to this function, the Client will trigger updateAuthCredentials(); and update Client's credentials.

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 ($SugarAPI->refreshToken()) {
        //do stuff
    } else {
        //login failed
        echo "Could not refreshToken.";
        pre($SugarAPI->getAuth()->getActionEndpoint('refresh')->getResponse());
    }
} catch (Exception $ex) {
    echo "Error Occurred: ";
    pre($ex->getMessage());
    pre($ex->getTraceAsString());
}

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
    } else {
        //login failed
        echo "Could not logout.";
        pre($SugarAPI->getAuth()->getActionEndpoint('logout')->getResponse());
    }
} catch (Exception $ex) {
    echo "Error Occurred: ";
    pre($ex->getMessage());
    pre($ex->getTraceAsString());
}

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 \Sugarcrm\REST\Client\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 \Sugarcrm\REST\Client\SugarApi($server,$credentials);
if ($SugarAPI->authenticated()){
    //token is still good, do stuff
}