This document describes the authentication mechanism if punchout is used as identity provider.
If you need an introduction to this topic, read the Authentication Concept first.
The PWA must be configured in a specific way to use punchout as an identity provider.
Apart from the enabled punchout feature flag, the following configuration can be added to the Angular CLI environment.ts files for development purposes:
features: [
'punchout'
],
identityProvider: 'Punchout',
identityProviders: {
'Punchout': {
type: 'PUNCHOUT',
}
},Warning
This configuration enables the Punchout identity provider as the one and only configured global identity provider, meaning the standard ICM identity provider used for the standard login is no longer configured and the standard login will no longer work.
As mentioned above, this configuration example is only relevant for punchout development purposes.
For production-like deployments, the PWA has to be configured to use the Punchout identity provider only when the user enters the punchout route.
This can be configured with the OVERRIDE_IDENTITY_PROVIDERS environment variable (see Override Identity Providers by Path) for the NGINX container.
Nevertheless, the SSR process needs to be provided with the punchout identity provider configuration as one of the available identity providers.
In this way, the global identityProvider configuration is left to be the default ICM configuration.
The following is a sample punchout identity provider configuration for docker-compose that enables the punchout identity provider on the punchout route only.
pwa:
environment:
IDENTITY_PROVIDERS: |
Punchout:
type: PUNCHOUT
nginx:
environment:
OVERRIDE_IDENTITY_PROVIDERS: |
.+:
- path: /punchout
type: PunchoutExample for the configuration via PWA Helm Chart 1.0.0 or later:
app:
env:
- name: IDENTITY_PROVIDERS
value: |
{
"Punchout": {"type": "PUNCHOUT"}
}
proxy:
env:
- name: OVERRIDE_IDENTITY_PROVIDERS
value: |
.+:
- path: /punchout
type: PunchoutImportant
The OVERRIDE_IDENTITY_PROVIDERS matching pattern (in the example .+) must exactly match a MULTI_CHANNEL matching pattern, or it can be configured as a RegEx that matches several MULTI_CHANNEL matching patterns.
proxy:
env:
- name: OVERRIDE_IDENTITY_PROVIDERS
value: |
.+:
- path: /punchout
type: Punchout
multiChannel: |
.+:
- baseHref: /en
channel: default
lang: en_US
- baseHref: /de
channel: default
lang: de_DE
- baseHref: /fr
channel: default
lang: fr_FR
- baseHref: /b2c
channel: default
theme: b2cFor the OCI punchout, the PWA submits the basket to the HOOK_URL given as query parameter at login.
To prevent script injection via this form target, the PWA checks the scheme of the HOOK_URL before logging in, the same way as the ICM checks the OCI return URL.
The HOOK_URL has to start with an allowed scheme; leading whitespace or control characters are not allowed.
By default, http, https, and sapevent (used by SAP systems for catalogs embedded in the SAP GUI) are allowed.
To change the allowed schemes, configure the hookUrlSchemes property of the punchout identity provider, e.g., to allow only https, so that the basket data is never transferred unencrypted.
If hookUrlSchemes is empty, the default is used.
The script schemes javascript, data, and vbscript are never allowed, even if they are configured.
If the HOOK_URL is not valid, the user is not logged in, the HOOK_URL is not stored, and the error page is displayed.
pwa:
environment:
IDENTITY_PROVIDERS: |
Punchout:
type: PUNCHOUT
hookUrlSchemes:
- httpsExample for the configuration via PWA Helm Chart 1.0.0 or later:
app:
env:
- name: IDENTITY_PROVIDERS
value: |
{
"Punchout": {
"type": "PUNCHOUT",
"hookUrlSchemes": ["https"]
}
}Note
The host of the HOOK_URL is not restricted.
The Content Security Policy directive form-action restricts the targets of the punchout basket transfer in the browser.
The default form-action 'self' https: blocks HOOK_URLs with the schemes http and sapevent.
To support them for the OCI punchout, add the schemes to the directive, e.g., form-action 'self' https: http: sapevent:.
A user can log in by navigating to the /punchout or /login route.
For this purpose, specific query params need to be added to the given route depending on whether the OCI or the cXML punchout should be used.
For the OCI punchout login, the user needs to add the HOOK_URL, USERNAME and PASSWORD as query parameters, while the cXML user has to include the sid and access-token.
In addition, the cXML punchout tester could be used to log in a cXML punchout user.
The request /customers/${CustomersKey}/punchouts/cxml1.2/setuprequest to create a new cXML punchout session must be inserted as the URL with the credentials of the cXML punchout user.
When the session is created successfully, the punchout tester will redirect to the ICM configured PWA deployment /punchout route.
There is currently no possibility to register a new punchout user in the PWA.
Each authentication token has a predefined lifetime.
That means, the token has to be refreshed to prevent it from expiring.
Once 75% of the token's lifetime have passed ( this time can be configured in the oAuth library), an info event is emitted.
This event is used to call the refresh mechanism setupRefreshTokenMechanism$ of the oAuth configuration service and the authentication token will be renewed.
Hence, the token will not expire as long as the user keeps the PWA open in the browser.
When the user logs out by clicking the logout link or navigating to the /logout route, the configured logout() function will be executed, which will call the revokeApiToken() user service in order to deactivate the token on server side.
Besides this, the PWA removes the token and basket-id on browser side, fetches a new anonymous user token, and sets it as apiToken cookie.
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 Website, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.