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, send 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 the 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 it is expired or about to expire:
  Creates a set of tokens 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>"

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

Identity JSON Web Token Processing

Processes an identity JSON web token. Allows clients to explicitly create users or customers associated with identity providers.

Public Keys

ICM JWT tokens are signed using keys. An asymmetric signature uses a public/private key pair. A signature that was generated with a private key can be verified with the public key.
This API allows clients to get the public keys the server uses.

Examples

Get all public keys:

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

---
Example Response:
    {
      "keys": [
        {
          "kty": "OKP",
          "use": "sig",
          "crv": "Ed25519",
          "kid": "FUCsFd.hcIIAAAFzAEx5sJAu",
          "x": "AeasbZjilrI2pnlJ6gH91BbBP_1CdTQl0EaU_Wr1G6Y"
        },
        {
          "kty": "OKP",
          "use": "sig",
          "crv": "Ed25519",
          "kid": "rA.sFd.hIswAAAFzwEp5sJAu",
          "x": "8Vpyz4Y95iZpz88HKh2xtgRgYMh8Rj-4zXpI6LNtJPU"
        }
      ]
    }

Following Java code shows how an ID-token can be parsed and verified:

import java.text.ParseException;
import java.util.Objects;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.MediaType;

import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.crypto.Ed25519Verifier;
import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jwt.SignedJWT;

/**
 * This example illustrates how to verify an ID-token that was signed using a private key.
 */
public class VerifyTokenExample
{
    /**
     * Verifies a signed token using the JSON web-key from the tokens header.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKinHeader(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()) && null != header.getJWK())
        {
            // get key from header and verify
            return jwt.verify(new Ed25519Verifier(header.getJWK()
                            .toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved by the key URI from the tokens header.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromJKU(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()) && null != header.getJWKURL())
        {
            // read the key, URI should be present in claim 'jku'
            String key = ClientBuilder.newClient()
                            .target(header.getJWKURL())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWK jwk = JWK.parse(key);

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved using the 'keys'-endpoint.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromKeysWithKidResource(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()))
        {
            // read the key from the keys resource
            String key = ClientBuilder.newClient()
                            .target(getKeysURI())
                            // add key id
                            .path(header.getKeyID())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWK jwk = JWK.parse(key);

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved using the 'keys'-endpoint.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromKeysResource(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()))
        {
            // read the key from the keys resource
            String keys = ClientBuilder.newClient()
                            .target(getKeysURI())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWKSet jwkSet = JWKSet.parse(keys);

            JWK jwk = Objects.requireNonNull(jwkSet.getKeyByKeyId(header.getKeyID()),
                            "Could not resolve key with id " + header.getKeyID());

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    String getKeysURI()
    {
        return "https://localhost/INTERSHOP/rest/WFS/inSPIRED/-/keys/";
    }

}