aldettinger commented on code in PR #511:
URL:
https://github.com/apache/camel-quarkus-examples/pull/511#discussion_r3332924338
##########
amq-broker-keycloak/README.adoc:
##########
@@ -0,0 +1,552 @@
+= AMQ Broker and Keycloak Integration: A Camel Quarkus example
+:cq-example-description: An example that demonstrates integration of AMQ
Broker with Keycloak security using REST and SOAP endpoints
+
+{cq-description}
+
+TIP: Check the
https://camel.apache.org/camel-quarkus/latest/first-steps.html[Camel Quarkus
User guide] for prerequisites
+and other general information.
+
+== Overview
+
+This example demonstrates how to integrate Apache ActiveMQ Artemis (AMQ
Broker) with Keycloak authentication in a Camel Quarkus application.
+The application provides both REST and SOAP endpoints that are secured using
Keycloak authentication policies.
+
+The example includes:
+
+* *REST endpoint* for order submission (`/api/orders/submit`) - requires
authentication
+* *REST endpoint* for admin operations (`/api/admin/users`) - requires
authentication and admin role
+* *SOAP endpoint* for inventory management (`/services/inventory`) - secured
with Keycloak
+* *JMS integration* using AMQ Broker to process orders asynchronously via
`order-queue`
+* *Keycloak component* for user management and authentication
+
+== Prerequisites
+
+The example application requires both a Keycloak instance and an AMQ Broker
(Apache ActiveMQ Artemis) instance.
+
+You do not need to provide these instances yourself as long as you play with
the example code in dev mode
+(a.k.a. `mvn quarkus:dev`) - read more
https://quarkus.io/guides/getting-started#development-mode[here]
+or as long as you only run the supplied tests (`mvn test`).
+In those situations, Quarkus tooling automatically starts both Keycloak and
Artemis containers for you via
+https://quarkus.io/guides/security-openid-connect-dev-services[Quarkus Dev
Services] and
+https://docs.quarkiverse.io/quarkus-artemis/dev/index.html#_dev_services[Artemis
Dev Services],
+and it also configures the application so that you do not need to touch
anything in `application.properties`.
+
+[[users-configuration]]
+
+=== Users configuration
+
+In all scenarios which we will cover, we will need two users:
+- *customer* (with role `customer-role` and password `customer-pass`) - can
submit orders
+- *admin* (with role `admin-role` and password `admin-pass`) - can submit
orders and access admin endpoints
+
+WARNING: These hardcoded credentials are for demonstration purposes only and
should never be used in production.
+
+=== Quarkus OIDC
+
+We use the approach described in
https://quarkus.io/guides/security-openid-connect-client-reference[Quarkus Open
ID Connect]
+to protect the application with Keycloak as our OIDC provider. This
automatically secures our
+Camel Quarkus routes using the `keycloakPolicy` policy defined in the
application.
+
+== Start in Development mode
+
+=== Run the app with Dev Services
+
+Run the application in development mode. Quarkus will automatically start
Keycloak and AMQ Broker containers:
+
+[source,shell]
+----
+$ mvn clean compile quarkus:dev
+----
+
+The above command compiles the project, starts the application, and starts
both Keycloak and AMQ Broker instances via Dev Services.
+The Quarkus tooling watches for changes in your workspace. Any modifications
in your project will automatically take effect
+in the running application.
+
+TIP: Please refer to the Development mode section of
+https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode[Camel
Quarkus User guide] for more details.
+
+Now you can move on to the <<playground>> section with the assumption that
`KEYCLOAK_URL=http://localhost:8082` and `APP_URL=http://localhost:8080`.
+
+[[playground]]
+
+=== Playground
+
+The first thing to do is to obtain the Bearer token from the running Keycloak
instance for each created user. Save those tokens for further authentication.
+
+For the `customer` user, extract value from response of key `access_token` and
call it `CUSTOMER_TOKEN`:
+
+[source,shell]
+----
+$ curl -d "client_id=quarkus-client" -d "client_secret=secret" -d
"username=customer" -d "password=customer-pass" -d "grant_type=password"
$KEYCLOAK_URL/realms/quarkus/protocol/openid-connect/token
+----
+
+For the `admin` user, extract value from response of key `access_token` and
call it `ADMIN_TOKEN`:
+
+[source,shell]
+----
+$ curl -d "client_id=quarkus-client" -d "client_secret=secret" -d
"username=admin" -d "password=admin-pass" -d "grant_type=password"
$KEYCLOAK_URL/realms/quarkus/protocol/openid-connect/token
+----
+
+Now we are ready to try the HTTP endpoints:
+
+==== Submit an order (authenticated endpoint)
+
+The `customer` user can submit orders (you should receive `200 OK` and the
order will be sent to the JMS queue):
+
+[source,shell]
+----
+$ curl -i -X POST -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type:
application/json" \
+ -d
'{"orderId":"ORDER-001","customerId":"CUST-001","productId":"PRODUCT-001","quantity":5}'
\
+ $APP_URL/api/orders/submit
+----
+
+The `admin` user can also submit orders:
+
+[source,shell]
+----
+$ curl -i -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type:
application/json" \
+ -d
'{"orderId":"ORDER-002","customerId":"CUST-002","productId":"PRODUCT-002","quantity":10}'
\
+ $APP_URL/api/orders/submit
+----
+
+Without authentication, the request should fail (you should receive `401
Unauthorized`):
+
+[source,shell]
+----
+$ curl -i -X POST -H "Content-Type: application/json" \
+ -d
'{"orderId":"ORDER-003","customerId":"CUST-003","productId":"PRODUCT-003","quantity":3}'
\
+ $APP_URL/api/orders/submit
+----
+
+==== Access admin endpoint (authorized endpoint)
+
+The `customer` user cannot access admin endpoints (you should receive `403
Forbidden`):
+
+[source,shell]
+----
+$ curl -i -X GET -H "Authorization: Bearer $CUSTOMER_TOKEN"
$APP_URL/api/admin/users
+----
+
+The `admin` user can access admin endpoints (you should receive `200 OK` with
a list of Keycloak users):
+
+[source,shell]
+----
+$ curl -i -X GET -H "Authorization: Bearer $ADMIN_TOKEN"
$APP_URL/api/admin/users
+----
+
+==== SOAP Inventory Service
+
+The SOAP endpoint is available at `/services/inventory` and is also secured
with Keycloak authentication.
+You can test it using a SOAP client tool like SoapUI or curl with SOAP
envelope:
+
+[source,shell]
+----
+$ curl -i -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type:
text/xml" \
+ -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/";>
+ <soap:Body>
+ <tns:UpdateStockRequest xmlns:tns="http://acme.org/inventory";>
+ <productId>PRODUCT-001</productId>
+ <quantity>5</quantity>
+ </tns:UpdateStockRequest>
+ </soap:Body>
+ </soap:Envelope>' \
+ $APP_URL/services/inventory
+----
+
+Expected response:
+[source,xml]
+----
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/";>
+ <soap:Body>
+ <ns2:UpdateStockResponse xmlns:ns2="http://acme.org/inventory";>
+ <success>true</success>
+ <message>Stock updated successfully</message>
+ <newStock>95</newStock>
+ </ns2:UpdateStockResponse>
+ </soap:Body>
+</soap:Envelope>
+----
+
+[[external-instances-configuration]]
+
+== Prerequisites for externally running Keycloak and AMQ Broker instances
+
+For the next steps, we need to have externally running Keycloak and AMQ Broker
instances.
+
+=== Run Keycloak
+
+You can start a Keycloak instance easily via Docker:
+
+[source,shell]
+----
+$ docker run --name keycloak_amq_demo -p 8082:8080 \
+ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
+ quay.io/keycloak/keycloak:latest \
+ start-dev
+----
+
+=== Configure the Keycloak realm
+
+Then go to `http://localhost:8082/` click on `Administration Console` and
login with `admin:admin`.
+
+Create a new realm named `quarkus` with the following configuration:
+
+*Create a client:*
+- Client ID: `quarkus-client`
+- Client authentication: On
+- Direct access grants: Enabled
+- Client secret: `secret`
+
+*Create two roles:*
+- `customer-role`
+- `admin-role`
+
+*Create two users:*
+- Username: `customer`, Password: `customer-pass`, Email:
`[email protected]`, Role: `customer-role`
+- Username: `admin`, Password: `admin-pass`, Email: `[email protected]`, Role:
`admin-role`
+
+IMPORTANT: For each user, you must set:
+- Email address (required - without it you'll get "Account is not fully set
up" error)
+- Email verified: On
+- Password: Set as non-temporary
+- Assign the appropriate role
+
+TIP: Make sure to enable direct access grants for the client to support
password grant type.
+
+=== Run AMQ Broker (Apache ActiveMQ Artemis)
+
+You can start an AMQ Broker instance via Docker:
+
+[source,shell]
+----
+$ docker run --name artemis_amq_demo -d -p 61616:61616 -p 8161:8161 \
+ -e AMQ_USER=admin -e AMQ_PASSWORD=admin \
+ quay.io/artemiscloud/activemq-artemis-broker:latest
Review Comment:
For docker related commande lines, maybe pinning to explicit versions would
be preferred to `latest` ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
