Introduction

This document is valid from ICM 12.1.

For previous versions, refer to Concept - Integration of Progressive Web App and Responsive Starter Store (valid to 12.0) and Concept - Integration of Progressive Web App and Responsive Starter Store (valid from 7.10.32.16).

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 (e.g., product listing), but also elements of the Responsive Starter Store (for example, checkout) are to be used together in a project.

References

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. Consider the following settings:

General:
In the appserver.properties, the following property must be configured:
appserver.properties
```
intershop.apitoken.cookie.enabled=true
```
Site-specific:
The same property intershop.apitoken.cookie.enabled=true has to be set in the domain-specific configuration of the site.

Implementation

The PWA must have cookies enabled. If so, 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, the 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 in to 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	Description	Type	Mandatory/Optional	Default value
`intershop.apitoken.cookie.enabled`	If `true`, the feature is enabled (cookie is set).	boolean	optional	`false`
`intershop.apitoken.cookie.name`	The name of the cookie to be used.	string	optional	`apiToken`
`intershop.apitoken.cookie.maxage`	The maximum age of the cookie in minutes.	integer	optional	`60` (same as session timeout)
`intershop.apitoken.cookie.sslmode`	If `true`, the `secure` attribute of the cookie is set, so the cookie will only be submitted if the transport is secure (SSL/TLS).	boolean	optional	`true`
`intershop.apitoken.cookie.samesite`	Defines the `SameSite` attribute of the cookie. If the Responsive starter store is hosted using a different domain than the PWA, this property needs to be set to `none` to allow both applications to access the cookie.	enum (one of {`strict`,`lax`,`none`})	optional	`strict`

Hint for Customization

Pipeline Calls / Log in and Out

The UserLogin pipeline is called. On 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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents