This page details out all options to authenticate a API client to the Shop.
Inhaltsverzeichnis #
- Versions
- Regular Session-Based Logon
- Logon using HTTP Basic Auth
- Logon using Cookie-based authentication
- PCG-Application Logon
- Response
- Logon Results
- Sample Code
- sample Interaction Diagram for Basic Auth
While some data of an online-Shop is publicly visible, most of the data is tailored for individual customers. Therefore, a early logon is strongly required for the business model behind these shops to work efficiently. Test this with Login!
All Logon methods establish a session that is valid with a timeout of one hour or until a logout. The session id is handed over as cookie in the response headers. SSL is strongly recommended for this call, as the password is transmitted. Subsequent calls carry the session id, which might be vulnerable too, depending on the usage context.
Depending on the usage, logon should be with the credentials of the end user. For administrative applications, an operator should be authenticated. A operator has always a negative userid (below -100).
Versions# #
logon1, since 2010, changes response to JSON
logon2, since 25.8.20. adds version information to the response, if the user has higher permissions in the system
Regular Session-Based Logon # #
<urlbase>/api/logon?cid=<userid>&pass=<password> <urlbase>/api/logon?guest=true <urlbase>/start?cid=<userid>&pass=<password>
These are older options (legacy), not to be used for new implementations:
<urlbase>/logon?cid=<userid>&pass=<password> <urlbase>/s3/exec.jsp?action=Logon&cid=<userid>&pass=<password> <urlbase>/s3/start.jsp?action=Logon&cid=<userid>&pass=<password>
The last two variants do not only logon, but also retrieve the data as described under API.methods.start useridThe Userid used to logon for a given shop. Beside the real id, that can be the email address and for some shops the name of the user.passwordThe password.guest=trueThis session is marked as being from a guest. Use this variant, if you need to execute methods for an otherwise unknown caller (e.g. a new registration).
Sample Session using wget
prompt>wget --save-cookies cookies.txt --load-cookies cookies.txt --keep-session-cookies -q -O - "http://oekobox-online.de/v3/shop/bosshamerschhof/logon?cid=-102&pass=xxxxxx" ...logon result message here... prompt>wget --save-cookies cookies.txt --load-cookies cookies.txt --keep-session-cookies -q -O - "http://oekobox-online.de/v3/shop/bosshamerschhof/ ...tour list here...
Response:
{
"action": "Logon",
"result": "ok",
"pcgifversion":" 2020-08-20",
"shopversion":"6.0.165/2.0.1"
}
Logon using HTTP Basic Auth# #
This is useful to save one network round trip. This mechanism transfers the user credentials a HTTP Header as part of the request. As with the other logon option, a session cookie is returned. See sample code below.
The image below shows the difference to the regular interaction as shown here.
<urlbase>/s3/exec.jsp?action=Logon&ba <urlbase>/s3/start.jsp?action=Logon&ba
The request parameter ba triggers the basic auth mechanism. The latter example combines the authentication with data fetching as described in API.methods.start.
Note that many browsers cache the information provided to this mechanism at least until the browser is shut down.
Logon using Cookie-based authentication# #
This is a long term authentication cookie (that has nothing to do with the session cookie). This is comparable to the option „stay connected“ in the user interface. The initial installation of the cookie is best done with the browser ui (i.e. when the user is logged on anyway)
The caller may install him/herself a cookie with credential data. This will then allow a on-the-fly logon without further interactive challenge. For programmatic clients, this option might be useful if they simulate a browser-like behavior.
The cookie itself can be installed from within an authenticated session, e.g. from the profile page in the online shop.
<urlbase>/s3/exec.jsp?action=Logon&ca <urlbase>/s3/start.jsp?action=Logon&ca
The request parameter ca triggers the basic auth mechanism. The latter example combines the authentication with data fetching as described in API.methods.start.
PCG-Application Logon# #
Back-end applications may call functionality by including the wpass parameter into any request. Its value needs to be valid and is a result of prior back-end data exchange. wpass a random value, that needs to be obtained from prior database request (using the authenticated database connection).
Response# #
{action: "Logon", result: "<result>"}
Logon Results# #
| ok | expected result. The response should carry a cookie header with the sessionid (jsessionid) |
| relogon | repeated logon attempt for a still valid session |
| guest | Pseudo Logon as „Guest“ |
| no_data | no data was provided, no authentication |
| empty | shop is not yet loaded with data, no authentication possible |
| no_such_user | User can not be identified |
| duplicate_user | attempt to authenticate by email, but email exists multiple times in system, acess denied |
| wrong_password | Wrong Password |
| blocked | User Account temporarily blocked |
| tblocked | Calling IP Address temporarily blocked |
| token_too_old | Logon token too old (usually a mail logon) |
| wrong_token | Token wrong |
| use_id | Logon by email is impossible; use a custoemer id |
| token_session | Token was not created by this session |
Valid good responses are marked bold
Sample Code# #
This is groovy code.
String urlbase = ....
HttpClient httpclient = ...
// build the auth string acc. to HTTP Basic Auth rules
String b64AuthString = "Basic " + (userid + ":" + passwd).bytes.encodeBase64(); // assumes a suitable encoding
println "Using this authentcation header: $b64AuthString"
// now lets go for the first screen, using the BA variant
String startUrl = urlbase + "/s3/start.jsp?action=Logon&ba"
gm = Util.getGet(startUrl) // utility, provides a "get" method object
responseCode = httpClient.executeMethod(gm)
assert responseCode==401, "We should get an error here, Authentication required"
// lets try with authentication
gm.addRequestHeader("authorization", b64AuthString)
responseCode = httpClient.executeMethod(gm)
assert responseCode == 200, "regular fine response is 200, 401 is a wrong u/p "
sample Interaction Diagram for Basic Auth# #
