6Reference

Pass-Through Authentication Configuration Settings

A number of configuration settings must be modified to configure pass-through authentication. These settings are listed here and described in detail in the topics referenced in the table.

Configuration settings are modified using the Configuration Settings editor. For more information about configuration settings, see How the Configuration Settings Editor Works.

Table Pass-Through Authentication Configuration Settings

Setting Description

EGW_AUTO_CONT_ CREATE

This setting, which is enabled by default, allows the creation of new contact records when an email is received from an email address that does not already exist in the database. To avoid potential login issues when using PTA, this setting should be disabled. See Enable and Configure Pass-Through Authentication.

EU_CUST_PASSWORD_ ENABLED

This setting, which is enabled by default, enables the display of the contact password field on customer portal pages. This setting should be enabled when using PTA. See How You Define the External Login Page.

PTA_ENABLED

Enables the use of pass-through authentication. See Enable and Configure Pass-Through Authentication.

PTA_ENCRYPTION_IV

Specifies the initialization vector you want to use for PTA encryption. See Why and How to Use Data Encryption.

PTA_ENCRYPTION_ KEYGEN

Specifies the keygen method you want to use for PTA encryption. Refer to Why and How to Use Data Encryption.

PTA_ENCRYPTION_ METHOD

Specifies the encryption method you want to use for PTA logins. Refer to How You Enable Dual-Mode Login and Why and How to Use Data Encryption.

PTA_ENCRYPTION_ PADDING

Specifies the type of padding you want to use for PTA encryption. See Why and How to Use Data Encryption.

PTA_ENCRYPTION_ SALT

Specifies the salt value you want to use for PTA encryption. See Why and How to Use Data Encryption.

PTA_ERROR_URL

Specifies the URL where customers are redirected when PTA login attempts fail. If this setting is blank, customers are redirected to the URL specified in the PTA_EXTERNAL_LOGIN_URL setting. See How You Interpret Error Codes.

PTA_EXTERNAL_ LOGIN_URL

Contains the URL to a login page where customers are directed if they try to access a customer portal page that requires authentication. See How You Define the External Login Page.

PTA_EXTERNAL_ LOGOUT_SCRIPT_URL

Specifies the URL where customers are directed to log out of the customer portal. If this setting has a value, customers can log out of the customer portal. If the setting is blank, customers will not be able to log out from the customer portal since the logout widget will not display. See How You Require Customers to Log Out From the Customer Portal.

PTA_EXTERNAL_POST_ LOGOUT_URL

Contains the URL to the page where you want to redirect customers after they log out of the external system. See How You Require Customers to Log Out From the Customer Portal.

PTA_IGNORE_ CONTACT_PASSWORD

Specifies whether contact passwords are honored during PTA logins. See How You Enable Dual-Mode Login.

PTA_SECRET_KEY

Contains the secret key used to validate login integration parameters when encryption is disabled, or the key to decode the PTA string when encryption is enabled. See Why and How to Use Data Encryption.

Additional Parameters

Besides the fields from the contacts table, you can also pass parameters to the customer portal.

Table Parameter Descriptions

Parameter Notes

p_ccf_*

This parameter represents a contact custom field in B2C Service. The * must be replaced with the number of the cf_id for the contact custom field. If this is a menu custom field, the numbers (not the actual text) for each menu item must be specified as the value in the integration login code. See How You Find Code Numbers and Report IDs.

p_chan_*

This parameter represents the contact’s social channel. The * must be replaced with the ID number of a valid channel:

11—Twitter

12—YouTube

The value represents the user name for the channel. For example, if you want to pass the contact’s Twitter user name, you would pass the parameter and value p_chan_11="jane.doe", where jane.doe is the user name.

p_li_expiry

This parameter is a time stamp that defines how long the PTA login information is valid. When the time expires, the login information is no longer accepted and contacts are redirected to the page specified in the PTA_ERROR_URL configuration setting, and an error code of 16 is passed to the page. See How You Interpret Error Codes.

Note: You can generate the value using a UNIX date/time stamp generator.

p_li_passwd

This parameter represents the string specified in the PTA_SECRET_KEY configuration setting.

Note: This parameter is required if the PTA_SECRET_KEY configuration setting contains a value and the PTA_ENCRYPTION_METHOD configuration setting does not contain a value.

p_org_id

This parameter represents an organization ID to associate with a contact.

Note: You must manually assign any service level agreements (SLA) that you want to associate with the organization, including those controlling privileged access.

p_state.css

This parameter represents the contact’s state for B2C Service.

0—Disabled

1—Enabled

p_state.ma

This parameter represents the contact’s state for B2C Service Outreach.

0—Disabled

1—Enabled

p_state.sa

This parameter represents the contact’s state for Opportunity Tracking.

0—Disabled

1—Enabled

How You Interpret Error Codes

When a customer attempts to log in using pass-through authentication, there are a number of factors that can cause login failure, including an invalid user name or password, a duplicate email address in the database, and problems with the PTA string.

To help you debug login errors or provide informational messages, customers can be redirected to a custom page displaying an error code and session information when an error occurs.

The URL of the page where customers are redirected is specified in the PTA_ERROR_URL configuration setting. To display an error code, the URL must be appended with the %error_code% variable. Session information can be provided in the form of a base64-encoded string if the %session% variable is also appended. Session information displays only if login tracking cookies are disabled on the customer’s computer.

Note: The PTA_ERROR_URL configuration setting is blank by default. If you do not specify a value for the setting, customers are redirected to the URL in the PTA_EXTERNAL_LOGIN_URL configuration setting when a login error occurs. If you choose not to use PTA_ERROR_URL, you can append the %error_code% and %session% variables to the end of the URL specified in PTA_EXTERNAL_LOGIN_URL. See How You Define the External Login Page.

For example, assume that you set the configuration setting value to:

http://your_site/my_login_error_page.php/%error_code%

If login fails because the password exceeds the 20-character limit, the URL that is returned is:

http://your_site/login/nextPage/home/error/15

The error code, 15 in this example, lets you know what caused the failure.

The table describes error codes found in the URL. These codes are the same whether the %error_code% variable is used in the PTA_ERROR_URL or the PTA_EXTERNAL_LOGIN_URL configuration setting.

Table Error Code Descriptions

Error Code Description

1

The PTA string parameter was not found. This parameter contains all of the encoded PTA information in the URL, so it must be present to log in.

2

PTA information after pre_pta_decode hook was not in the correct format. A string or an array was expected, but something else was received.

3

PTA string could not be Base 64 decoded. There was an error within the string that caused the decoding process to fail.

4

One of the PTA string parameters was not well formed. For example, it did not contain “p_” or was missing an “=” separator between the key and value.

5

The p_userid string was passed in, but it did not have a value. This pair is required for login.

6

The value of the p_li_passwd pair was incorrect. This error applies only if no value is set for the PTA_ENCRYPTION_METHOD configuration setting.

7

The specified credentials were invalid.

8

Login failed because PTA is not enabled for the interface.

9

Data decryption failed.

10

Login failed because PTA_ENCRYPTION_METHOD does not contain a valid value.

11

Login failed because the PTA_ENCRYPTION_PADDING configuration setting does not contain a valid value.

12

Login failed because the PTA_ENCRYPTION_KEYGEN configuration setting does not contain a valid value.

13

Login failed because the PTA_IGNORE_CONTACT_PASSWORD configuration setting is enabled, but no encryption scheme has been set in PTA_ENCRYPTION_METHOD.

14

Login failed because the format of the data after the pre_pta_convert hook was not an array.

15

Login failed because the password exceeded the 20-character maximum length.

16

Login failed because the PTA token expired and is no longer valid. A new token must be generated to authenticate the customer.

17

Login failed because two or more email addresses have the same value.

How You Find Code Numbers and Report IDs

You must use code numbers (ID numbers) in pass-through authentication to specify parameters such as countries, provinces, custom fields, and organization IDs.

The administration interface provides three ways to look up the codes for these types of fields:
  • Hovering over the field name

  • Displaying report IDs in the Reports explorer

  • Using the NamedID helper object

When exploring reports, you can view the report ID (ac_id) by displaying the ID column in the explorer details.

Many records and items contain an Info button on the Home tab of the ribbon. When you click the Info button, record details display, including the record ID number.

How You Pass Login Parameters

These examples show how to generate a form to pass login parameters to B2C Service.

Using these examples, you can retain all query_string parameters and append key-value pair parameters.

Replacing certain variables with meaningful values will make the scripts easier for you to understand.

  • your_domain: the domain name used by your B2C Service site

  • your_interface: your interface name

  • li_password: the string specified in the PTA_SECRET_KEY configuration setting

Caution: This example code snippet is for illustrative purposes only and will be improperly formatted if you attempt to cut and paste directly from it.
<?
//Assumption is that user has been validated/logged in and you have their contact record
//available and can access their profile data
//Build up PTA data array
$ptaDataArray = array(

//Common contact fields (not a complete listing, this is just a sampling)
//The $contact variable is assumed to be the data of the user logging in
'p_userid'     => $contact->login,
'p_passwd'     => $contact->password,

//Only needs to be sent if PTA_IGNORE_CONTACT_PASSWORD is disabled
'p_email.addr' => $contact->emailAddress,
'p_name.first' => $contact->firstName,
'p_name.last'  => $contact->lastName,

//Example of sending in custom field value where the custom field 
ID is 3 'p_ccf_3'      => $contact->customField3Value,

//Example of sending in channel field value where the channel field ID is 14
'p_chan_14'    => $contact->channelField14Value);

//Add secret key if not using encryption
if (PTA_ENCRYPTION_METHOD configuration setting IS NOT set)
{
$ptaDataArray['p_li_passwd'] = Value of PTA_SECRET_KEY config setting;
}

//Convert PTA data array to string
$ptaDataString = "";
foreach($ptaData as $key=>$value)
{
$ptaDataString .= ($ptaDataString === "") ? '' : '&';
    $ptaDataString .= "$key=$value";
}

//Optionally encrypt data if using encryption with the method, secret key, padding a keygen
//methods. The function called here is made up. The actual function will vary depending on
//which language you are using
if (PTA_ENCRYPTION_METHOD IS set)
{
$ptaDataString = encryptData($ptaDataString, PTA_ENCRYPTION_METHOD, 
PTA_SECRET_KEY, PTA_ENCRYPTION_PADDING, PTA_ENCRYPTION_KEYGEN);
}

//Base64 encode the data
$ptaDataString = base64_encode($ptaDataString);

//Make sure the data is URL safe
$ptaDataString = strtr($ptaDataString, array('+' => '_', '/' =>
'~', '='                         => '*'));

//Specify which page to take the user to
if (%next_page% URL parameter exists)
$redirectPage = %next_page% parameter;
else
$redirectPage = 'home';

//Send the user to the PTA controller to log them in
header("Location: http://your _CP_site/ci/pta/login/redirect/$redirectPage/p_li/$ptaDataString");
exit;

How You Use the pre_pta_decode Hook

The pre_pta_decode hook lets you write custom PHP code, which is executed after accepting the PTA string from the URL and before calling the login routine.

After the hook runs, the p_li parameter is processed and passed to the PTA controller. The hook also passes the redirect parameter so you can modify the location where the customer is directed.

It is not possible to return a custom error message from this hook, so if you want to cover the situation of an interrupted PTA login, you must add a header() location redirect and exit() in your hook. There are two data formatting options: string or array.

  • String format—After the hook executes, the login integration data that was passed to the hook is evaluated to see if it is still a string. If it is, the data is assumed to be a standard base_64 encoded string. An algorithm is run to convert the string into an array of contact pairdata in key->value pairs. This allows the pass-through authentication to work as it would if no hook handler is defined and no extra encryption is added.

  • Array format—After the hook executes, the p_li parameter is evaluated to see if it has been converted to an array. If so, the format of this array is assumed to be the contact pairdata key->value structure. Here’s an example of this structure.

array(
   [p_passwd]=>
   [p_userid]=>username
   [p_email.addr]=>email@example.com

How You Use the pre_pta_convert Hook

You can use a pre_pta_convert hook that runs after the data has been decoded and converted into an array, and before it is converted to the correct pair data structure.

This lets you modify the PTA data sent in the URL on the fly without having to decrypt and convert it yourself.

In this hook, a single parameter named “decodedData,” which is in the form of an array, is passed. This example shows the data in the URL in the first line and the decoded/decrypted data passed to the hook by reference in the second line.

JnBfdXNlcmlkPXVzZXJuYW1lJnBfZW1haWw9dGVzdEBleGFtcGx lLmNvbQ**
[p_userid => 'username', p_email => 'test@example.com']

Any modifications to the array are picked up by the PTA controller when the data is converted into contact API pairs.