2Pass-Through Authentication Configuration

Enable and Configure Pass-Through Authentication

Enable pass-through authentication (PTA), set configuration options, then stage and promote your changes to the customer portal.

  1. Set the PTA_ENABLED configuration setting to Yes.

  2. Optional: Set the EGW_AUTO_CONT_CREATE configuration setting to No.

    EGW_AUTO_CONT_CREATE allows contact records to be created through email. By default, when an email message is sent to a Service mailbox from an address that does not exist in the Oracle database, a contact record is created automatically. By setting EGW_AUTO_CONT_CREATE to No, you avoid login issues resulting from mismatched user names and passwords.
  3. If you set EGW_AUTO_CONT_CREATE to No, then set the message base parameter NOT_REG_EMAIL_MSG to direct new customers to your website to register and create an account.

  4. Define the external login page.

  5. Decide if you want to use data encryption. If you do, set the method and other encryption specifications.

  6. Decide if you want to allow logout from the customer portal.

  7. Stage Your Customer Portal Pages.

  8. Promote Your Customer Portal Pages.

How You Define the External Login Page

Customers who try to access your customer portal from your external page may be redirected to an external login page when they click the link. If and how this occurs depends on several factors.

  • The URL of the link to the customer portal that resides on the external page

  • Whether the customer is logged in to the external site

  • Whether the customer portal page being accessed requires login

If the link to your customer portal on your external site passes customer information in the URL and the customer is logged in to the external site, the customer data is passed through the Customer Portal login function. The customer is then logged in to the customer portal, and the page opens. The login process is invisible to the customer, who clicks the link on the external page and sees the customer portal page open.

When the customer portal page requires login or the customer clicks the Log In link on the customer portal but is not logged in to your external site, they will be directed to the page defined by the PTA_EXTERNAL_LOGIN_URL configuration setting. Most likely, this will be the login page for your external site. You can pass next page variables and session information in this URL.

The PTA_EXTERNAL_LOGIN_URL configuration setting also accepts the error code variables you can use in the PTA_ERROR_URL configuration setting to help troubleshoot pass-through authentication login issues. When a value is entered in the PTA_ERROR_URL configuration setting, any error code variables in the PTA_EXTERNAL_LOGIN_URL configuration setting are ignored.

For example, if the customer tries to open the Answers page but you have required login on that page, the URL you specify to redirect the login can contain the %next_page% variable. After they have logged in, your login functionality points them back to the customer portal, passing the validated customer information and returning them to the Answers page. The URL looks like this:

http://your_site/login/nextPage/%nextPage%
Note: The next page parameter gets passed to the page automatically even when you do not configure it, but specifying it lets you control its placement.

You can also pass URL parameters using this format:

http://your_site/login.php?nextPage=%nextPage%

The customer portal processes the customer information through its login functionality, although the customer does not see this process. If the information passed in the URL is sufficient to identify an existing contact record in the Oracle database, the customer is logged in and sees the customer portal page they originally tried to access. Any new or additional contact information that is passed through the URL is used to update the contact record.

The passed login parameters must provide data for the minimum required fields needed to log in to the customer portal (p_userid and p_passwd) or create a new contact record (p_userid, p_passwd, and p_email.addr). (In most cases, we recommend that you pass back all URL parameters to B2C Service that the application passed during the redirection.)

Note: If contact custom fields have been created on the administration interface and are required on the customer portal, the values for these fields must also be passed before a new contact record can be created.

If no contact record in the database matches the login parameters passed to the customer portal, a new contact record is created and the customer is logged in to the customer portal as the new contact. If the contact information that is passed does not contain all the fields required to create a new contact record, you can configure the customer portal to direct the customer to an alternate URL. For example, you might create a web page that lets the customer know that access is denied. Or this URL might be a form for gathering the additional required information that then re-passes the parameters to the customer portal.

URLs sent to contacts through email (for example, a link to update the incident) use the URL specified in the PTA_EXTERNAL_LOGIN_URL configuration setting. If you pass a non-blank password using p_passwd in a PTA event and the EU_CUST_ PASSWD_ENABLED configuration setting is disabled, the PTA event will fail. We recommend that you do not change the default value of the EU_CUST_PASSWD_ENABLED configuration setting, which is Yes (enabled), when using PTA.

The customer session ID can be automatically appended to the URL when the customer is redirected through the customer portal. The page specified in the PTA_EXTERNAL_LOGIN_URL configuration setting must be configured to accept the session ID.

Why and How to Use Data Encryption

You can use encryption to increase the security of the customer login information passed to the customer portal pages from an external site.

By default, encryption is disabled and the data received by the customer portal page URL is Base 64 encoded and then decoded. With encryption enabled, the data is still Base 64 encoded and decoded, but then it is converted to an encrypted string.

Note: If you do not want to use data encryption, you must define a value for the PTA_SECRET_KEY configuration setting in order to validate login parameters. This value should be passed as a p_li_passwd parameter encoded in the PTA login string.

Four configuration settings are used to configure PTA data encryption. For the procedure to edit configuration settings, see Edit Configuration Settings.

Table Data-Encryption Configuration Settings

Setting Description
PTA_ENCRYPTION_METHOD Specifies the encryption method you want to use, and is blank by default. The options are des3, aes128, aes192, and aes256.
PTA_ENCRYPTION_IV Lets you specify an initialization vector value to use for PTA encryption. Initialization vectors are optional, but can help you increase the security of the encryption. You can enter up to a 16-byte value, given as a hex-encoded (base 16) list of bytes. The value depends on the type of encryption specified in the PTA_ENCRYPTION_METHOD configuration setting. 16 bytes are required for aes128, aes192, and aes256 encryptions, and 8 bytes are required for des3 encryption.
Optionally, you can enter a value of ENCODED if the decryption method expects the initialization vector to be read from the encrypted string (after the salt, if salt is used) and before the encrypted value. This option is more secure than hardcoded values if the proper cryptographically random values are sent along in the encrypted data.
PTA_ENCRYPTION_KEYGEN Specifies the keygen method used for PTA encryption. The default value is RSSL_KEYGEN_PKCS5_V20, and the other options are RSSL_KEYGEN_PK55_V15 and RSSL_KEYGEN_NONE.
PTA_ENCRYPTION_PADDING Specifies the padding method used for PTA encryption. The default value is RSSL_PAD_ANSIX923, and the other options are RSSL_PAD_PKCS7, RSSL_PAD_NONE, RSSL_PAD_ZERO, and RSSL_PAD_ISO10126.
PTA_ENCRYPTION_SALT Lets you specify a salt value to use for PTA encryption. Salt values are optional, but can help you increase the security of the encryption. You can enter up to an 8-byte value, given as a hex-encoded (base 16) list of bytes.
Optionally, you can enter a value of ENCODED if the decryption method expects the salt to be read from the encrypted string before the initialization vector and the encrypted value. This option is more secure than hardcoded values if the proper cryptographically random values are sent along in the encrypted data.
PTA_SECRET_KEY Specifies the key used to decode the encrypted PTA string. The value is blank by default. (Do not include the value of PTA_SECRET_KEY in the string itself. The setting should be used only to encrypt the value sent.)

Stage Your Customer Portal Pages

After you have edited the customer portal pages in the development area, you can stage them to see how your changes will appear on the production site.

Before you can stage development pages, the profile assigned to you must have the CP Stage permission enabled. You or your administrator can enable this permission if necessary.
Because the staging area replicates the production site but keeps the pages from being visible to customers, you can continue to modify the development pages and then stage them without exposing the changes to your customers until you are satisfied with the results.
  1. Log in to B2C Service.

    Alternately, you can use the Customer Portal Administration site instead of the administration interface by entering https://<your_site>/ci/deploy/index (or http://<your_site>/ci/deploy/index if your site does not have SSL enabled.)

    Continue to Step 5 to resume this procedure.

  2. Click Configuration on the navigation pane.

  3. Expand Site Configuration and double-click Customer Portal.

  4. Select the interface you want to stage from the Interfaces column.

  5. Perform one of these tasks:

    • On the administration interface, click Stage on the Customer Portal editor ribbon.

    • On the Customer Portal Administration site, click Stage on the Deploy page.

    If you have created a new widget for your customer portal, you must be sure that Copy to Staging is selected for the widget on this first step of the staging process. Additionally, you must also select Yes to push all framework and widget version changes on the Version Changes page during the staging process. If you do not include pushing the version changes, your new widget will not be available on your staging site.

    The first window displays a list of files that have been changed in the development area since the last time files were staged. By default, all new and edited files are selected to be copied to the staging area, and any files you have removed from the development pages have the Remove From Staging action.

  6. To prevent a file from being copied to the staging environment, click the Action drop-down menu in the row associated with the file and select No Action.

    This lets you maintain any changes you have made to the development page without having those changes appear in the staging environment or the production pages when you promote the site.

  7. To remove one or more files from the staging environment, click the Action drop-down menu in the row associated with the file and select Remove From Staging.

    The selected file will be removed from the staged pages and will not be available to be copied to your production site.
  8. Click Next to continue.

    The window displays any version changes to the framework or widgets.

  9. To push all framework and widget version changes, including the addition of new widgets, select Yes from the drop-down menu located in the bottom-left corner of the page.

    Caution: If you do not include pushing the version changes, any new widgets will not be available on your staging site.
  10. Click Next to continue.

    The window displays all user agent page set mappings for the interface and notes whether they are enabled or disabled. It also shows the differences in the page sets between the development and staging areas. By default, No Action is selected for the listed page sets, but if you have disabled a page set, the action will be Remove From Staging.

  11. To copy a page set that you’ve enabled to the staging area, click the drop-down menu in the Actions column and select Copy To Staging.

  12. To remove a development page set from the staging area, click the drop-down menu in the Actions column and select Remove From Staging.

  13. Click Next.

    The window summarizes your selections from the earlier pages of the staging process.

  14. To store a comment in the staging log file, enter a note in the field.

    You can enter up to 4,000 characters.
  15. To re-initialize the staging environment, select the check box just above the Stage button.

    Caution: If you select this check box, you will lose any file and page set selections you have made during the staging process. Re-initializing means that all files in the staging area will be deleted and replaced with their corresponding files or settings from the development area.
  16. Click Stage.

    A message asks you to confirm that you want to copy the selected items to the staging area.

    Note: You will see a message if a deploy lock is in place. Clicking No cancels the staging operation and Yes overrides the existing lock and then continues with the staging operation. Use caution when clicking Yes because you may compromise another staff member’s file promote if you start overwriting files in the staging area.
  17. Click Stage to continue.

    When the process is complete, a window lets you know staging was successful. It also displays a link to view the log. If you staged the files from the Customer Portal Administration site, the window also contains links to the staging area, where you can view the pages, and a link to the Promote page.

    Note: If any widgets have been deleted, the message notifies you that the deleted widget has been deactivated in the staging environment. Also, if any of the widget versions are incompatible with the framework, a staging error occurs and identifies the incompatible widget.

Promote Your Customer Portal Pages

After you are satisfied with your staging area, you can promote the pages and files to production.

Before you can promote the staging area, the profile assigned to you must have the CP Promote permission enabled. You or your administrator can enable this permission if necessary.
  1. Perform one of these tasks:

    • Log in to B2C Service.

    • In a web browser, enter https://<your_site_interface>/ci/deploy/promote. Continue to Step 6.

  2. Click Configuration on the navigation pane.

  3. Expand Site Configuration, and double-click Customer Portal.

  4. Select the interface you want to promote from the Interfaces column.

  5. Click Promote.

    The window shows you the list of edited files and configurations and notes whether the file or configuration exists in the staging and production areas.

  6. To store a comment in the log file, enter a note in the field.

    You can enter up to 4,000 characters.

  7. Click Promote at the bottom of the page.

    A message asks you to confirm that you want to replace your current production area with the files from the staging area. You will see a message if a deploy lock is in place. Clicking No cancels the promote operation and Yes overrides the existing lock and continues with the promote. Use caution when clicking Yes because you may overwrite another staff member’s work.

  8. Click Promote to continue.

    When the process is complete, a window lets you know the promote process was successful. It also displays a link to view the log. If you promoted the files from the Customer Portal Administration site, the window also contains a link to the production area, where you can view the promoted pages, and a link to the Rollback page.

How You Configure the Customer Portal for Pass-Through Authentication

When you implement PTA integration with the customer portal, you may want to make some changes to your customer portal pages.

These options are available.

  • Require login on customer portal pages—You can add a login requirement to any customer portal page so that customers must be validated through the external login pagey before they can open the customer portal page. See Require a Login for Customer Portal Pages.

  • Edit the Your Account pages—If you do not want customers to edit the fields on the Your Account pages, you can remove them. If you want to let them edit fields, you must edit the input field widgets on the pages containing the fields. See Allow Customers to Edit Fields on the Account Settings Page.

Note: After you have completed these steps, you must deploy the customer portal. If your profile does not have sufficient permissions to deploy the customer portal, coordinate with your administrator to arrange the deployment.

How You Use Pass-Through Authentication When a Chat Request is Accepted

If you use pass-through authentication (PTA) to log users into your customer portal site, you can use the same login credentials when using the syndicated ProactiveChat widget API, and when a chat request is accepted.

To use PTA, you have to subscribe to the evt_beforeDataRequest event, which is initiated after a chat is accepted and after chat agent availability is checked. In the callback method for the event, you can build your PTA string similar to the way it is done within customer portal code. The encoded PTA string can then be added to the data arguments.

Add code similar to this to the web page containing the widget.

<script type="text/javascript">
    function addPta(type, args, instance){
          var ptaToken = 'thisIsYourEncryptedPTAString';
          var data = args[0];
             if(data){
                 data.pta = ptaToken;
RightNow.Client.Event.evt_beforeDataRequest.subscribe(addPta);
</script> 

In the example, the callback method addPta is called when the event is fired.

Edit Configuration Settings

Follow this procedure to edit pass-through authentication configuration settings.

  1. Click Configuration on the navigation pane.

  2. Expand Site Configuration, and double-click Configuration Settings. The Search window opens.

    Note: You must perform a search before any data displays.

    From the Search window you can filter the configuration settings that display on the editor. Alternatively, you can click the Cancel button to bypass the Search window and perform your search using the buttons on the ribbon or the search fields on the top of the editor.

  3. Type the name of the configuration setting you want to edit in the Key field. You can type a partial name, using the percent (%) or asterisk (*) symbols as wildcard characters. For instance, you can search for configuration settings beginning with PTA_ by entering “pta_%” in the Key field.

    Tip: To display the configuration settings you need, you may need to click the Select All check box in the Configuration Base field.
  4. Select the row that displays the configuration setting you want to edit.

  5. Perform one of these tasks:

    • Click Edit Selection. Either the Site or interface_name window opens depending on the whether the configuration setting applies to the entire B2C Service site or to specific interfaces.
    • Double-click the setting to open it on the content pane and edit the value field.
  6. Type or select the new value. Editing options are specific to the field’s data type. For example, if a setting can be enabled or disabled, a Yes/No drop-down menu displays in the Value field.

  7. Perform one of these tasks:

    • To confirm a value entered in the Site or interface_name window, click the window’s OK button, and then click Save.
    • To confirm a value entered in the editor on the content pane, click Save.
      Note: You may be required to log out of the administration interface and log back in for your changes to take effect.