kaldesai commented on code in PR #614: URL: https://github.com/apache/incubator-kie-kogito-docs/pull/614#discussion_r1568821881
########## serverlessworkflow/modules/ROOT/pages/cloud/custom-ingress-authz.adoc: ########## @@ -0,0 +1,340 @@ += Using an Ingress to add Authentication and Authorization to Workflow Applications +:compat-mode!: +// Metadata: +:description: Securing workflow applications via a +:keywords: cloud, kubernetes, docker, image, podman, openshift, oidc, keycloak, apisix +// links +:oidc_spec_url: https://openid.net/specs/openid-connect-core-1_0.html +:kubernetes_svc_url: https://kubernetes.io/docs/concepts/services-networking/service/ +:kubernetes_networkpolicy_url: https://kubernetes.io/docs/concepts/services-networking/network-policies/ +:sonataflow_apisix_example_url: https://github.com/apache/incubator-kie-kogito-examples/tree/stable/serverless-operator-examples/sonataflow-apisix-oidc +:keycloak_resource_owner_granttype_url: https://www.keycloak.org/docs/23.0.7/securing_apps/#_resource_owner_password_credentials_flow +:apisix_install_url: https://apisix.apache.org/docs/ingress-controller/deployments/minikube/ + +This document describes how you add an Ingress to a {product_name} workflow to handle authentication and authorization use cases. + +In the approach outlined in this guide, protect your workflows from anonymous access outside the cluster with the link:{oidc_spec_url}[OpenID Connect] specification. + +Although the example demonstrated in this document is not meant to be used in production, you can use it as a reference to create your own architecture. + +== Architecture + +The following image illustrates a simplified architecture view of the recommended approach for protecting {product_name} workflow endpoints. + +image::cloud/apisix-keycloak/ingress-apisix-keycloak.png[] + +1. User makes a request with their credentials +2. APISIX do the JWT token introspection in the OIDC Server (Keycloak) +3. Keycloak validates the token +4. APISIX forwards the request to the workflow application + +This is a simplified approach for OIDC use cases. In production environments, you can tailor your gateway and OIDC server to meet your requirements and scope. + +[IMPORTANT] +==== +This approach only protects the communication via Ingress. Direct calls to the workflow application link:{kubernetes_svc_url}[internal service] would be anonymous. +For example, another microservice in the cluster making requests to the workflow internal service. +Make sure to set link:{kubernetes_networkpolicy_url}[Kuberbetes NetworkPolicies] to your workflow applications if this is not the desired behavior. +==== + +== How to Deploy the Example Architecture + +The following sections describe how to deploy the example architecture using APISIX and Keycloak to protect your {product_name} workflows. + +.Prerequisites + +* Minikube is installed. You can use Kind or any other cluster if you have admin access. Just ensure to adapt the steps below to your environment. +* link:{sonataflow_apisix_example_url}[Clone the example SonataFlow APISIX with Keycloak in a local directory]. +* (Optional) xref:cloud/operator/install-serverless-operator.adoc[{operator_name} is installed] if you are going to deploy via the operator. +* (Optional) xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-minikube.adoc[Quarkus {product_name} workflow is deployed] if you are not using the operator. + +=== Installing Keycloak + +From the example's cloned directory 'sonataflow-apisix-oidc', run the following command: + +.Running kustomize to install Keycloak +[source,shell,subs="attributes+"] +---- +kubectl create ns keycloak +kubectl kustomize manifests/bases | kubectl apply -f - -n keycloak +---- + +This command creates a namespace called `keycloak` and a Keycloak server deployment connected to a PostgreSQL database to persist your data across cluster restarts. + +==== Exposing Keycloak Locally + +[TIP] +==== +You can skip this section if you are running on OpenShift or any cluster that you can expose Keycloak via an Ingress DNS or Route. +==== + +Since Keycloak is running on Minikube, expose the service port to your local network by running the following command: + +.Exposing Keycloak to the local network +[source,shell,subs="attributes+"] +---- +kubectl port-forward $(kubectl get pods -l app=keycloak --output=jsonpath='{.items[*].metadata.name}' -n keycloak) 8080:8080 -n keycloak +---- + +From now on, every connection to the `8080` port is forwarded to the Keycloak service endpoint. + +The next step is to configure your local `/etc/hosts`. This step is needed because the token you are going to generate must come from the same URL that APISIX server introspects once you access the workflow. + +Edit your local `/etc/hosts` file and add the following line: + +.Hosts file with the Keycloak address entry +[source,txt,subs="attributes+"] +---- +127.0.0.1 keycloak.keycloak.svc.cluster.local +---- + +You can try accessing your Keycloak admin console in the address link:http://keycloak.keycloak.svc.cluster.local:8080[]. The default user and password are `admin`. + +[IMPORTANT] +==== +In real-life environments this step is not needed since Keycloak or any OIDC server is served by a load balancer with the correct address configured. +==== + +==== Configuring the Keycloak OIDC Server + +In the next step, log in to the Keycloak admin console in the address link:http://keycloak.keycloak.svc.cluster.local:8080[] using the default credentials. + +Once you are logged into the console, click on *Create realm* in the top left menu. In this screen, create a new realm named `sonataflow`. See the image below for more details: Review Comment: ```suggestion Once you are logged into the console, click *Create realm* in the top left menu. In this screen, create a new realm named `sonataflow`. See the image below for more details: ``` -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
