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-2.1.x.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-2.1.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).

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

Before you begin

Ensure that you are logged in as the administrative user to the Keycloak user interface.

Adding a new realm

1. Add a realm by following the instructions at creating a new Realm.
2. 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
3. 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:

1. In the upper right corner, click the drop-down menu.
2. Click Manage Account.
3. Enter your e-mail address.

Optional: In the Realm Settings > Theme, modify the themes used for the realm, if any.

Creating Clients

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:

Client	CLIENT_ID
Admin Studio	studio
Account Management UI	am_ui
Storefront	storefront

note

Ensure that the Admin Studio Client ID is set to studio. You cannot change this setting during the deployment time.

1. In the realm that you created in adding a new realm step, navigate to Realm Settings > Clients and click Create.

2. Enter the following settings:

   • Client ID: CLIENT_ID
   • Client Protocol: openid-connect

3. Click Save.

   The system redirects you to the new client configuration page.

4. In the new client configuration page, do the following:

   1. In the Access Type field, select confidential.
   2. 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 https://example.tld/*
   3. (Optional) In the Login Theme field, set any custom theme. Use the am_ui theme for the account management user interface.

5. Click Save.

6. Navigate to the Credentials tab and ensure that the Client Authenticator is set to Client Id and Secret.

7. Click Regenerate Secret and note the Secret and the CLIENT_ID value.

   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

1. 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.

2. Enter the username, e-mail address, password, and any required details for the user.

3. Click Save.

   The system provides the newly added seller administrator the access to the Account Management user interface.

note

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.

1. Verify that the Keycloak administration page is accessible at the Keycloak URL.

   For more information about the Keycloak URL, see the Requirements section.

2. To verify the e-mail settings, click Test Connection.

3. Navigate to the Realm > Clients page and click Base URL.

   1. In the Client ID section in the account, click the base URL.
   2. Perform authentication using the username and password of the newly added seller administrator.

Related Topics

• Keycloak server installation
• Deploy Docker containers on ECS