Oct 1, 2024 | Retail Pro Prism
Retail Pro Prism 2.3 Authentication changes related to licensing
This document is based on a pre-release version of the Retail Pro Prism software. No feature is committed until the product GA release.
Background
For the purposes of this document client connections are connections to Retail Pro Prism using the API. Connections to the Rabbit MQ data bus or directly to the MySQL database are not covered as part of this document but will be secured in future releases.
Prior to Retail Pro Prism 2.3
- Implementations of Prism did not count or limit the number of concurrent client connections. Any number of client connections could be made to the API without regard to the actual number of seats paid for.
- Clients also could abandon the connection they were working on (close a tab or the browser) without concern for the number of open connections the server was maintaining.
- There was no interface to see the current connections to the Prism server.
- Restarting the Prism server would invalidate all active session tokens and require additional logins from all connected clients.
- The POSv1 service managed all active sessions.
Retail Pro Prism 2.3
Prism 2.3 Introduces 2 different types of connections: a read only connection that does not take a seat, and a read write connection that does take a seat. Applications logging into the system through the API that need to manipulate data will need to use a read write connection that takes a seat. See Authentication for customizations in 2.3 below.
With Retail Pro Prism 2.3 and going forward
- Retail Pro Prism will enforce the number of client connections that are paid for and bound to a Client ID.
- Within TTK there is now UI showing the client connections that are in use and the ability to manage those connections.
- Retail Pro Prism Licensing now manages all active sessions so POSv1 is not burdened with that task.
- Sessions are now DB backed. Rebooting the Retail Pro Prism licensing service no longer requires connected clients to login again and generate new auth tokens.
- Connections from the Retail Pro web client, iOS apps, TTK, or anything else that connects to the API to manipulate data will consume a seat.
- Retail Pro Prism inter-process authentication does not take a seat. i.e. Communication between POSv1 and BackOffice modules.
- Retail Pro Prism will allow additional logins past your Maximum Seat Count, but these will be read only logins and cannot be converted to read write logins.
- Logins now require logouts to release a seat and make it available for future use.
- PUT, POST, DELETE HTTP verbs will require a read write seat.
- Client customizations should use the current user token to make requests.
- Proxy customizations should use the current user token to make requests.
Authentication with Retail Pro Prism 2.3
Logging into Retail Pro Prism 2.3
The login process starts with an HTTP GET request using the following pattern:
URI: /api/security/login?usr=
Header: Accept : application/json, text/plain, */*
The parameters of the URI are detailed below.
|
Pos |
Parameter |
Value |
Required? |
Description |
|
1 |
Usr |
Plaintext |
Yes |
Prism employee name |
|
2 |
Pwd |
Plaintext but (MD5-Hashed preferred) |
Yes |
Password |
|
3 |
Ws |
Plaintext |
Optional for Non-Seated session. |
Workstation name |
|
4 |
Claimseat |
Boolean string |
Optional. False for Non-Seated session. |
True by Default in conjunction with WS param. |
|
5 |
Appid |
Plaintext |
Yes |
|
A successful login will return a session payload.
For example, the request
/api/security/login?usr=sysadmin&pwd=48a365b4ce1e322a55ae9017f3daf0c0 &ws=rkwin10_8080&claimseat=true&appid=POSTMAN
Might return this payload - Note the highlighted fields and values:
[
{
"sid": "696753503011199555",
"sessionstatus": 2,
"username": "sysadmin",
"employeesid": "444757996000133005",
"employeename": "SYSADMIN",
"employeeactive": true,
"employeeissysadmin": true,
"workstationid": "444758667000167217",
"databasetype": "oracle",
"seated": true,
"seatsid": "696753514011112556",
"seatedapp": "POSTMAN",
"token": "6AA19E214E7D44BEBE4A74C7A9941053",
"internal": false,
"lasttransaction": "2024-01-29T14:51:44.000-08:00",
"subsidiarysid": "444757993000014001",
"storesid": "444757993000014002",
"seasonsid": "444758236000102187",
"regionsid": "0",
"districtsid": "0",
"workstationtype": 1,
"workstation": "rkwin10_8080",
"active": true,
"storeactive": true,
"departmentname": null,
"homeurl": null,
"xforwardedfor": null,
"serveraddress": "http://rkumar-vms.retailpro.com",
"imageserveraddress": "http://rkumar-vms.retailpro.com",
"oldsbssid": null,
"oldstoresid": null,
"servertimezone": 480,
"pricelevelsid": "444758224000132171",
"hisecsbssid": "0",
"hisecemplsid": "0",
"basecurrencycodealpha": "ERO",
"basecurrencysymbol": null,
"controllernumber": 111,
"workstationnumber": 1,
"subsidiarynumber": 1,
"storenumber": 1,
"storecode": "001",
"subsidiaryname": "001",
"storename": "Seattle",
"languagesid": "444758234000192183",
"ispoa": false,
"isstore": false,
"isstandalone": true,
"tillsid": null,
"drawernumber": 1,
"employeemaxdiscperc": 100,
"countrycode": null,
"rpproductcode": "RP_PRISM_ENT",
"opendrawereventsid": null,
"basecurrencysid": "480551537010041255",
"countrysid": "444758072000127097",
"statuserrorcode": 0, <0=OK, 1=Lic Not Found, 2=Lic Not Valid, 3=No Seat Available>
"link": "/api/security/session",
"preferences": {
"activation_expiration_date_in_days": "365",
"apply_promotions_based_on_original_price": "0",
...
},
"permissions": {
"inventoryassemblekits": "ALLOW",
"allowmanualdetax": "ALLOW",
"xzoutforcecloseregister": "ALLOW",
...
},
"registersid": "0",
"registerstate": 0,
"cacheseq": 0,
"licenseinfo": {
"sid": "691445193011176764",
"productcode": "RP_PRISM_ENT",
"productversion": "2.3",
"expirationdate": "2024-07-18T16:00:00.000-08:00",
"maxstores": 110,
"maxsites": 90,
"maxseats": 101,
"issuedbyrpops": true,
"valid": true
}
}
]
Logging out of Retail Pro Prism 2.3
The logout process starts with an HTTP GET request using the following pattern:
URI: /api/security/logout
Header: Auth-Session:< a valid auth session>
Upon successful logout, the server will return the following:
Response Code: 200 - OK
NOTE: It is advised not to wait for the response 200-OK code. Nothing can be done at this point even if get any errors during logout. Alternatively, you can always kill any dangling session manually in Retail Pro Prism TTK.
Authentication for customizations in Retail Pro Prism 2.3
Retail Pro Prism 2.3 will continue (for a limited time) to support old security endpoints to perform authentication & authorization using 3-way handshaking mechanism (Auth, Sit, Stand). However, it's advised to start converting your apps/tools/plugins to adopt new security changes.
We understand that given these rules, many existing customizations would take seats. As we work toward a final solution for customization licensing (See "Beyond Retail Pro Prism 2.3" below), we are offing a temporary internal user that will not consume a seat for customization developers. The login parameters are shown below.
Username : PRISM_CUSTOM
Password : 96DFB7F740CBE63B73DB1254
Empl_Name : CUSTOM
Internal : True
Active : True
Is_Admin : False
Note:
No Groups or Permissions assigned by default. It's the user's responsibility to assign appropriate permissions before using it.
Beyond Retail Pro Prism 2.3
As the security landscape in the world changes, we need to not only ensure that clients are using the number of seats they have contracted for, but that the customizations our clients use have been validated to be legitimate and safe.
Along that line we will continue to enhance the authentication process further and plan in the future to include digital signatures for each customization using public/private encryption for communications between clients and Retail Pro Prism servers.