Account Management Deployment Overview

note

Account Management API is now deprecated and we recommend that you use Account Management functionality built into Elastic Path Commerce 8.2 and later.

Elastic Path Account Management deployment needs the following software components and its dependencies deployed and provisioned:

Account Management API: Helix REST API service that performs logical operations of Account Management service. The REST API service includes a developer tool kit, Admin studio for debugging and development of Account Management APIs.
Account Management user interface: The user interface for managing accounts in Elastic Path Account Management.
MySQL server: Storage of the Account Management data.
JMS (Java Message Service) server: Relaying messages from the Account Management API (Optional as of 2.4.2).

Prerequisites

Before deploying the Account Management service:

Ensure that you have access to the build artifact file, account-management-2.4.x.zip, at the Elastic Path Public Nexus repository.
Ensure that you have an identity provider that is compatible with OpenID Connect.

OpenID Connect requirements

The identity provider must be compatible with OpenID Connect and:

Provide Account Management with public Subject Identifiers.
Allow Account Management to authenticate using the client_secret_basic authentication method.
Allow authentication using the Authorization Code Flow.
Publish an OpenID Connect Discovery document. If your OpenID Connect provider does not support OpenID Connect Discovery, a JSON file can be created manually and hosted in a publicly accessible location. The document must have all required values listed in the specification.
Must not encrypt the ID Token or the UserInfo Endpoint response.
The ID Token generated must contain only the client id used by the Account Management service.
Must not require the use of the nonce parameter or the acr_values parameter as part of the Authentication Request.
Must not rely on the auth_time claim being validated ID Token Validation.
Return a custom claim for Account Management to determine whether the authenticated user is a seller administrator or an associate. This claim can be a JSON list or a single string value. If a list is returned, a user is only matched to a seller administrator or an associate role. All other values in the list are ignored. When you deploy the Account Management service, you can specify the key name and the matching value. A key name must have only one matching value. The following code sample shows the reference example from Section 5.3.2, augmented with a new roles key:
```
{
  "sub": "248289761001",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "preferred_username": "j.doe",
  "email": "janedoe@example.com",
  "picture": "http://example.com/janedoe/me.jpg",
  "roles": ["seller-users"]
 }
```
Use a unique email address for each user and do not use the same address for different users.

note

The identity provider must not be configured as an identity broker or participate in an identity federation. The users with the same email address from different external providers are treated as the same user in the Account Management service. This might allow users from a third party identity provider to impersonate users from a different identity provider.

Additional Prerequisites for Deploying to AWS

Ensure that Elastic Path Commerce 7.5.0 or later version is deployed with Elastic Path CloudOps for AWS (Amazon Web Services) 3.3.x.
Ensure that the domain names for storefronts that utilize Account Management functionality are available.

Requirements

Docker

A computer with Docker installed, for building docker images.

JWT RS256 private and public key pair

A key pair is required to enable secure communication between Elastic Path Commerce and the Account Management service. Elastic Path recommends using openssl to generate the key. However, you can use any mechanism to generate the RS256 key.

Encode the private key in the following sequence:

Validate JWT Key

The following example shows a command that validates that the token is in the correct format:

$ echo $JWT_AUTH_PRIVATE_KEY \
  | openssl enc -d -A -base64 \
  | openssl pkcs8 -nocrypt -inform DER -outform DER  \
  | openssl rsa -check -noout -inform DER
RSA key ok

The token in this example is stored in the JWT_AUTH_PRIVATE_KEY variable.

Example JWT Key Generation

The following command generates an example private and public key pair in the format required by the Account Management service and Elastic Path Commerce:

#Create temp directory
TMPDIR=$(mktemp -d --suffix=encryption-key)

#Generate JWT Key in PKCS8 format
openssl genpkey -out $TMPDIR/jwtRS256.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048

#Generate Public Key in PEM format
openssl rsa -in $TMPDIR/jwtRS256.key -pubout -outform PEM -out $TMPDIR/jwtRS256.key.pub

#Output format
echo "
AM_AUTH_JWT_PRIVATE_KEY=$(cat $TMPDIR/jwtRS256.key | grep -v "^----" | tr -d "\n")

AM_AUTH_JWT_PUBLIC_KEY=$(cat $TMPDIR/jwtRS256.key.pub | grep -v "^-----" | tr -d "\n")
"

# Delete keys from disk
rm $TMPDIR/jwtRS256.key $TMPDIR/jwtRS256.key.pub

# Delete directory
rmdir $TMPDIR

note

The default Docker Compose deployment includes an example JWT private key in the environment variables. You must not use the example key in production.

Additional Requirements Deploying to AWS

New DNS records

A DNS record for accessing the Account Management user interface. The primary entry point and landing page for the users. This domain name is visible to end-users.
A DNS record for accessing the Account Management API. The Hypermedia REST endpoints that are used by the user interface, store fronts, and touchpoints. Developers and system administrators can access the Account Management studio using this domain name.

SSL certificates

Two SSL certificates for the Account Management user interface and Account Management API.

MySQL compatible server

For Account Management data storage. Elastic Path supports the following services:

MySQL 5.7 on Amazon RDS (Relational Database Service)
Amazon Aurora RDS (MySQL 5.6-compatible)

JMS server

An ActiveMQ JMS server is required for Account Management to send messages about events in the system.