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 a 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 with:

• Username and password
• Anonymous user
• Basic authentication
• Refresh token

The response contains a set of tokens that should be used to authenticate subsequent requests. Along with identity (ID) tokens 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 specified in the token set response. ID tokens and access tokens can no longer be used after this expiration time.

Implicit Token Creation

Every REST endpoint supports authentication using basic authentication. To authenticate the client, send the user's credentials with the Authorization header, which contains the word Basic followed by a space and a base64-encoded string username:password.
The response of such a request includes a header authentication-token which contains the user token. If the server does not support JSON Web Token (JWT), 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 tokens as user tokens, implicit token creation should not be used because the token will not renew.

Token Creation Endpoint

This API can be used to create access tokens and ID tokens that clients can use 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

• A user is logged in via the client with user 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, see 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 user is logged out by the client (this causes the refresh tokens to expire):

  curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/logout -X PUT -H "Authorization:Basic <REFRESH_TOKEN>"

This section covers the processing of an identity JSON web token. This allows clients to explicitly create users or customers associated with identity providers.

This section covers operations related to identity provider configurations.

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 the 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 the organization Operations:

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

This section covers operations that allow clients to retrieve public keys used by the server.

ICM JWT tokens are signed following the RFC7515: the private part of a key pair is used to create a signature for the actual token payload. So the payload's validity (payload is unmodified and the origin is known) can be checked using the public key.
The ICM creates key pairs on demand: whenever a token is generated and there's no key stored (in memory) which is not timed out.
Attention: before requesting at least 1 token there will be no public key available (see resource https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token).

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"
        }
      ]
    }

Parse and Verify an ID Token

The 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/";
    }

}