Prism Users Guide - Chapter 26. Miscellaneous
26.16 OAuth Setup

Prism OAuth Setup PDF

This topic explains how to configure Prism to send email (Gmail) using OAuth as the authentication method. 
Basic Steps
(Each of these basic steps is explained in more detail in the sections that follow.)
1.    Create a Project and OAuth credentials in Google Cloud Platform Console.
2.     Configure Prism Email Server preferences (store-level) for OAuth.
3.    Configure Prism store records (subsidiary-level) for OAuth. Copy the Redirect URL. Save and exit the store record.
4.    In Google Cloud Platform Console, paste the Redirect URL into the Authorized Redirect URI field for the store's OAuth credentials and save the changes.
5.    Re-open the store record and authenticate. Google will establish a connection and generate OAuth access/refresh tokens.
6.    Configure Prism Print Preferences for email.
Requirements/Notes

• The machine used to set up OAuth for each Prism store and that authenticates with Google must be secured using SSL certificates. 
• A valid network domain is required. Sending email using OAuth does not work for a "workgroup" network setup. 
• You can set up OAuth for all Prism Stores at a single machine, e.g. the root authority server, or set up OAuth for each Store at the Store server.
• Only the machine that was used for the original OAuth setup (i.e., that "authenticated" with Google) can be used to modify the setup, unless the account is specifically configured to allow other machines to do so (i.e., those other machines are added as authorized redirect URIs).
• To modify an OAuth setup, the host must be secured using SSL certificates and the host's secure Authorized Redirect URI must be entered and saved in the Gmail OAuth Credentials that are being used for that specific setup.
• Once configured, both the Store's OAuth Configuration settings, and the Print Area settings for each Store are replicated throughout the Enterprise.
• Email preferences from the original login session will take priority over email preferences of a ‘Change Location' session (when a user changes store or subsidiary). For example, a user whose normal workstation login is Store 1 changes stores and creates a document for Store 10. The Email Preferences from the user's original location (Store 1) will be used, not those for Store 10. 

 
Best practice - Limit use to small-to-medium enterprises
Free email services like Gmail have limitations, not all of which are known. In addition, the mechanisms and requirements of the email provider may change at any time, making any existing configurations invalid. Therefore, we recommend you limit this feature to small-to-medium Prism enterprises. This feature has been tested with Gmail using a sample 5 store enterprise with a moderate number of emails. The testing used one Gmail account for all 5 stores and one "project" for which multiple OAuth credentials are defined (one credential per store), all configured at the Root Authority and replicated throughout the enterprise.). 
Best Practice - One Email Account per store
For each store, we recommend you create a separate Gmail account (e.g., xxx@gmail.com) that is only used to send documents from Prism (not for private or company communication). 
Create OAuth Credentials in Google Cloud Platform Console
1.    Go to the Google Cloud Platform Console (https://console.cloud.google.com/) and log in to the account.
2.    Create a New Project. Click the link to enter the project.
3.    Click on ‘APIs & Services.' 
4.    Click on ‘Enabled APIs & Services' on the left. In the list of APIs, click on the Gmail API. 
5.    Click ‘Enable.' This will link the Gmail API to your project.
6.    Click on ‘OAuth Consent Screen' on the left. 
Make sure ‘User Type' is set to ‘External.' 
Add a Test user. Use the actual store GMail account. Example: ‘store001account@gmail.com'). (Note: You will have to enter this same Gmail account in Prism Email Server preferences.)
DO NOT CLICK ‘PUBLISH_APP' since this is an internal app for use by the merchant in sending email using the merchant's Gmail account. 
 
Sample OAuth Consent Screen:

7.    Click ‘Credentials' on the left and ‘Create Credentials' (top).  
8.    Select ‘OAuth Client ID.' 
9.    Select ‘Web application' for the Application Type. On the displayed screen:

• Enter a name for the credentials.
• Leave the Authorized Redirect URIs area alone for now. Later, when configuring Prism store records, you will click the Load Callback URL button and add the displayed URL as an Authorized Redirect URI.
• Click ‘Create.' When the process is finished, you will see the credentials in the list of OAuth Client IDs. 

10.    Click on the name of your credentials. Under ‘Additional Information', copy the ‘Client ID' and the ‘Client Secret' and paste into the appropriate fields in the Prism store record.  
 
Configure Prism Email Server Preferences (store-level)
1.    Navigate to Admin Console > Node Preferences > Node Selection. Drill down to the desired store so that the store's list of workstations is displayed.
2.    With the list of workstations displayed, navigate to Admin Console > Node Preferences > Email Server Preferences. 
3.    Set the Email Authentication Type to OAuth.
4.    Set the Email Host Name to smtp.gmail.com
5.    Set the SMTP Port to 587.
6.    Select the Use SSL checkbox.
7.    In the Sender Email Address field, enter the Gmail account.
8.   In the Server User Name field, enter the Gmail account.
9.   In the Server Password field, enter the password used to log in to the Gmail account.
10.    Save the changes.

Email Server Preferences fields

Sample Prism Email Server Preferences (Store Level)

Configure Prism Store Record
Add Client ID, Client Secret, Gmail Account to store record
1.    Navigate to Admin Console > Node Preferences > Node Selection > [Subsidiary] so the stores for the subsidiary are displayed.
2.    Click the Edit button for a store to display the store record. The store record includes several Gmail Oauth fields at the bottom of the screen.   
3.    Copy/paste the Client ID and Secret Key and enter the Gmail account.
4.    Click Load Callback URL. Copy the displayed URL.
5.    Save and exit the store record.

Add Authorized Redirect URI for store's OAuth credentials
1.    Display the store's OAuth credentials in Google Cloud Platform Console and paste the copied URL into the Authorized Redirect URI field (Click ADD URI). Save the changes to the credentials. 

Authenticate
1.    Re-open the store record and click Authenticate.
2.    When you click Authenticate, you will see a series of prompts.  First, you will be prompted to select the account to use.
 
 
Next you will see a prompt explaining that you are accessing an unverified (Unpublished) app. 
Click Continue. 
 
Another verification screen is displayed, confirming the domain that wants access to the selected account. 
Click Continue.

Finally, you will see a message announcing that authentication was successful. Close the window.
   

 After you authenticate successfully:

• Create a test transaction.
• Send a test email.

Notes

• Prism does not display an error to the end user if an e-mail fails to be sent. This is true whether the authentication method is OAuth or username/password. 

Prism Store record OAuth fields

Configure Prism Print Preferences
This section has information about how to configure print preferences (Email settings). 
1.    In Admin Console > Node Preferences > Node Selection, set the context to the Store Level.
2.    Navigate to Node Preferences > Hardware > Print Preferences.
3.    Select POS Transactions from the list of Print Areas.
4.    Ensure "Override Sub-Areas" is checked.
5.    Set Default Action to Email.
6.    Select the desired Email design.
7.    Save the changes.

Sample Node Preferences > Hardware > Print Preferences [Email Settings]: 

 
Notes
If you select Dialog for the Default Action, at POS when the transaction is complete and the user clicks the Print/Update button, a dialog will pop up with the selected Email Design already entered; you just need to type in the email address and click the Email button to send the email.