What are the types of authentication is available in ConnectPHP API?

Environment:

Oracle B2C Service, all supported versions

Resolution:

There are different types of authentication are available in the ConnectPHP API. The most common types are outlined below:

• authentication is performed using initConnectAPI()
• there is no need to specify credentials (login/password)

// Find our position in the file tree
require_once(
get_cfg_var('doc_root')
 
/************* Agent Authentication ***************/
                        
. '/include/ConnectPHP/Connect_init.phph' );
initConnectAPI();
                        
/************* End agent authentication ***********/
                                                
// Set up versioned namespace for Connect PHP API                        
use RightNow\Connect\v1_3 as RNCPHP;
                        
//----------- Ready to proceed with script --------//

 

2. File manager access point

• authentication is performed using AgentAuthenticator()
• the script URL looks like this: https://<site_name>.custhelp.com/cgi-bin/<interface_name>.cfg/php/custom/<script_name>.php
• if the script is called from outside the agent desktop, credentials must be provided

// Find our position in the file tree
if (!defined('DOCROOT')) {
$docroot = get_cfg_var('doc_root');
define('DOCROOT', $docroot);
}
 
/************* Agent Authentication ***************/
 
// Set up and call the AgentAuthenticator
require_once (DOCROOT . '/include/services/AgentAuthenticator.phph');
 
// On failure, this includes the Access Denied page and then exits,
// preventing the rest of the page from running.
$account = AgentAuthenticator::authenticateCredentials("login", "password");
 
/************* End agent authentication ***********/
 
// Set up versioned namespace for the Connect PHP API
use RightNow\Connect\v1_3 as RNCPHP;
 
//----------- Ready to proceed with script --------//

 

• if the script is called from the agent desktop (e.g. a browser control), the logged in agent session ID can be provided instead of specified credentials

<?php
// Find our position in the file tree
if (!defined('DOCROOT')) {
$docroot = get_cfg_var('doc_root');
define('DOCROOT', $docroot);
}
 
/************* Agent Authentication ***************/
 
// Set up and call the AgentAuthenticator
require_once (DOCROOT . '/include/services/AgentAuthenticator.phph');
 
// On failure, this includes the Access Denied page and then exits,
// preventing the rest of the page from running.
$agentSessionID = $_GET['p_sid'];
$account = AgentAuthenticator::authenticateSessionID($agentSessionID);
 
/************* End agent authentication ***********/
 
// Set up versioned namespace for the Connect PHP API
use RightNow\Connect\v1_3 as RNCPHP;
 
//----------- Ready to proceed with script --------//

 

• notice the session ID comes from the "p_sid" parameter in the above snippet
• when authenticating using the logged in agent session ID, make sure that the associated profile has the appropriate permissions to perform the actions in the script (e.g. if the script creates a contact, the authenticating agent must have permissions to create contacts)
   

For more information about passing information as URL parameters when calling custom scripts, please review:  Answer ID 2429: Including a variable on a custom tab or custom link.

It is also important to note that the authentication process updates Oracle B2C Service database tables such as _accounts or session_history. If multiple scripts executed very often are authenticating using the same staff account, it might lead to "deadlock" errors on the database, since every authentication would be locking the same table row on those tables.

For more information please review the ConnectPHP API documentation:
Answer ID 5169: Technical Documentation and Sample Code.