- Ensure that all requirements described in the Requirements section are met
- Ensure that you have the URLs for the Account Management user interface, the Account Management API, and Keycloak
- Ensure that the SMTP server details are available
- Ensure that the URLs of all storefronts that will utilize the Account Management service are available
- Ensure that you have access to the
account-management-2.2.x.zipfile in the Elastic Path Public Nexus repository
- Ensure that Updating Elastic Path Commerce is complete
- Ensure that the custom branding for the storefronts or the Account Management user interface are available
You can use any method to deploy Keycloak. For the deployment, Elastic Path recommends using the Keycloak docker file in the
account-management-2.2.x.zip file that is based on the
jboss/keycloak:4.8.3.Final docker image. This Docker image includes a theme corresponding to the Account Management user interface. Other themes can be included and the docker image can be deployed via the Amazon ECS (Elastic Container Service).
By default, Keycloak is configured to run in standalone mode. Additional configuration changes are required to run multiple instances in a load balanced environment. For more information, see the Keycloak documentation.
Keycloak recommends that you configure a dedicated RDBMS system and not use the built in database. Keycloak requires SSL/TLS support to work. Elastic Path recommends using an external proxy, such as, an Amazon ELB (Elastic Load Balancer), to terminate the SSL. If you use the included Docker container, you must set the
PROXY_ADDRESS_FORWARDING environment variable to
true when using an Amazon ELB to terminate SSL.
Before you begin
Ensure that you are logged in as the administrative user to the Keycloak user interface.
Adding a new realm
- Add a realm by following the instructions at creating a new Realm.
- In the new realm, go to Realm Settings > Login page and verify the following settings:
- User Registration: OFF
- Edit user name: OFF
- Login with email: ON
- In the Realm Settings > Email field page, enter the necessary configuration values for the SMTP server.
Important: If you get the
Logged in User does not have an e-mail error when you click Test Connection, do the following:
- In the upper right corner, click the drop-down menu.
- Click Manage Account.
- Enter your e-mail address.
Optional: In the Realm Settings > Theme, modify the themes used for the realm, if any.
You must create clients for the admin studio, account management user interface, and any storefronts. This section describes creating clients by replacing the
CLIENT_ID with the client identifier that you use.
You must use the following client IDs:
|Account Management UI|
Note: Ensure that the Admin Studio Client ID is set to
studio. You cannot change this setting during the deployment time.
In the realm that you created in adding a new realm step, navigate to Realm Settings > Clients and click Create.
Enter the following settings:
- Client ID:
- Client Protocol:
- Client ID:
The system redirects you to the new client configuration page.
In the new client configuration page, do the following:
- In the Access Type field, select confidential.
- In the Valid Redirect URIs filed, enter the URLs used by the Account Management user interface, admin studio, and storefronts.
For a URL hosted at
https://example.tld/, enter a URL with a wildcard
- (Optional) In the Login Theme field, set any custom theme.
am_uitheme for the account management user interface.
Navigate to the Credentials tab and ensure that the Client Authenticator is set to Client Id and Secret.
Click Regenerate Secret and note the Secret and the
This value is used during the deployment of the client. For an example, see the Deploy API Service - Docker Image Environment Variables section.
Creating a Seller Administrator
In the new realm, click Users > Add user
Important: A seller administrator account is required to use Account Management functionality and is necessary to validate subsequent steps.
Enter the username, e-mail address, password, and any required details for the user.
The system provides the newly added seller administrator the access to the Account Management user interface.
Note the value of ID in the Details tab of the newly created account.
Validating Keycloak deployment
Use this procedure to validate the Keycloak deployment.
Verify that the Keycloak administration page is accessible at the Keycloak URL.
For more information about the Keycloak URL, see the Requirements section.
To verify the e-mail settings, click Test Connection.
Navigate to the Realm > Clients page and click Base URL
- In the Client ID section in the account, click the base URL.
- Perform authentication using the username and password of the newly added seller administrator.