IntershopICM - 7.10 - Authentication 1.0.0

Authentication (1.0.0)

Download OpenAPI specification:Download

This is Intershop ICM REST API documentation.

This reference lists the REST API for storefront development. The REST API covers features of both, the B2C (SMB - Small and Medium-sized businesses) and the B2B storefront development. This reference is intended for developers who want to make use of an easy-to-use API when developing frontend solutions. You can find more information at Intershop Communications. Contact our Intershop experts at Support - Intershop Communications

Introduction

This API is documented in OpenAPI format.

Authentication

basicAuth

Basic access authentication. In basic authentication, a request contains a header field in the form of authorization: Basic <credentials>, where credentials is the Base64 encoding of ID and password joined by a single colon :.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

authToken

User authentication token to authenticate the request. The token is a string generated by the ICM server in the same header in every response of an REST endpoint.

Security Scheme Type API Key
Header parameter name: authentication-token

bearerAuth

Bearer token authentication. A request contains a header field in the form of authorization: Bearer <token>, where is a string generated by an authentication service in response to a login request.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Authentication Protocol: Identity Tokens

Authentication of REST-Requests

Several API operations require an authenticated user. Intershop ICM REST API supports authentication using:

  • token endpoint (supports password grant, refresh-token grant, client-authentication grant via basic authentication or bearer token)
  • basic authentication
  • header authentication-token

Authentication via Token

Tokens are encoded or signed strings that can be used to authenticate a REST request. Tokens are submitted using the header Authorization containing the word Bearer followed by space and the token string. Alternatively the header authentication-token containing the user token can be used.

Token Creation via Token Endpoint

The token endpoint is used to create tokens that are used in subsequent requests as authentication token. The user can authenticate using:

  • username and password
  • anonymous user
  • basic authentication
  • refresh token The response will contain a set of tokens that should be used to authenticate subsequent requests. Along with ID- and access-tokens a refresh token is returned. Use the received refresh token to renew expired tokens to authenticate further requests. Along with the token expiration times are given in the token set response. ID and access tokens cannot be used after this expiration time.

Implicit Token Creation

Every REST endpoint supports authentication using basic authentication. To authenticate the client sends the users credentials with the header Authorization that contains the word Basic followed by space and a base64-encoded string username:password. The response of such a request includes a header authentication-token containing the user token. If the server does not support JWT (JSON Web Token) each response of REST request will contain the header authentication-token which should replace former tokens since it contains an updated expiration time.

Note: REST endpoints that support Web-Adapter-cached responses cannot be used for implicit token creation.
If the server supports JWT token as user token implicit token creation should not be used because the token will not renew.

Token Creation Endpoint

This API can be used to create access and identity tokens which allow clients to securely call protected APIs. Clients request tokens that can be used in the 'Authorization' header so the server grants access to a particular resource which will be invoked in the context of the encoded user-identity.

Example Use Case

  • Client logs in a user with name and password. The client uses the received ID-token for subsequent requests and stores the refresh-token for further use:
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&organization=<ORGANIZATION>" 
  • The client renews the ID-token using the refresh-token if its expired or about to expire: Creates a set of token based on a refresh token:
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>
  • The client logs out the user (this will expire refresh-tokens):
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/logout -X PUT -H "Authorization:Basic <REFRESH_TOKEN>"

Creates a new set of tokens.

Token Creation

Creates a set of tokens. The given authorization grant determines for which identity the tokens get created. Following authorization grants are supported:

Authorization Grants

Anonymous

Creates a set of tokens for an anonymous user. Example call with no form data:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST

alternatively the grant_type can be submitted:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=anonymous"

Password

Creates a set of tokens for a user that authenticates via user name and password (and organization, defaults to the sites default organization):

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&organization=<ORGANIZATION>"

Client Credentials

Creates a set of tokens for a user that authenticates using e.g. basic authentication (user name and password given Base64 encoded USERNAME:PASSWORD, here: admin:!InterShop00!):

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=client_credentials&organization=<ORGANIZATION>" -H "Authorization:Basic YWRtaW46IUludGVyU2hvcDAwIQ=="

Refresh Token

Creates a set of token based on a refresh token:

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>
Request Body schema: application/x-www-form-urlencoded
Any of
  • Anonymous User Grant
  • Password Grant
  • Refresh Token Grant
  • Client Credentials Grant
grant_type
string
Value: "anonymous"

the grant type. If set to anonymous a new token for an anonymous user will be created

Responses

200

OK

400

Bad request

401

Unauthorized

post/token

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id_token": "string",
  • "access_token": "string",
  • "refresh_token": "string",
  • "expires_in": 0,
  • "refresh_expires_in": 0,
  • "token_type": "bearer"
}

Logs out the current user.

Logs out the current user. All (refresh) tokens issued for this user will expire and invalidated.

Responses

204

No content

401

Unauthorized

put/logout

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/logout

Identity Provider Configurations

Identity Provider Configurations End Point

Identity providers are used to authenticate users. Clients can use this endpoint in order to receive all identity providers that are available for an organization. Typically, this information can be used to enable a user to log on to the ICM back office or the storefront. There might be different types of identity providers. The type local is used for the standard internal ICM user login handling which is most often represented by a login form and completely handled by ICM server. However, other types include oidc for OpenID Connect compatible providers which can be used for single sign-on scenarios.

Example Usage

The following example shows how to retrieve identity providers for organization Operations:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/identityproviderconfigurations/Operations

Returns a list of identity provider configurations

This operation returns the identity providers that are available for an organization.

path Parameters
organizationKey
required
string

The key of organization

query Parameters
providerType
string

The provider type. If used only matching configurations will be returned.

Responses

200

OK

404

Not found

get/identityproviderconfigurations/{organizationKey}

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/identityproviderconfigurations/{organizationKey}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Returns an identity provider configuration

This operation returns the identity providers that are available for an organization.

path Parameters
organizationKey
required
string

The key of organization

providerKey
required
string

The key of the configuration

Responses

200

OK

404

Not found

get/identityproviderconfigurations/{organizationKey}/{providerKey}

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/identityproviderconfigurations/{organizationKey}/{providerKey}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "key": "uniqueKey",
  • "name": "display name",
  • "type": "local"
}

Captcha

get captcha code

Responds with script snippet containing CAPTCHA challenge. Workflow:

  • Send a request to a protected resource.
  • Detect the status 401 Authorization required.
  • Determine the authentication scheme and the necessary parameters.
  • Display the CAPTCHA a human user can solve.
  • Re-send the request including the CAPTCHA challenge and solution. At least on CAPTCHA service must be configured as enabled for the application/site. Otherwise the resource will return an error.

Responses

200

OK

500

Internal Server Error response headers will include required fields: RequiredFields: recaptcha_challenge_field,recaptcha_response_field

get/captcha

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/captcha

Credentials

Update login

Updates the login of the currently logged in user with a new one.

path Parameters
CustomerKey
required
string
Example: ExampleKey

The key or UUID to resolve a single item

Request Body schema:
name
string

The name of an element.

login
string

the login used for authentication

Responses

204

No content

400

Bad request possible values for header error-key:

  • customer.credentials.missing_fields.error
  • customer.credentials.invalid_fields.error
401

Unauthorized

put/customers/{CustomerKey}/credentials/login

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/customers/{CustomerKey}/credentials/login

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "string",
  • "login": "pmiller@test.intershop.de"
}

Update password

Updates the password of the currently logged in customer with a new one.

path Parameters
CustomerKey
required
string
Example: ExampleKey

The key or UUID to resolve a single item

Request Body schema:
name
string

The name of an element.

password
string

new password

currentPassword
string

current password

Responses

204

No content

400

Bad request possible values for header error-key:

  • customer.credentials.missing_fields.error
  • customer.credentials.invalid_fields.error
401

Unauthorized

put/customers/{CustomerKey}/credentials/password

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/customers/{CustomerKey}/credentials/password

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "string",
  • "password": "InterShop00",
  • "currentPassword": "!InterShop00!"
}

Update security question

Updates the security question of the currently logged in customer. The key of the security question should be submitted. A client could get the list of possible keys from /securiry/questions resource.

path Parameters
CustomerKey
required
string
Example: ExampleKey

The key or UUID to resolve a single item

Request Body schema:
name
string

The name of an element.

type
string

The type of the object. This is normally a constant that can be used to differentiate objects by their type.

text
string

the text of the security question

key
string

the key of the security question

Responses

204

No content

400

Bad request

401

Unauthorized

put/customers/{CustomerKey}/credentials/question

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/customers/{CustomerKey}/credentials/question

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "string",
  • "type": "SecurityQuestion",
  • "text": "What is your pet's name?",
  • "key": "account.security_question.pet_name.text"
}

Security

Update password

Updates the password of the currently logged in customer with a new one.

path Parameters
CustomerKey
required
string
Example: ExampleKey

The key or UUID to resolve a single item

Request Body schema:
name
string

The name of an element.

password
string

new password

currentPassword
string

current password

Responses

204

No content

400

Bad request possible values for header error-key:

  • customer.credentials.missing_fields.error
  • customer.credentials.invalid_fields.error
401

Unauthorized

put/customers/{CustomerKey}/credentials/password

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/customers/{CustomerKey}/credentials/password

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "string",
  • "password": "InterShop00",
  • "currentPassword": "!InterShop00!"
}

Update security question

Updates the security question of the currently logged in customer. The key of the security question should be submitted. A client could get the list of possible keys from /securiry/questions resource.

path Parameters
CustomerKey
required
string
Example: ExampleKey

The key or UUID to resolve a single item

Request Body schema:
name
string

The name of an element.

type
string

The type of the object. This is normally a constant that can be used to differentiate objects by their type.

text
string

the text of the security question

key
string

the key of the security question

Responses

204

No content

400

Bad request

401

Unauthorized

put/customers/{CustomerKey}/credentials/question

Intershop ICM Server

/INTERSHOP/rest/{serverGroup}/{siteName}/{appUrl}/customers/{CustomerKey}/credentials/question

Request samples

Content type
Copy
Expand all Collapse all
{
  • "name": "string",
  • "type": "SecurityQuestion",
  • "text": "What is your pet's name?",
  • "key": "account.security_question.pet_name.text"
}

Reset password of registered user.

If the client submits a valid user ID and secure code then password of the related user will be reset to the provided new password value. User ID and secu