Introduction
This document is valid from ICM 7.10.32.16-LTS and 7.10.38-9-LTS to 12.0.
For previous versions, refer to Concept - Integration of Progressive Web App and Responsive Starter Store (valid to 7.10.32.15).
For newer versions, refer to Concept - Integration of Progressive Web App and Responsive Starter Store.
The API token login feature enables customers to log in to both the Progressive Web App (PWA) or any other REST-based client and the Responsive Starter Store.
This feature can be useful if certain elements of the PWA (for example, product listing), but also elements of the Responsive Starter Store (for example, checkout) should be used together in a project.
References
- Overview - Intershop Progressive Web App
- Overview - Cookie Handling
- PWA Hybrid Approach Documentation in GitHub
Glossary
| Term | Description |
|---|---|
| ICM | The abbreviation for Intershop Commerce Management |
| PWA | The abbreviation for Progressive Web App |
Activation
The API token login can be enabled generally or domain-specifically. Therefore consider the following settings:
General:
In the appserver.properties, the following property must be configured:appserver.propertiesintershop.apitoken.cookie.enabled=true
- Site-specific:
The same propertyintershop.apitoken.cookie.enabled=truehas to be set in the domain-specific configuration of the site.
Implementation
The PWA must have cookies enabled. If this is the case, a cookie is written when the ICM application server processes a request (page is not cached by the web adapter).
The cookie named apiToken contains a JSON object with the API token.
The attribute 'isAnonymous' indicates the authentication state:
'true'for anonymous users'false'for authenticated users
When the ICM starts handling a request and the cookie is present, ICM ensures that the user is logged in or an anonymous basket is retrieved.
For technical reasons, ICM overwrites the PWA cookie with its own cookie. The difference is that another JSON attribute is added, which is called creator='icm'.
If the user is logged into the ICM but no cookie is available when the ICM takes over, the user will be logged out.
Note
This feature is based on the assumption that PWA and ICM can read and write each other's cookies. That means that both cookies must have the same domain and the same path. Therefore, this feature only works if PWA and ICM are running in the same domain.
ICM Cookie Handling
When does ICM write the cookie?
- The feature is active and the ICM application server processes a request.
When does ICM delete the cookie?
- The feature is active and the token inside the cookie is invalid.
The detailed workflow is as follows:
Configuration
| Key | Value |
|---|---|
| intershop.apitoken.cookie.enabled | 'true', if the feature should be active, otherwise anything else. |
| intershop.apitoken.cookie.name | If the cookie should not be named 'apiToken', set an alternative name here. |
| intershop.apitoken.cookie.maxage | The maximum age of the cookie. Since our session is 60 minutes long, the default is 60. |
| intershop.apitoken.cookie.comment | The API allows to set a comment, which can be set here. |
| intershop.apitoken.cookie.sslmode | 'true', if the cookie should be SSL-only. The feature will not work if ICM or PWA still use HTTP. |
Hint for Customization
Pipeline Calls / Log in and Out
The pipeline UserLogin is called. For the login, the start-node LoginUser is called. For the logout, the start-node Logout is called.
This pipeline does what is done for login and logout in the platform. In f_business, the pipeline is overwritten to call the pipelines for ProcessUser .
If there are additional tasks in customer projects when a user is logged in, further overwriting may be necessary.