User Authentication

Generally, the JustOn Self-Service Extension provides two options for user authentication:

• It includes a complete infrastructure (pages, classes and settings) to authenticate users with external identity providers. The extension implements the standard OpenId Connect and supports the providers Amazon, Google, PayPal and Salesforce.
• Alternatively, it supports a password-based authentication mechanism for (registered) contacts. Passwords are stored on the contact using a secure and strong hashing algorithm (PBKDF2).

Note

JustOn recommends to authenticate your users using an external identity provider for the following reasons:

• You are not responsible for keeping safe the password hashes of your users.
• You get verified profile information for your users.
• Users usually do not want to remember another user name and password.

Info

Identity provider-based authentication and password-based authentication can be used together for the same Force.com site.

External Identity Provider

The JustOn Self-Service Extension includes a complete infrastructure (pages, classes and settings) to authenticate users with external identity providers. The extension implements the standard OpenId Connect and supports the providers Amazon, Google, PayPal and Salesforce.

Concepts and Workflow

Authentication Workflow

(1) If a user is not authenticated, they are redirected to the login page.

(2) The login page shows a login button for each enabled identity provider.

(3) The user selects an identity provider.

(4) The user is redirected to a login page at the provider site where they provide their credentials.

(5) The user is redirected back to the JustOn Self-Service Extension.

(6) The JustOn Self-Service Extension either creates a new account and contact if the user is a new user or finds an existing contact and account.

(7) The JustOn Self-Service Extension sets a cookie to store the identity provider used by the user.

(8) The JustOn Self-Service Extension creates a 2-hour session and redirects the user to the products page.

Session Handling

The JustOn Self-Service Extension stores the session information on the custom object Session. Expired sessions are deleted automatically.

Each session refers to an account and contact. Account and contact restrict the access of the authenticated users to their own subscriptions and invoices.

The Session object holds the following information:

Field	Description
Account	The related account.
Contact	The related contact.
Expires	The expiration date and time of the session.
Session ID	A unique, random ID of the session.
Timeout	The timeout in minutes. Defaults to 120.

User Identification

The JustOn Self-Service Extension identifies a user using the custom contact fields External User ID and Identity Provider. The combination of the two values is considered unique. The external user ID is provided by the identity provider upon successful login.

Field	Description
Identity Provider	The external identity provider. Possible values include Amazon, Google, Paypal, Salesforce.
External User ID	The unique ID of the user set by the identity provider.

Setting Up Identity Provider

In order to use one of the supported identity providers, your Force.com site must be registered with the provider. On the one hand, the provider needs a return URL to which the users are redirected after successfully logging in. On the other hand, the provider generates a client ID and client secret, which must be stored for the JustOn Self-Service Extension.

This data is kept in the custom setting Authentication Provider.

Field	Description
Name	Either Amazon, Google, Paypal or Salesforce.
Client ID	A unique value generated by the identity provider.
Client Secret	A unique value generated by the identity provider.
Return URL	A unique URL, made of the server address of your Force.com site and the provider-specific Login Handler page.

The return URL is made of the server address of your Force.com site and the provider-specific Login Handler page. The site URL must use the HTTPS scheme.

Provider	Login Handler	Example Return URL
Amazon	ONBSE1__AmazonLoginHandler	https://s3e-developer-edition.eu0.force.com/ONBSE1__AmazonLoginHandler
Google	ONBSE1__GoogleLoginHandler	https://s3e-developer-edition.eu0.force.com/ONBSE1__GoogleLoginHandler
PayPal	ONBSE1__PaypalLoginHandler	https://s3e-developer-edition.eu0.force.com/ONBSE1__PaypalLoginHandler
Salesforce	ONBSE1__SalesforceLoginHandler	https://s3e-developer-edition.eu0.force.com/ONBSE1__SalesforceLoginHandler

Creating Authentication Provider

1. In Setup, open Custom Settings.

   In Salesforce Lightning, navigate to Custom Code > Custom Settings.

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Authentication Provider.

3. Click New.

4. Specify the details as necessary.

   • Name: either Amazon, Google, Paypal or Salesforce
   • Client ID: as generated by the identity provider
   • Client Secret: as generated by the identity provider
   • Return URL: see table above

5. Click Save.

Configuring Amazon as Identity Provider

1. Navigate to Login with Amazon.
2. Click Sign Up.
3. Log in using your Amazon account (or create a new one).
4. Click Register New Application.
5. Specify the information as necessary, then click Save.
6. Open Web Settings and click Edit.

7. Specify the Amazon return URL, then click Save.

   For details about the return URL, see Setting Up Identity Provider.

8. Create a new Authentication Provider for Amazon.

   Specify the name Amazon and paste the Client ID, Client Secret and return URL from your Amazon Web Settings.

   For details, see Creating Authentication Provider.

For more information about integrating Amazon as identity provider, see Getting Started for Web or Login with Amazon Developer Guide for Websites.

Configuring Google as Identity Provider

1. Navigate to the Google Cloud Platform Console.
2. Log in using your Google account (or create a new one).
3. Click Create Project, and follow Google's instructions to create the project.
4. Select APIs & Services in the console left side menu, then select Library.

5. Enable the following APIs:

   • Contacts API
   • Google+ API

6. Select Credentials in the console left side menu.

7. Click New Credentials, then select OAuth client ID.

8. Follow Google's instructions to configure the application.

   The required information include:

   • Application Type: Web Application
   • Authorized Redirect URI: the Google return URL

   For details about the return URL, see Setting Up Identity Provider.

9. Click Create client ID.

10. Create a new Authentication Provider for Google.

    Specify the name Google and paste the Client ID, Client Secret and return URL from your Google application configuration.

    For details, see Creating Authentication Provider.

For more information about integrating Google as identity provider, refer to the Google Cloud Platform Console Help:

Create, shut down, and restore projects
Enable and disable APIs
Setting up OAuth 2.0

Configuring PayPal as Identity Provider

1. Navigate to the PayPal Developer Dashboard.
2. Log in using your PayPal account (or create a new one).
3. Select My Apps & Credentials.
4. In the REST API apps section, click Create App.
5. Provide a name and click Create App.
6. In the App Settings section, click Show next to Return URL.

7. Specify the PayPal return URL, and click +.

   For details about the return URL, see Setting Up Identity Provider.

8. Select the Log In with PayPal app feature and deselect all other options.

9. Click Advanced Options next to Log In with PayPal.

   1. Select Personal Information > Full Name.
   2. Select Address Information > all.

10. Click Save.

11. Create a new Authentication Provider for PayPal.

    Specify the name Paypal and paste Client ID, Client Secret and return URL from your PayPal app API credentials.

    For details, see Creating Authentication Provider.

For more information about integrating PayPal as identity provider, see Integrate Connect with PayPal in the PayPal Developer Documentation.

Configuring Salesforce as Identity Provider

Introduction

The Salesforce integration allows you to manage the self-service users with Salesforce. The integration allows two modes of operation:

• Enabling the login to the self-service portal for any Salesforce user. This is the appropriate option if many of your clients also have a Salesforce account that can be used to prove their identity.
• Enabling the login only for users of the Salesforce org where the self-service extension is installed. This is suitable if you intend to manage your clients with more control:
  • create user accounts with appropriate licenses (like, for example, Chatter External)
  • reset user passwords
  • activate/deactivate users

The Salesforce integration also supports the registration of new Salesforce users. If enabled accordingly, site guest users can register themselves as individual Salesforce users.

For details about user management in Salesforce, see Chatter User Licenses and View and Manage Users in the Salesforce Help.

Workflow

In broad outline, the user management works as follows:

(1) Optionally, create a Salesforce user with an appropriate license, like, for example, Chatter External, and email the password reset link to the client.

(2) Optionally, the client activates the user account and specifies a password using the link in the email.

(3) The client uses the Salesforce user account to log in to the self-service portal.

(4) The self-service extension creates according account and contact records for billing purposes.

Configuration

Info

If you want to manage your users, enable the option Restrict Salesforce users to local org in the custom setting Global Settings.

The configuration includes a Connected App and an Authentication Provider custom setting.

1. In Setup, open the New Connected App page.

   In Salesforce Lightning, navigate to Apps > App Manager, then click New Connected App.

   In Salesforce Classic, navigate to Build > Create > Apps, then click New in the Connected Apps section.

   1. Specify the app name, API name and contact email as required.
   2. Select the Enable OAuth Settings checkbox.
   3. Provide the callback URL as described in Setting Up Identity Provider.
   4. Select the OAuth scopes Access your basic information (id, profile, email, address, phone) and Allow Access to your unique identifier (openid).
   5. Click Save.
   6. Copy the generated consumer key and consumer secret.

2. Create a new Authentication Provider for Salesforce.

   Specify the name Salesforce and paste Client ID (Consumer Key), Client Secret (Consumer Secret) and return URL from your Salesforce Connected App.

   For details, see Creating Authentication Provider.

Enabling User Registration

Your business may require to allow site guest users to register themselves as Salesforce users. To support this use case, the self-service extension provides the custom setting Registration.

Field	Description	Example
Profile	The name of the profile to be assigned to registered users.	Chatter External User
Username Prefix	Specifies a prefix to be added to the username. As Salesforce usually takes the email as the username, the new username will be composed of the prefix and email.	my-service-

To enable the self registration, create an org default record as follows:

1. In Setup, open Custom Settings.

   In Salesforce Lightning, navigate to Custom Code > Custom Settings.

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Registration.

3. Click New in the Organization Level Value section.
4. Specify the details as necessary.

5. Click Save.

   This displays the link to the registration page on the login page.

Note

Be aware that Registration is a hierarchy custom setting. Make sure to create the default registration record on organization level, as described in Manage Custom Settings Data in the Salesforce Help.

Profile Information Provided by Identity Providers

Each supported identity provider offers a different set of profile information upon successful login. The JustOn Self-Service Extension uses this data to fill the fields on the account and contact. Users can then review and modify the information on the profile page.

Provider	Profile Information	Target Fields
Amazon	Name, Postal Code, Email	Account Name, Contact Name, Account Billing Postal Code, Contact Email
Google	Name, Given Name, Family Name, Email	Account Name, Contact First Name, Contact Last Name, Contact Email
PayPal	Name, Address, Given Name, Family Name, Email	Account Name, Account Billing Address, Contact First Name, Contact Last Name, Contact Email
Salesforce	Name, First Name, Last Name, Email, Mailing Address	Account Name, Contact First Name, Contact Last Name, Contact Email, Account Billing Address

Password-Based Authentication

The JustOn Self-Service Extension supports a password-based authentication mechanism for Salesforce contacts. Passwords are stored on the contact using a secure and strong hashing algorithm (PBKDF2). The system does not store plain text passwords.

Setting Up Password-Based Authentication

Setting up the password-based authentication involves the following steps:

• Creating an internal authentication provider
• Enabling read access for the password field on the contact
• Adding the button Set Password to the contact layout
• Optionally, enabling user name-based login

Once the setup has been completed, a user name and password field are visible on the login page of the extension.

Creating Internal Authentication Provider

1. In Setup, open Custom Settings.

   In Salesforce Lightning, navigate to Custom Code > Custom Settings.

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Authentication Provider.

3. Click New.

4. Specify the details as necessary.

   • Name: Internal
   • Client ID: -
   • Client Secret: -
   • Return URL: -

5. Click Save.

Enabling Password Read Access

1. Open the Site Details of your site.

   In the Sites list, click the label of the site to open its details.

2. Click Public Access Settings to open the site profile, and scroll to the Field-Level Security section.

3. Open the field-level security page for Contact.
4. Select Read Access for the field Password Hash.
5. Click Save.

Enabling Password Assignment

1. Navigate to the object management settings of the Contact object.
2. Click Page Layouts.
3. In the Contact Layout row, click Edit.

4. Add the Set Password button to the page layout.

   In Salesforce Lightning, drag the button from the Mobile & Lightning Actions palette to the Salesforce Mobile and Lightning Experience Actions section.

   In Salesforce Classic, drag the button from the Buttons palette to the Custom Buttons area.

5. Click Save to save the modified page layout.

For help about modifying page layouts, see Managing Page Layouts.

Enabling Login With User Name

By default, users can log in to the self-service portal using their email address and password. You can, however, define an additional field on the contact that holds a user name. If the field is enabled, users can log in using either their email or user name.

1. In Setup, open Custom Settings.

   In Salesforce Lightning, navigate to Custom Code > Custom Settings.

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Global Settings.

3. Click Edit in the row of Default.
4. In Username Field, specify the API name of the contact field that holds the user name.
5. Click Save.

Assigning Password to Contact

Users are not able to register themselves using the password-based authentication. Instead, you must assign a password to an existing contact and then send the credentials to the corresponding user.

1. Open the contact for which you want to create a password.
2. Click Set Password.

3. Specify the details as necessary.

   1. Specify the user name (if enabled).
   2. Specify the email address.

   3. Set and repeat the password.

      The password must be at least 10 characters long.

   4. Enable/disable the user.

4. Send the credentials to the user.

Creating Passwords for Multiple Contacts

You can generate passwords for multiple contacts at once by executing the BatchSetPassword job in the in the Salesforce Developer Console like, for example:

BatchSetPassword batch = new BatchSetPassword(
    [SELECT Id FROM Contact]
);
Database.executeBatch(batch, 1);

The produced passwords are randomized. They are stored to a CSV file for later reference.

1. Open the Developer Console.

   For details, see Open the Developer Console in the Salesforce Help.

2. Open Debug > Open Execute Anonymous Window.

3. Execute the code listed above.

   Edit the SELECT statement as necessary to edit the intended contacts.

   You can supply a second parameter to the constructor in order to set a global password.

4. If required, open Apex Jobs in Setup to monitor the job progress.

Once the job has finished, the CSV file with the user information and passwords is available in the Documents tab (Classic UI). Make sure to delete the file after you have sent the login credentials to the users.

Password Troubleshooting

The passwords are hashed multiple times to provide a better protection against brute force attacks. The Force.com platform provides, however, only limited computing resources, which may be hit if the iteration count is too high. JustOn therefore recommends at least 500 hashing iterations.

If the authentication takes too long, or if you see errors like login required or CPU timeout limit exceeded, consider reducing the number of password hash iterations.

1. In Setup, open Custom Settings.

   In Salesforce Lightning, navigate to Custom Code > Custom Settings.

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Global Settings.

3. Click Edit in the row of Default.
4. In Password Hash Iterations, specify the intended number of iterations.
5. Click Save.

Note

You must reset the passwords of your users to activate the change.

Info

JustOn recommends to adjust this setting only during the test phase.