AWS Marketplace

{{toc}}

# Usage Instructions

## Getting started

1. Launch the product via 1-Click

2. Use a web browser to access the Admin console at: https://[ec2-ip]:8443, where [ec2_ip] is the public ip provided by Amazon for your instance.

3. Log in using the following credentials:

   * Username: admin

   * Password: the instance_id of the instance

You can also access your instance via SSH using the username and your Amazon private key.

The **username** depends on the operative system:

* Centos 9 Stream: 'ec2-user'

* Other Centos: 'centos'

* Ubuntu: 'ubuntu'

* Rocky Linux: 'rocky'

## Installation details

### Keycloak installed with wildfly distribution

In versions prior to 19.0.1, we install Keyckloak embedded within the wildfly application server

The configuration files are located inside the embedded WildFly, that is, in the directory $KEYCLOAK_HOME where KEYCLOAK_HOME is /usr/java/keycloak.

For more details on the installation, you can refer to the documentation at https://www.keycloak.org/docs/latest/server_installation/index.html

### Keycloak installed with the Quarkus distribution.

From version 19.0.1, we install Keycloak with Quarkus as the distribution with WildFly is deprecated.

The configuration file is located in the directory $KEYCLOAK_HOME/conf/keycloak.conf where $KEYCLOAK_HOME is /usr/java/keycloak.

For more details on the installation, you can refer to the documentation at https://www.keycloak.org/docs/latest/server_installation/index.html

### TLS configuration in Keycloak

By default, we have created a self-signed certificate using Java Keystore so it's not validated by any authority (by default, the Keycloak server looks for the file $KEYCLOAK_HOME/conf/server.keystore).

If you want to obtain a valid certificate, you will need to request one from a certificate authority and make the necessary changes in Keycloak.

### Service configuration

Server service is configured with systemd.

The Keycloak service is in /etc/systemd/system/keycloak.service, which indicates whether to start Keycloak in development or production mode:

* If you have chosen Keycloak with H2, the service will start in development mode: ExecStart=/usr/java/keycloak/bin/kc.sh start-dev

* If you have chosen Keycloak with MySQL or PostgreSQL, the service is started for production mode: ExecStart=/usr/java/keycloak/bin/kc.sh start

View status server:

``` shell

[centos@ip-172-31-9-232 etc]$ sudo systemctl status keycloak

```

Stop server:

``` shell

[centos@ip-172-31-9-232 etc]$ sudo systemctl stop keycloak

```

Start server:

``` shell

[centos@ip-172-31-9-232 etc]$ sudo systemctl start keycloak

```

### Data persistence modes

**H2 (Default)**

Keycloak comes with its own embedded Java-based relational database called H2. Usually recommended for development environments, for production environments it is recommended to work with better relational databases.

We provide also this product with MySQL or PostgreSQL.

**MySQL**

Keycloak is configured with a MySQL database.

**PostgreSQL**

Keycloak is configured with a PostgreSQL database.

#### MySQL

View service status:

``` shell

$ sudo systemctl status  mysql

```

Stop service:

``` shell

$ sudo systemctl stop mysql

```

Start service:

``` shell

$ sudo systemctl start mysql

```

Access the MySQL console from your terminal:

``` shell

$ sudo mysql

```

#### PostgreSQL

View service status:

``` shell

$ sudo systemctl status  postgresql

```

Stop service:

``` shell

$ sudo systemctl stop postgresql

```

Start service:

``` shell

$ sudo systemctl start postgresql

```

Access the MySQL console from your terminal:

``` shell

$ sudo -u postgres psql

```

## Other useful data

**Location of sensitive information**

All the information is saved in the database.

In MySQL the data folder is /var/lib/mysql

In PostgreSQL the data folder is /var/lib/pgsql/data

**Encryption configuration**

There is no encrypted data.

**Changing system credentials**

To change the Kecycloak credentials you have to go to the menu on the right, users, credentials and press the reset button.

**Instructions on how the user interacts with Keycloak to decrypt necessary data**

You can use the Keycloak management console to view all necessary data.

**How to assess and monitor the health and proper function of the application.**

1. Navigate to your Amazon EC2 console and verify that you're in the correct region.

2. Choose Instance and select your launched instance.

3. Select the server to display your metadata page and choose the Status checks tab at the bottom of the page to review if your status checks passed or failed.

## Additional resources

* https://www.keycloak.org/

* https://www.keycloak.org/server/enabletls 

* https://www.keycloak.org/server/configuration