Deploying and Configuring Keycloak
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.
- 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-1.0.0.zip
file 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
Deploy Keycloak
You can use any method to deploy Keycloak. For the deployment, Elastic Path recommends using the Keycloak docker file in the account-management-1.0.0.zip
file that is based on the jboss/keycloak:4.7.0.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).
Note: 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.
Configure Keycloak
You will need to be logged in as the administrative user to the Keycloak user interface in order to apply the configurations mentioned below.
Add a new realm
Add a realm by following the instructions at creating a new Realm.
- In the new realm, go to "Realm Settings > Login" and verify the following settings:
- User Registration: OFF
- Edit user name: OFF
- Login with email: ON
- In the "Realm Settings > Email field", 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 applicable
- Important: If you get the
Create a client
Create a client that will be used by the Account Management API, UI and storefronts, by performing the following actions:
- In the realm that was created, Navigate to "Realm Settings > Clients" and click Create
- Enter the following settings:
- Client ID: eam
- Client Protocol: openid-connect
- Click Save
- The system redirects you to the new client configuration
- In the new client configuration page, enter the following settings:
- Access Type: confidential
- Valid Redirect URIs: The URLs used by the Account Management UI, Admin Studio, and Store Fronts. For a URL hosted at
https://example.tld/
, enter a URL with a wildcardhttps://example.tld/*
- Click Save
Create a Seller Administrator
- While in Keycloak, Navigate to the Credentials tab and ensure that the Client Authenticator is set to Client Id and Secret
- Click Regenerate Secret and save the value for future use
- The system uses this client for the communication between the API and Keycloak
- In the new realm, add a seller administrator by clicking "Users > Add user"
- Important: A seller administrator account is required to use Account Management functionality and is necessary to validate subsequent steps
- Enter username, e-mail, password, and any required details for the user
- The system provides this user access to the Account Management user interface
- Click Save
- Note: Make note of the value of ID in the Details tab of the newly created account.
Validate Keycloak deployment
Use this procedure to a validation of Keycloak deployment.
- Verify that the Keycloak administration page is accessible at the Keycloak URL.
- For more information about the Keycloak URL, see the Infrastructure Requirements
- Verify the e-mail settings by clicking "Test Connection"
- Navigate to "Realm > Clients" and click Base URL
- In the Client ID section of the account, click the Base URL
- Authenticate using the username and password of the newly added seller administrator