# (Optional) Exercise 1: Setup the web-application and Microservices locally

To run these optional exercises you need to ensure you have installed the following tools on your local machine and you can run them in your terminal sessions.

* [git 2.24.1 or higher](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [yarn 1.22.4 or higher](https://yarnpkg.com)
* [Node.js v14.6.0 or higher](https://nodejs.org/en/)
* [Apache Maven 3.6.3](https://maven.apache.org/ref/3.6.3/maven-embedder/cli.html)
* [Docker 3.0.4 or higher](https://www.docker.com/products/docker-desktop) (running Keycloak locally)
* Java 9 or higher

## Architecture

Here is the local architecture whichs shows the Web-App and the two Microservices Web-API and Articles are running on your local machine in terminal sessions. Keycloak is running on Kubernetes on IBM Cloud.

![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2Ff1798c99b5476e8cdd883ae4df98ead0bd408ad0.png?generation=1598019657937160\&alt=media)

The gif shows the logon to the example web frontend application. This is the simplified sequence which happens in the background:

1. When we invoke the web frontend on \`[http://localhost:8080](http://localhost:8080) we will be routed to login dialog provided by the Keyloak server.
2. After the successfully Keycloak authentication we will be redirected to the web frontend and the frontend gets an access-token.
3. The access-token contains the needed information for the authorization at the Java microservice Web-API and the user information.
4. The web frontend extracts and displays the username.
5. Then the web fronted uses the access-token to invoke the Web-API Microservice endpoint to get the articles and displays the Articles.

![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2Fe2b70af25ced76b6248c642fffbf15e0f93d462e.gif?generation=1603894554452740\&alt=media)

## YouTube video related to the workshop

[![](https://img.youtube.com/vi/Un8n0VMLsCs/0.jpg)](https://www.youtube.com/watch?v=Un8n0VMLsCs)

## Step 1: Clone the project to your local machine

```bash
git clone https://github.com/IBM/cloud-native-starter.git
cd cloud-native-starter/security
ROOT_FOLDER=$(pwd)
```

## **(Optional) Setup Keycloak locally**

If you have your Keycloak running on Kubernetes you just skip to [setup Web-App](#step-1-configure-web-app).

In this part we will setup Keycloak locally. We will run a local Keycloak Docker container and reuse an existing realm configuration.

The image below shows the relevant elements we will use later.

![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2F5c3433216ee2796591e6c2166b9439110b5b6ca1.png?generation=1603893936623640\&alt=media)

### Step 1: Start Keycloak Docker image local

Open the first terminal session and enter following command:

```bash
docker run -it -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8282:8080 jboss/keycloak:9.0.2
```

_Note:_ We use here

* `KEYCLOAK_USER=admin`
* `KEYCLOAK_PASSWORD=admin`
* `8282:8080` port forwarding
* `keycloak:9.0.2` container image

### Step 2: Import the existing realm configuration

1.  Open the Keycloak in a browser select the Administration Console

    Use following URL:

    ```bash
    http://localhost:8282/
    ```

    ![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2F9554cc33a57bba76c7b520abb2bcbb06f1061dfa.png?generation=1603894213489201\&alt=media)
2. Login to using the URL in your browser with `user/admin` and `password/admin`
3.  Select _Add realm_

    ![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2Fa891ebae15bb55cc15f667e2ae84e2f0f1630f09.png?generation=1603894213748815\&alt=media)
4.  Choose for import _Select file_ and open the `quarkus-realm.json`.

    ![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2F905f9b6f64b7bef012ca03346939b122f82b039e.png?generation=1603894213785227\&alt=media)

### Step 3: Press `view all users`

You should see following users: `admin`, `alice`, `jdoe`

![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2Fe9d0bd4f9888518ea985351e9930ee5cca5c5ce6.png?generation=1598017431783584\&alt=media)

### Step 4: Verify the role mapping

![](https://1980280846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MFGEw-4BAG72jtDCP4q%2Fsync%2Fc029e1031b87e413e62295b4f1be382a24bc2c2a.png?generation=1598017436567574\&alt=media)

## **Setup Web-App**

### Step 1: Configure web-app

Now insert `Keycloak URL`/auth in `main.js` (`http://localhost:8282`) and save the changes.

```bash
cd $ROOT_FOLDER/web-app/src
nano main.js
```

Example:

```javascript
if (currentHostname.indexOf('localhost') > -1) {
  urls = {
    api: 'http://localhost:8081/',
    login: 'https://YOUR_URL/auth' // insert your http or https://<KeycloakURL>/auth
  }
  store.commit("setAPIAndLogin", urls);
}
```

### Step 2: Run the web-app

Open the second terminal session and start the application on port 8080.

```bash
cd $ROOT_FOLDER/web-app
yarn install
yarn serve
```

## **Setup Web-Api**

### Step 1: Configure web-api-secure

Insert your the `auth-server-url` URL of your Keycloak instance in `application.properties` file and save the file.

Therefore you use the `Keycloak URL` you got during the setup of Keycloak on IBM Cloud.

```bash
cd $ROOT_FOLDER/web-api-secure/src/main/resources
nano application.properties
```

Example:

```java
// When running locally, uncomment the next line, add your Keycloak URL, must end on '/auth/realms/quarkus'
quarkus.oidc.auth-server-url=https://YOUR_URL/auth/realms/quarkus

quarkus.oidc.client-id=backend-service
quarkus.oidc.credentials.secret=secret

quarkus.http.port=8081
quarkus.http.cors=true

resteasy.role.based.security=true
```

### Step 2: Run the web-api-secure Microservice

Open a third terminal and start the service on port 8081.

```bash
cd $ROOT_FOLDER/web-api-secure
mvn clean package quarkus:dev
```

## **Setup Articles microservice**

### Step 1: Configure articles-secure

Insert your the `auth-server-url` URL of your Keycloak instance in `application.properties` file and save the file. Therefore you use the `Keycloak URL` you got during the setup of Keycloak on IBM Cloud.

```bash
cd $ROOT_FOLDER/articles-secure/src/main/resources
nano application.properties
```

Example:

```java
// When running locally, uncomment the next line, add your Keycloak URL, must end on '/auth/realms/quarkus'
quarkus.oidc.auth-server-url=https://YOUR_URL/auth/realms/quarkus

quarkus.oidc.client-id=backend-service
quarkus.oidc.credentials.secret=secret

quarkus.http.port=8082
quarkus.http.cors=true

resteasy.role.based.security=true
```

### Step 2: Run the articles-secure Microservice

Open a fourth terminal and start the service on port 8081.

```bash
cd $ROOT_FOLDER/articles-secure
mvn clean package quarkus:dev
```

## Open the Web-App

### Step 1: Open the Web-App in your local browser

Open the following URL in your browser:

```bash
http://localhost:8080
```

### Step 2: Log in with the test user: alice, password: alice

> Congratulations, you have successfully completed this optional hands-on lab tasks for `uthentication and Authorization with Keycloak and Quarkus` section of the workshop. Awesome :star:
