From b0e19f1b6665b7d4c165a94a88295e318b96aab9 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 30 Jan 2023 15:16:16 -0500 Subject: [PATCH 01/25] adding contributing file Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 90 +--------------------------------------------- 2 files changed, 95 insertions(+), 89 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9d9524ba --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,94 @@ +# Contributing + +## Development: Building and pushing + +The binary and container can be built with the following command, replacing the container tag with the desired container tag of choice. + + +This makes the tornjak agent + spire 1.1.3 server container: + +``` +CONTAINER_BACKEND_WITH_SPIRE_TAG=tsidentity/tornjak-spire-server:latest make container-tornjak-be-spire +``` + +The container is run with the same arguments as the SPIRE server image, and usage is transparent. It runs a server hosted on port 10000 accessed via http. A different spire version may be specified within the first line of the [Dockerfile.add-frontend](./Dockerfile.add-frontend#L1) file. Currently, SPIRE versions <= 1.4.0 are compatible with Tornjak. + +Alternatively, pre-built Tornjak images can be found at `gcr.io/spiffe-io/tornjak-spire-server:{version}`, where the specified tag denotes the supported SPIRE server version, as listed in the [SPIRE_BUILD_VERSIONS](./SPIRE_BUILD_VERSIONS) document. + +### Testing and validating the Tornjak front-end +To start a local version of the Tornjak front-end server +point at the running Tornjak APIs: + +```console +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http:/// npm start +``` + +Assuming `npm` is installed, this will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +### Running the Tornjak Manager +Once you have a Tornjak agent running, you may run the Tornjak manager by locally running + +``` +go run tornjak-backend/cmd/manager/manager.go +``` + +which starts listening on port 50000. To start the manager UI, run: + +``` +REACT_APP_API_SERVER_URI=http://localhost:50000/ +REACT_APP_TORNJAK_MANAGER=true npm start +``` + +In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. + +## Enable User Management +User Management prevents un-authorized access to Tornjak and SPIRE APIs. +For more information on enabling the User Management and Keycloak configuration, +please check [docs/keycloak-configuration.md](docs/keycloak-configuration.md) document. + +First, start Keycloak instance locally: + +``` +docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev +``` + +Keycloak instance will start listening port on 8080 + +Next, start the Tornjak with Auth service: + +``` +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http://localhost:10000/ +REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start +``` + +To build the frontend on a container as a separate image: + +Note: Make sure CONTAINER_TAG_FRONTEND point at your directory, as tsidentity can only be used for pulling but not pushing. + +``` +CONTAINER_TAG_FRONTEND=tsidentity/tornjak-fe:latest +make container-frontend-push +``` + +## User Management Disabled + +To test build image locally, run: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' tsidentity/tornjak-fe:latest +``` + +Alternatively, to run the image with the authentication/authorization enabled on the local Keycloak instance, run: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest +``` + +This will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +Depending on the user used to signin, there will be two different views. +An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. diff --git a/README.md b/README.md index cc39e62e..6e0daaa8 100644 --- a/README.md +++ b/README.md @@ -34,93 +34,5 @@ For more details of the components and execution plan, please refer to these doc ## Development: Building and pushing -The binary and container can be built with the following command, replacing the container tag with the desired container tag of choice. +To request features or report bugs, please use [Github Issues](https://github.com/spiffe/tornjak/issues). To get started on development, please see [CONTRIBUTING](./CONTRIBUTING.md) - -This makes the tornjak agent + spire 1.1.3 server container: - -``` -CONTAINER_BACKEND_WITH_SPIRE_TAG=tsidentity/tornjak-spire-server:latest make container-tornjak-be-spire -``` - -The container is run with the same arguments as the SPIRE server image, and usage is transparent. It runs a server hosted on port 10000 accessed via http. A different spire version may be specified within the first line of the [Dockerfile.add-frontend](./Dockerfile.add-frontend#L1) file. Currently, SPIRE versions <= 1.4.0 are compatible with Tornjak. - -Alternatively, pre-built Tornjak images can be found at `gcr.io/spiffe-io/tornjak-spire-server:{version}`, where the specified tag denotes the supported SPIRE server version, as listed in the [SPIRE_BUILD_VERSIONS](./SPIRE_BUILD_VERSIONS) document. - -### Testing and validating the Tornjak front-end -To start a local version of the Tornjak front-end server -point at the running Tornjak APIs: - -```console -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http:/// npm start -``` - -Assuming `npm` is installed, this will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. - -### Running the Tornjak Manager -Once you have a Tornjak agent running, you may run the Tornjak manager by locally running - -``` -go run tornjak-backend/cmd/manager/manager.go -``` - -which starts listening on port 50000. To start the manager UI, run: - -``` -REACT_APP_API_SERVER_URI=http://localhost:50000/ -REACT_APP_TORNJAK_MANAGER=true npm start -``` - -In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. - -## Enable User Management -User Management prevents un-authorized access to Tornjak and SPIRE APIs. -For more information on enabling the User Management and Keycloak configuration, -please check [docs/keycloak-configuration.md](docs/keycloak-configuration.md) document. - -First, start Keycloak instance locally: - -``` -docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev -``` - -Keycloak instance will start listening port on 8080 - -Next, start the Tornjak with Auth service: - -``` -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http://localhost:10000/ -REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start -``` - -To build the frontend on a container as a separate image: - -Note: Make sure CONTAINER_TAG_FRONTEND point at your directory, as tsidentity can only be used for pulling but not pushing. - -``` -CONTAINER_TAG_FRONTEND=tsidentity/tornjak-fe:latest -make container-frontend-push -``` - -## User Management Disabled - -To test build image locally, run: - -``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' tsidentity/tornjak-fe:latest -``` - -Alternatively, to run the image with the authentication/authorization enabled on the local Keycloak instance, run: - -``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest -``` - -This will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. - -Depending on the user used to signin, there will be two different views. -An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. From 5aa6c743336dd8f7beccd57cd9322891a11508a5 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 30 Jan 2023 15:21:33 -0500 Subject: [PATCH 02/25] removed old tutorial Signed-off-by: Maia Iyer --- README.md | 2 +- docs/spire-quickstart.md | 206 --------------------------------------- 2 files changed, 1 insertion(+), 207 deletions(-) delete mode 100644 docs/spire-quickstart.md diff --git a/README.md b/README.md index 6e0daaa8..ce5b85ef 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This can be thought about as a central management plane for identities across SP ## Get Started The following are guides on how to try out Tornjak: -- [Tornjak simple deployment with SPIRE k8s quickstart](docs/spire-quickstart.md) +- [Tornjak simple deployment with SPIRE k8s quickstart](docs/tornjak-quickstart.md) Here are a few additional resources: - [Tornjak basic functions demo](https://www.youtube.com/watch?v=dOdRu4psKJ8) diff --git a/docs/spire-quickstart.md b/docs/spire-quickstart.md deleted file mode 100644 index 6aa6be04..00000000 --- a/docs/spire-quickstart.md +++ /dev/null @@ -1,206 +0,0 @@ -# Tornjak simple deployment with SPIRE k8s quickstart - -In this tutorial, we will show how one can try out tornjak with a SPIRE deployment using the SPIRE k8s quickstart tutorial. As we will see, this is as simple as setting up SPIRE, and replacing the image with the Tornjak compatible image for the SPIRE server. A walkthrough of this guide is also available through [video](https://youtu.be/24VQtKgi4Zc) - -## Step 1: Setup SPIRE k8s quickstart tutorial (optional) - -For this tutorial we will utilize the SPIRE k8s quickstart deployment for a SPIRE deployment. If you have a SPIRE deployment set up already, you may skip this step and go ahead to the [section: configuring Tornjak](#step-2-configuring-tornjak). If not we will use the [SPIRE quickstart for Kubernetes](https://spiffe.io/docs/latest/try/getting-started-k8s/). - -### Setting up k8s - -For this tutorial, we will use minikube, if you have an existing kubernetes cluster, feel free to use that. - -``` -➜ ~ minikube start -😄 minikube v1.12.0 on Darwin 11.2 -🎉 minikube 1.18.1 is available! Download it: https://github.com/kubernetes/minikube/releases/tag/v1.18.1 -💡 To disable this notice, run: 'minikube config set WantUpdateNotification false' -✨ Automatically selected the docker driver. Other choices: hyperkit, virtualbox -👍 Starting control plane node minikube in cluster minikube -🔥 Creating docker container (CPUs=2, Memory=1989MB) ... -🐳 Preparing Kubernetes v1.18.3 on Docker 19.03.2 ... -🔎 Verifying Kubernetes components... -🌟 Enabled addons: default-storageclass, storage-provisioner -🏄 Done! kubectl is now configured to use "minikube" - -➜ ~ kubectl get nodes -NAME STATUS ROLES AGE VERSION -minikube Ready master 79s v1.18.3 -``` - - -### Setting up the SPIRE deployment - -Next, we will follow the steps from the [SPIRE quickstart for Kubernetes](https://spiffe.io/docs/latest/try/getting-started-k8s/), for the most accurate information, follow the instructions from the page to get your SPIRE deployment set up. Follow through with the tutorial till you get to the end, but do not tear down the components! The output would look like the following: - -``` -➜ ~ git clone git@github.com:spiffe/spire-tutorials.git -Cloning into 'spire-tutorials'... -remote: Enumerating objects: 65, done. -remote: Counting objects: 100% (65/65), done. -remote: Compressing objects: 100% (49/49), done. -remote: Total 725 (delta 20), reused 52 (delta 16), pack-reused 660 -Receiving objects: 100% (725/725), 1008.46 KiB | 9.08 MiB/s, done. -Resolving deltas: 100% (327/327), done. - -➜ ~ cd spire-tutorials/k8s/quickstart - -➜ quickstart git:(master) kubectl apply -f spire-namespace.yaml -namespace/spire created - -➜ quickstart git:(master) kubectl apply \ - -f server-account.yaml \ - -f spire-bundle-configmap.yaml \ - -f server-cluster-role.yaml -serviceaccount/spire-server created -configmap/spire-bundle created -clusterrole.rbac.authorization.k8s.io/spire-server-trust-role created -clusterrolebinding.rbac.authorization.k8s.io/spire-server-trust-role-binding created - -➜ quickstart git:(master) kubectl apply \ - -f server-configmap.yaml \ - -f server-statefulset.yaml \ - -f server-service.yaml -configmap/spire-server created -statefulset.apps/spire-server created -service/spire-server created - -➜ quickstart git:(master) kubectl get statefulset --namespace spire -NAME READY AGE -spire-server 1/1 26s - -➜ quickstart git:(master) kubectl apply \ - -f agent-account.yaml \ - -f agent-cluster-role.yaml -serviceaccount/spire-agent created -clusterrole.rbac.authorization.k8s.io/spire-agent-cluster-role created -clusterrolebinding.rbac.authorization.k8s.io/spire-agent-cluster-role-binding created - -➜ quickstart git:(master) kubectl apply \ - -f agent-configmap.yaml \ - -f agent-daemonset.yaml -configmap/spire-agent created -daemonset.apps/spire-agent created - -➜ quickstart git:(master) kubectl get daemonset --namespace spire -NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE -spire-agent 1 1 1 1 1 19s - -➜ quickstart git:(master) kubectl exec -n spire spire-server-0 -- \ - /opt/spire/bin/spire-server entry create \ - -spiffeID spiffe://example.org/ns/spire/sa/spire-agent \ - -selector k8s_sat:cluster:demo-cluster \ - -selector k8s_sat:agent_ns:spire \ - -selector k8s_sat:agent_sa:spire-agent \ - -node -Entry ID : 03d0ec2b-54b7-4340-a0b9-d3b2cf1b041a -SPIFFE ID : spiffe://example.org/ns/spire/sa/spire-agent -Parent ID : spiffe://example.org/spire/server -Revision : 0 -TTL : default -Selector : k8s_sat:agent_ns:spire -Selector : k8s_sat:agent_sa:spire-agent -Selector : k8s_sat:cluster:demo-cluster - -➜ quickstart git:(master) kubectl exec -n spire spire-server-0 -- \ - /opt/spire/bin/spire-server entry create \ - -spiffeID spiffe://example.org/ns/default/sa/default \ - -parentID spiffe://example.org/ns/spire/sa/spire-agent \ - -selector k8s:ns:default \ - -selector k8s:sa:default -Entry ID : 11a367ab-7095-4390-ab89-34dea5fddd61 -SPIFFE ID : spiffe://example.org/ns/default/sa/default -Parent ID : spiffe://example.org/ns/spire/sa/spire-agent -Revision : 0 -TTL : default -Selector : k8s:ns:default -Selector : k8s:sa:default - -➜ quickstart git:(master) kubectl apply -f client-deployment.yaml -deployment.apps/client created - -➜ quickstart git:(master) kubectl exec -it $(kubectl get pods -o=jsonpath='{.items[0].metadata.name}' \ - -l app=client) -- /bin/sh -/opt/spire # /opt/spire/bin/spire-agent api fetch -socketPath /run/spire/sockets/agent.sock -Received 1 svid after 8.8537ms - -SPIFFE ID: spiffe://example.org/ns/default/sa/default -SVID Valid After: 2021-04-06 20:13:02 +0000 UTC -SVID Valid Until: 2021-04-06 21:13:12 +0000 UTC -CA #1 Valid After: 2021-04-06 20:12:20 +0000 UTC -CA #1 Valid Until: 2021-04-07 20:12:30 +0000 UTC - -/opt/spire # -``` - - -## Step 2: Configuring Tornjak - -Now that we have the SPIRE deployment set up, it should be fairly simple to use Tornjak. - -### Replacing the SPIRE server image - -We first need to use the Tornjak image. This can be done by modifying the image in the SPIRE server deployment: - - -``` -➜ quickstart git:(master) cat server-statefulset.yaml -... - spec: - serviceAccountName: spire-server - containers: - - name: spire-server - image: ghcr.io/spiffe/spire-server:1.4.4 - args: - - -config - - /run/spire/config/server.conf - ports: - - containerPort: 8081 -... -``` - -We want to replace the image with the Tornjak image: `ghcr.io/spiffe/tornjak-spire-server:1.4.4` - -``` -➜ quickstart git:(master) cat server-statefulset.yaml -... - spec: - serviceAccountName: spire-server - containers: - - name: spire-server - image: ghcr.io/spiffe/tornjak-spire-server:1.4.4 - args: - - -config - - /run/spire/config/server.conf - ports: - - containerPort: 8081 -... -``` - -We can then apply the changes of the statefulset deployment: - -``` -➜ quickstart git:(master) ✗ kubectl apply -f server-statefulset.yaml -statefulset.apps/spire-server configured -``` - -We will then wait and verify that the `spire-server-0` pod is now started with the new image: - -``` -➜ quickstart git:(master) ✗ kubectl -n spire describe pod spire-server-0 | grep "Image:" - Image: ghcr.io/spiffe/tornjak-spire-server:1.0.0 -``` - -### Connecting to the Tornjak UI - -The Tornjak HTTP server is running on port 10000 on the port. This can easily be accessed by performing a local port forward using `kubectl`. This will cause the local port 10000 to proxy to the Tornjak HTTP server. - -``` -➜ quickstart git:(master) ✗ kubectl -n spire port-forward spire-server-0 10000:10000 -Forwarding from 127.0.0.1:10000 -> 10000 -Forwarding from [::1]:10000 -> 10000 -``` - -Open a browser to `http://localhost:10000` and you should now be able to start using the Tornjak UI! - -![tornjak-ui](rsrc/tornjak-ui.png) From da0f3dd1bb0acf158e3c78e30bb5e6c20440ada9 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 30 Jan 2023 15:33:54 -0500 Subject: [PATCH 03/25] small descriptions for supported images Signed-off-by: Maia Iyer --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index ce5b85ef..0ae51d6f 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,11 @@ This can be thought about as a central management plane for identities across SP ## Get Started +We have published prebuilt images for the components of Tornjak. We currently support three images: +- [Tornjak Backend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-be): This image can be deployed as a sidecar with any SPIRE server. +- [Tornjak Manager](https://github.com/spiffe/tornjak/pkgs/container/tornjak-manager): A container that runs this image exposes a port to register multiple Tornjak backends and forward typical commands to multiple Tornjak backends from one API. +- [Tornjak Frontend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-fe): This image is typically deployed after the Tornjak Backend or Manager are deployed, as it requires a URL to connect directly to the Tornjak backend API. + The following are guides on how to try out Tornjak: - [Tornjak simple deployment with SPIRE k8s quickstart](docs/tornjak-quickstart.md) From 49a557b1f4849c979738379abbbe78616dae9098 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 30 Jan 2023 16:54:49 -0500 Subject: [PATCH 04/25] moved prebuilt image description to CONTRIBUTING Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++------------------ README.md | 5 ----- 2 files changed, 36 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d9524ba..7f283706 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,34 @@ # Contributing -## Development: Building and pushing +- Pre-built images +- Building + - discuss makefile targets +- Usage + - link to doc with config files + command line arguments + - Perhaps the UserManagement part lives here too +- Development + - link to architecture of codebase +- Testing + - frontend local testing section -The binary and container can be built with the following command, replacing the container tag with the desired container tag of choice. +## Pre-built images +We have published prebuilt images for the components of Tornjak. We currently support three images: +- [Tornjak Backend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-be): This image can be deployed as a sidecar with any SPIRE server. +- [Tornjak Manager](https://github.com/spiffe/tornjak/pkgs/container/tornjak-manager): A container that runs this image exposes a port to register multiple Tornjak backends and forward typical commands to multiple Tornjak backends from one API. +- [Tornjak Frontend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-fe): This image is typically deployed after the Tornjak Backend or Manager are deployed, as it requires a URL to connect directly to the Tornjak backend API. -This makes the tornjak agent + spire 1.1.3 server container: +NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in the same container, but these were recently deprecated. Images other than those above are NOT currently supported. -``` -CONTAINER_BACKEND_WITH_SPIRE_TAG=tsidentity/tornjak-spire-server:latest make container-tornjak-be-spire -``` - -The container is run with the same arguments as the SPIRE server image, and usage is transparent. It runs a server hosted on port 10000 accessed via http. A different spire version may be specified within the first line of the [Dockerfile.add-frontend](./Dockerfile.add-frontend#L1) file. Currently, SPIRE versions <= 1.4.0 are compatible with Tornjak. +## Building Executables and Images -Alternatively, pre-built Tornjak images can be found at `gcr.io/spiffe-io/tornjak-spire-server:{version}`, where the specified tag denotes the supported SPIRE server version, as listed in the [SPIRE_BUILD_VERSIONS](./SPIRE_BUILD_VERSIONS) document. +Building Tornjak can be done with the Makefile. Notable make targets follow: +- `make bin/tornjak-backend`: makes the Go executable of the Tornjak backend +- `make bin/tornjak-manager`: makes the Go executable of the Tornjak manager +- `make ui-agent`: makes the ReactJS app for the Tornjak frontend +- [TODO](TODO) include containerized images -### Testing and validating the Tornjak front-end -To start a local version of the Tornjak front-end server -point at the running Tornjak APIs: - -```console -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http:/// npm start -``` - -Assuming `npm` is installed, this will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. +Once built, a container may be run as is described in USAGE [TODO](TODO). ### Running the Tornjak Manager Once you have a Tornjak agent running, you may run the Tornjak manager by locally running @@ -43,6 +46,19 @@ REACT_APP_TORNJAK_MANAGER=true npm start In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. +Alternatively, one may also run these components in a container. + +### Testing and validating the Tornjak frontend +To start a local version of the Tornjak frontend, one must have a point at the running Tornjak APIs: + +```console +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http:/// npm start +``` + +Assuming `npm` is installed, this will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + ## Enable User Management User Management prevents un-authorized access to Tornjak and SPIRE APIs. For more information on enabling the User Management and Keycloak configuration, diff --git a/README.md b/README.md index 0ae51d6f..ce5b85ef 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,6 @@ This can be thought about as a central management plane for identities across SP ## Get Started -We have published prebuilt images for the components of Tornjak. We currently support three images: -- [Tornjak Backend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-be): This image can be deployed as a sidecar with any SPIRE server. -- [Tornjak Manager](https://github.com/spiffe/tornjak/pkgs/container/tornjak-manager): A container that runs this image exposes a port to register multiple Tornjak backends and forward typical commands to multiple Tornjak backends from one API. -- [Tornjak Frontend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-fe): This image is typically deployed after the Tornjak Backend or Manager are deployed, as it requires a URL to connect directly to the Tornjak backend API. - The following are guides on how to try out Tornjak: - [Tornjak simple deployment with SPIRE k8s quickstart](docs/tornjak-quickstart.md) From fd09cd19e7ba2dc4e6d71b343e300983f90897c3 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 1 Feb 2023 16:44:07 -0500 Subject: [PATCH 05/25] added link to codebase architecture Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f283706..600ec4df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,13 +22,21 @@ NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in ## Building Executables and Images -Building Tornjak can be done with the Makefile. Notable make targets follow: +Building Tornjak from scratch can be done with the Makefile. Notable make targets follow: - `make bin/tornjak-backend`: makes the Go executable of the Tornjak backend - `make bin/tornjak-manager`: makes the Go executable of the Tornjak manager - `make ui-agent`: makes the ReactJS app for the Tornjak frontend - [TODO](TODO) include containerized images -Once built, a container may be run as is described in USAGE [TODO](TODO). +## Usage + +Once built or pulled, a container may be run as is described in our usage document + +## Development + +There are code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). + + ### Running the Tornjak Manager Once you have a Tornjak agent running, you may run the Tornjak manager by locally running From 69631f0b372c857112e56d448d63d046b34768c1 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 10:22:27 -0500 Subject: [PATCH 06/25] added usage document Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 11 +---------- USAGE.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 10 deletions(-) create mode 100644 USAGE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 600ec4df..bc3e5a0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,12 +13,7 @@ ## Pre-built images -We have published prebuilt images for the components of Tornjak. We currently support three images: -- [Tornjak Backend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-be): This image can be deployed as a sidecar with any SPIRE server. -- [Tornjak Manager](https://github.com/spiffe/tornjak/pkgs/container/tornjak-manager): A container that runs this image exposes a port to register multiple Tornjak backends and forward typical commands to multiple Tornjak backends from one API. -- [Tornjak Frontend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-fe): This image is typically deployed after the Tornjak Backend or Manager are deployed, as it requires a URL to connect directly to the Tornjak backend API. - -NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in the same container, but these were recently deprecated. Images other than those above are NOT currently supported. +For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). ## Building Executables and Images @@ -28,10 +23,6 @@ Building Tornjak from scratch can be done with the Makefile. Notable make target - `make ui-agent`: makes the ReactJS app for the Tornjak frontend - [TODO](TODO) include containerized images -## Usage - -Once built or pulled, a container may be run as is described in our usage document - ## Development There are code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 00000000..d6b190ff --- /dev/null +++ b/USAGE.md @@ -0,0 +1,15 @@ +# Usage + +We support three container images currently: +- [Tornjak Backend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-be): This image can be deployed as a sidecar with any SPIRE server. +- [Tornjak Manager](https://github.com/spiffe/tornjak/pkgs/container/tornjak-manager): A container that runs this image exposes a port to register multiple Tornjak backends and forward typical commands to multiple Tornjak backends from one API. +- [Tornjak Frontend](https://github.com/spiffe/tornjak/pkgs/container/tornjak-fe): This image is typically deployed after the Tornjak Backend or Manager are deployed, as it requires a URL to connect directly to the Tornjak backend API. + +NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in the same container, but these were recently deprecated. Images other than those above are NOT currently supported. + +## Tornjak Backend + +The container has three arguments: + + + From fc166936336104570bbc0cc838dd8080234ea320 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 12:55:56 -0500 Subject: [PATCH 07/25] wrote usage documentation Signed-off-by: Maia Iyer --- USAGE.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/USAGE.md b/USAGE.md index d6b190ff..636f9967 100644 --- a/USAGE.md +++ b/USAGE.md @@ -9,7 +9,44 @@ NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in ## Tornjak Backend -The container has three arguments: +This is meant to be deployed where it can access a SPIRE server. To run, the container has three arguments: +| Flag | Description | Default | Arguments | Required | +|:---------------------|:------------------------------------------------------------|:--------|:----------|:---------| +| `-config|-c` | Config file path for SPIRE server | | | true | +| `-tornjak-config|-t` | Config file path for Tornjak | | | true | +| `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | +``` +docker run -p 10000:10000 -d ghcr.io/spiffe/tornjak-be:latest -c -t -expandEnv +``` +The above command creates a container listening at localhost:10000. Note that the config files must be accessible from INSIDE the container. Also note, this expands the container's environment variables in the Tornjak config map. + +This creates a service listening on container port 10000 for Tornjak API calls. + +## Tornjak Manager + +The manager is meant to be deployed where it can access all Tornjak backends we want to manage. To run, the container has no arguments. An example is below: + +``` +docker run -p 50000:50000 -d ghcr.io/spiffe/tornjak-manager:latest +``` + +This creates a service listening on container port 50000, forwarded to localhost:50000 for Tornjak Manager API calls. + +## Tornjak Frontend + +The frontend is meant to connect to either the Tornjak backend or the Tornjak manager. To run the container, we must set some environment variables: + +| Variable | Description | Default | Argument | Required | +|:--------------------------|-------------|--|--|--| +| REACT_APP_API_SERVER_URI | | | | | +| REACT_APP_TORNJAK_MANAGER | | | | | +| REACT_APP_AUTH_SERVER_URI | | | | | + +``` +docker run -p 3000:3000 -e REACT_APP_API_SERVER_URI='http://localhost:50000' -e REACT_APP_TORNJAK_MANAGER=true ghcr.io/spiffe/tornjak-fe:latest +``` + +The above command is an example of how to run the frontend. This creates a UI available at http://localhost:3000 forwarded from container port 3000. It is listening to a Tornjak backend or manager component available at http://localhost:50000, and has From 7088c27ae046955390ac8988cb7ce38b14fb3422 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 12:57:00 -0500 Subject: [PATCH 08/25] table fix Signed-off-by: Maia Iyer --- USAGE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/USAGE.md b/USAGE.md index 636f9967..6a0ad682 100644 --- a/USAGE.md +++ b/USAGE.md @@ -11,11 +11,11 @@ NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in This is meant to be deployed where it can access a SPIRE server. To run, the container has three arguments: -| Flag | Description | Default | Arguments | Required | -|:---------------------|:------------------------------------------------------------|:--------|:----------|:---------| -| `-config|-c` | Config file path for SPIRE server | | | true | -| `-tornjak-config|-t` | Config file path for Tornjak | | | true | -| `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | +| Flag | Description | Default | Arguments | Required | +|:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| +| `-config\|-c` | Config file path for SPIRE server | | | true | +| `-tornjak-config\|-t` | Config file path for Tornjak | | | true | +| `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` docker run -p 10000:10000 -d ghcr.io/spiffe/tornjak-be:latest -c -t -expandEnv From f38c65bd06dc6350f71e2d92516afa7bf876d0f2 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 13:06:56 -0500 Subject: [PATCH 09/25] small nits and table of contents Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 6 +++--- USAGE.md | 16 ++++++++++------ 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc3e5a0b..e744d4ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing -- Pre-built images -- Building +- [Pre-built images](./CONTRIBUTING.md#pre-built-images) +- [Building Executables and Images from Scratch](#building-executables-and-images-from-scratch) - discuss makefile targets - Usage - link to doc with config files + command line arguments @@ -15,7 +15,7 @@ For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). -## Building Executables and Images +## Building Executables and Images from scratch Building Tornjak from scratch can be done with the Makefile. Notable make targets follow: - `make bin/tornjak-backend`: makes the Go executable of the Tornjak backend diff --git a/USAGE.md b/USAGE.md index 6a0ad682..b226749c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -39,14 +39,18 @@ This creates a service listening on container port 50000, forwarded to localhost The frontend is meant to connect to either the Tornjak backend or the Tornjak manager. To run the container, we must set some environment variables: -| Variable | Description | Default | Argument | Required | -|:--------------------------|-------------|--|--|--| -| REACT_APP_API_SERVER_URI | | | | | -| REACT_APP_TORNJAK_MANAGER | | | | | -| REACT_APP_AUTH_SERVER_URI | | | | | +| Variable | Description | Default | Argument | Required | +|:----------------------------|-------------|--|--|--| +| `REACT_APP_API_SERVER_URI` | | | | | +| `REACT_APP_TORNJAK_MANAGER` | | | | | +| `REACT_APP_AUTH_SERVER_URI` | | | | | ``` docker run -p 3000:3000 -e REACT_APP_API_SERVER_URI='http://localhost:50000' -e REACT_APP_TORNJAK_MANAGER=true ghcr.io/spiffe/tornjak-fe:latest ``` -The above command is an example of how to run the frontend. This creates a UI available at http://localhost:3000 forwarded from container port 3000. It is listening to a Tornjak backend or manager component available at http://localhost:50000, and has +The above command is an example of how to run the frontend. This creates a UI available at http://localhost:3000 forwarded from container port 3000. It is listening to a Tornjak manager component available at http://localhost:50000, and knows to run in manager mode with the `REACT_APP_TORNJAK_MANAGER` flag. + +## Further steps + +It is recommended to try a full deployment of the Tornjak frontend, backend, and SPIRE Server in minikube. Please see our [tutorial document](./docs/tornjak-quickstart.md) for step-by-step instructions From c2911bb072f33ab560b166d7f907141f72a50028 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 15:11:29 -0500 Subject: [PATCH 10/25] added user management documentation page Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 100 +++++++++++++++------------------------- USAGE.md | 93 +++++++++++++++++++++++++++++++++++-- docs/user-management.md | 56 ++++++++++++++++++++++ 3 files changed, 181 insertions(+), 68 deletions(-) create mode 100644 docs/user-management.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e744d4ed..0484293e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,54 +1,51 @@ # Contributing -- [Pre-built images](./CONTRIBUTING.md#pre-built-images) +- [Pre-built images](#pre-built-images) +- [Build Requirements](#build-requirements) - [Building Executables and Images from Scratch](#building-executables-and-images-from-scratch) - - discuss makefile targets -- Usage - - link to doc with config files + command line arguments - - Perhaps the UserManagement part lives here too -- Development - - link to architecture of codebase +- [Development](#development) - Testing - frontend local testing section +TODO - Usermanagement? currently in usage ## Pre-built images For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). -## Building Executables and Images from scratch +## Build Requirements + +In order to build from scratch, we require the following installations: +- [Docker]() for the backend +- [npm]() for the frontend + +## Building Executables and Images from Scratch Building Tornjak from scratch can be done with the Makefile. Notable make targets follow: - `make bin/tornjak-backend`: makes the Go executable of the Tornjak backend - `make bin/tornjak-manager`: makes the Go executable of the Tornjak manager - `make ui-agent`: makes the ReactJS app for the Tornjak frontend -- [TODO](TODO) include containerized images +- `make container-tornjak-be`: containerizes Go executable of the Tornjak backend +- `make container-manager`:`containerizes Go executable of the Tornjak manager +- `make container-frontend`: containerizes React JS app for the Tornjak frontend + +For usage instructions of the containers, please see our [USAGE document](./USAGE.md) to get started. ## Development -There are code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). +There are code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). +## Local testing +We highly recommend starting with our [quickstart tutorial](./docs/tornjak-quickstart.md), using official images and preset configs before development. This tutorial creates a local instance of SPIRE on Minikube, adds Tornjak server, and runs a UI. -### Running the Tornjak Manager -Once you have a Tornjak agent running, you may run the Tornjak manager by locally running +Additionally, one may test out several other features including the following: +- [Running the Frontend Locally](#running-the-frontend-locally) +- [Running the Tornjak Manager Backend and Frontend Locally](#running-the-tornjak-manager) +- [User Management](#user-management) -``` -go run tornjak-backend/cmd/manager/manager.go -``` +### Running the Frontend Locally -which starts listening on port 50000. To start the manager UI, run: - -``` -REACT_APP_API_SERVER_URI=http://localhost:50000/ -REACT_APP_TORNJAK_MANAGER=true npm start -``` - -In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. - -Alternatively, one may also run these components in a container. - -### Testing and validating the Tornjak frontend -To start a local version of the Tornjak frontend, one must have a point at the running Tornjak APIs: +An excellent feature for frontend development is the ability to make changes to the frontend code without needing to restart the application. To start a local version of the Tornjak frontend, one must have it point at the running Tornjak APIs: ```console cd tornjak-frontend @@ -58,52 +55,27 @@ REACT_APP_API_SERVER_URI=http:/// npm start Assuming `npm` is installed, this will start a server on `http://localhost:3000` Please be patient, as it might take a few minutes to compile and start the server. -## Enable User Management -User Management prevents un-authorized access to Tornjak and SPIRE APIs. -For more information on enabling the User Management and Keycloak configuration, -please check [docs/keycloak-configuration.md](docs/keycloak-configuration.md) document. - -First, start Keycloak instance locally: - -``` -docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev -``` - -Keycloak instance will start listening port on 8080 - -Next, start the Tornjak with Auth service: - -``` -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http://localhost:10000/ -REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start -``` - -To build the frontend on a container as a separate image: +### Running the Tornjak Manager -Note: Make sure CONTAINER_TAG_FRONTEND point at your directory, as tsidentity can only be used for pulling but not pushing. +You may run the uncontainerized Tornjak manager by locally running the following: ``` -CONTAINER_TAG_FRONTEND=tsidentity/tornjak-fe:latest -make container-frontend-push +go run tornjak-backend/cmd/manager/manager.go ``` -## User Management Disabled +which starts listening on port 50000. -To test build image locally, run: +To start the manager UI, run: ``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' tsidentity/tornjak-fe:latest +REACT_APP_API_SERVER_URI=http://localhost:50000/ +REACT_APP_TORNJAK_MANAGER=true npm start ``` -Alternatively, to run the image with the authentication/authorization enabled on the local Keycloak instance, run: +In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. -``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest -``` +Alternatively, one may also run these components in a container, as is described in our [USAGE doc](./USAGE.md). -This will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. +### User Management -Depending on the user used to signin, there will be two different views. -An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. +User Management prevents un-authorized access to Tornjak and SPIRE APIs. We have several comprehensive resources for getting started with integrating user management in this [User Management documentation](./docs/user-management.md). diff --git a/USAGE.md b/USAGE.md index b226749c..f8cdbc38 100644 --- a/USAGE.md +++ b/USAGE.md @@ -14,16 +14,16 @@ This is meant to be deployed where it can access a SPIRE server. To run, the con | Flag | Description | Default | Arguments | Required | |:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| | `-config\|-c` | Config file path for SPIRE server | | | true | -| `-tornjak-config\|-t` | Config file path for Tornjak | | | true | +| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | | false | | `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` docker run -p 10000:10000 -d ghcr.io/spiffe/tornjak-be:latest -c -t -expandEnv ``` -The above command creates a container listening at localhost:10000. Note that the config files must be accessible from INSIDE the container. Also note, this expands the container's environment variables in the Tornjak config map. +The above command creates a container listening at http://localhost:10000 for Tornjak API calls. Note that the config files must be accessible from INSIDE the container. Also note, this expands the container's environment variables in the Tornjak config map. -This creates a service listening on container port 10000 for Tornjak API calls. +For more instructions on Tornjak config formatting, please see our [configuration reference](./docs/config-tornjak-agent.md). ## Tornjak Manager @@ -53,4 +53,89 @@ The above command is an example of how to run the frontend. This creates a UI av ## Further steps -It is recommended to try a full deployment of the Tornjak frontend, backend, and SPIRE Server in minikube. Please see our [tutorial document](./docs/tornjak-quickstart.md) for step-by-step instructions +It is recommended to try a full deployment of the Tornjak frontend, backend, and SPIRE Server in minikube. Please see our [tutorial document](./docs/tornjak-quickstart.md) for step-by-step instructions. + + + + + +------------- + +### Running the Tornjak Manager +Once you have a Tornjak agent running, you may run the Tornjak manager by locally running + +``` +go run tornjak-backend/cmd/manager/manager.go +``` + +which starts listening on port 50000. To start the manager UI, run: + +``` +REACT_APP_API_SERVER_URI=http://localhost:50000/ +REACT_APP_TORNJAK_MANAGER=true npm start +``` + +In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. + +Alternatively, one may also run these components in a container. + +### Testing and validating the Tornjak frontend +To start a local version of the Tornjak frontend, one must have a point at the running Tornjak APIs: + +```console +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http:/// npm start +``` + +Assuming `npm` is installed, this will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +## Enable User Management +User Management prevents un-authorized access to Tornjak and SPIRE APIs. +For more information on enabling the User Management and Keycloak configuration, +please check [docs/keycloak-configuration.md](docs/keycloak-configuration.md) document. + +First, start Keycloak instance locally: + +``` +docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev +``` + +Keycloak instance will start listening port on 8080 + +Next, start the Tornjak with Auth service: + +``` +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http://localhost:10000/ +REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start +``` + +To build the frontend on a container as a separate image: + +Note: Make sure CONTAINER_TAG_FRONTEND point at your directory, as tsidentity can only be used for pulling but not pushing. + +``` +CONTAINER_TAG_FRONTEND=tsidentity/tornjak-fe:latest +make container-frontend-push +``` + +## User Management Disabled + +To test build image locally, run: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' tsidentity/tornjak-fe:latest +``` + +Alternatively, to run the image with the authentication/authorization enabled on the local Keycloak instance, run: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest +``` + +This will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +Depending on the user used to signin, there will be two different views. +An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. diff --git a/docs/user-management.md b/docs/user-management.md new file mode 100644 index 00000000..222a4c56 --- /dev/null +++ b/docs/user-management.md @@ -0,0 +1,56 @@ +# User Management + +This document compiles all the information on the user management integration we have experimented with. + +Currently, this feature is available only for a single instance of a Tornjak agent with a frontend. + +## Overview + +We follow the OAuth2.0 spec for authentication. The diagrams below show the implemented [Standard Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow): +![standard](./rsrc/standard-auth-code-flow.png) + +We will eventually be implementing the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) to secure the backend with a public frontend application. This is necessary as the public frontend cannot store client secrets securely: +![pkce](./rsrc/pkce-auth-code-flow.png) + +A more in-depth Medium article for the overall architecture can be found [here](https://medium.com/universal-workload-identity/identity-access-management-iam-integration-with-tornjak-749984966ab5). + +## Architecture + +[TODO insert architecture diagram here] + +The architecture integrates with a separate Auth server. This Auth server is used to secure the backend, which can be configured to expected access tokens signed by a given list of public keys. Then, any callers to the Auth server must be able to obtain such an access token. + +## General Deployment + +In order to deploy, there are several steps: + +1. There must be an existing, preconfigured auth server for Tornjak components to integrate with. +2. The backend is deployed with a configuration pointing to said auth server. +3. The frontend must be deployed configured to obtain access tokens from said auth server before sending calls to the backend. + +## Examples and Tutorials + +We have experimented extensively with the open source Keycloak Auth server. Specifically, it is very easy to set up a Tornjak secured by Keycloak today. + +To configure the Auth server, please see our [Medium blog](https://medium.com/universal-workload-identity/step-by-step-guide-to-setup-keycloak-configuration-for-tornjak-dbe5c3049034) for a walkthrough on configuring the auth server. For more in-depth documentation on this setup, please see [this document on Keycloak configuration](./keycloak-configuration.md). + +Once the Auth server is set up, we can deploy the backend to require access tokens from our auth server, as detailed in [this followup Medium blog](https://medium.com/universal-workload-identity/guide-to-integrating-tornjak-with-keycloak-for-access-control-to-spire-40a3d5ee5f5a), with more details on the general configuration [here](https://github.com/spiffe/tornjak/blob/main/docs/config-tornjak-agent.md). + +Finally, the frontend must be deployed and configured to obtain access tokens from this auth server. This can be done locally with the environment variable `REACT_APP_AUTH_SERVER_URI`: + +``` +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http://localhost:10000/ +REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start +``` + +Alternatively, we can do the same on the containerized version: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest +``` + +This will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +Given the Auth server configuration above, we have an admin and a viewer user type. An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. From fd2c6d92451a39ad058b21a129f6a833ebd86580 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 15:26:56 -0500 Subject: [PATCH 11/25] renaming files and dedicated plugin doc Signed-off-by: Maia Iyer --- docs/config-tornjak-agent.md | 2 +- docs/feature_auth.md | 56 +++++++++++++++++++++++++++++ docs/plugin_auth_keycloak.md | 6 ---- docs/plugin_server_auth_keycloak.md | 23 ++++++++++++ 4 files changed, 80 insertions(+), 7 deletions(-) create mode 100644 docs/feature_auth.md delete mode 100644 docs/plugin_auth_keycloak.md create mode 100644 docs/plugin_server_auth_keycloak.md diff --git a/docs/config-tornjak-agent.md b/docs/config-tornjak-agent.md index 72a87703..4c4f1de4b 100644 --- a/docs/config-tornjak-agent.md +++ b/docs/config-tornjak-agent.md @@ -23,7 +23,7 @@ server { | Type | Name | Description | | ---- | ---- | ----------- | | DataStore | [sql]() | Default SQL storage for Tornjak metadata | -| UserManagement | [keycloak](/docs/plugin_auth_keycloak.md) | Requires JWT Bearer Access Token provided for each request | +| UserManagement | [keycloak](/docs/plugin_server_auth_keycloak.md) | Requires JWT Bearer Access Token provided for each request | ## Plugin configuration diff --git a/docs/feature_auth.md b/docs/feature_auth.md new file mode 100644 index 00000000..222a4c56 --- /dev/null +++ b/docs/feature_auth.md @@ -0,0 +1,56 @@ +# User Management + +This document compiles all the information on the user management integration we have experimented with. + +Currently, this feature is available only for a single instance of a Tornjak agent with a frontend. + +## Overview + +We follow the OAuth2.0 spec for authentication. The diagrams below show the implemented [Standard Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow): +![standard](./rsrc/standard-auth-code-flow.png) + +We will eventually be implementing the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) to secure the backend with a public frontend application. This is necessary as the public frontend cannot store client secrets securely: +![pkce](./rsrc/pkce-auth-code-flow.png) + +A more in-depth Medium article for the overall architecture can be found [here](https://medium.com/universal-workload-identity/identity-access-management-iam-integration-with-tornjak-749984966ab5). + +## Architecture + +[TODO insert architecture diagram here] + +The architecture integrates with a separate Auth server. This Auth server is used to secure the backend, which can be configured to expected access tokens signed by a given list of public keys. Then, any callers to the Auth server must be able to obtain such an access token. + +## General Deployment + +In order to deploy, there are several steps: + +1. There must be an existing, preconfigured auth server for Tornjak components to integrate with. +2. The backend is deployed with a configuration pointing to said auth server. +3. The frontend must be deployed configured to obtain access tokens from said auth server before sending calls to the backend. + +## Examples and Tutorials + +We have experimented extensively with the open source Keycloak Auth server. Specifically, it is very easy to set up a Tornjak secured by Keycloak today. + +To configure the Auth server, please see our [Medium blog](https://medium.com/universal-workload-identity/step-by-step-guide-to-setup-keycloak-configuration-for-tornjak-dbe5c3049034) for a walkthrough on configuring the auth server. For more in-depth documentation on this setup, please see [this document on Keycloak configuration](./keycloak-configuration.md). + +Once the Auth server is set up, we can deploy the backend to require access tokens from our auth server, as detailed in [this followup Medium blog](https://medium.com/universal-workload-identity/guide-to-integrating-tornjak-with-keycloak-for-access-control-to-spire-40a3d5ee5f5a), with more details on the general configuration [here](https://github.com/spiffe/tornjak/blob/main/docs/config-tornjak-agent.md). + +Finally, the frontend must be deployed and configured to obtain access tokens from this auth server. This can be done locally with the environment variable `REACT_APP_AUTH_SERVER_URI`: + +``` +cd tornjak-frontend +REACT_APP_API_SERVER_URI=http://localhost:10000/ +REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start +``` + +Alternatively, we can do the same on the containerized version: + +``` +docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest +``` + +This will start a server on `http://localhost:3000` +Please be patient, as it might take a few minutes to compile and start the server. + +Given the Auth server configuration above, we have an admin and a viewer user type. An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. diff --git a/docs/plugin_auth_keycloak.md b/docs/plugin_auth_keycloak.md deleted file mode 100644 index 50a0d679..00000000 --- a/docs/plugin_auth_keycloak.md +++ /dev/null @@ -1,6 +0,0 @@ -# **Proposed Oath2-inspired Protocol** -Currently, we are implementing [Standard Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow): -![standard](./rsrc/standard-auth-code-flow.png) -​ -We will eventually be implementing the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) to secure the backend with a public frontend application. This is necessary as the public frontend cannot store client secrets securely: -![pkce](./rsrc/pkce-auth-code-flow.png) \ No newline at end of file diff --git a/docs/plugin_server_auth_keycloak.md b/docs/plugin_server_auth_keycloak.md new file mode 100644 index 00000000..6354a39e --- /dev/null +++ b/docs/plugin_server_auth_keycloak.md @@ -0,0 +1,23 @@ +# Server plugin: Authorization "keycloak" + +Please see our documentation on the [authorization feature](./feature_auth.md) for more complete details. + +Note that configuring this requires the frontend to be configured to obtain access tokens at the relevant auth server. + +The configuration has the following key-value pairs: + +| Key | Description | Required | +| ----------- | ----------------------------------------------------------------------- | -------- | +| jwksURL | Location of the public keys used to validate access tokens | True | +| redirectuRL | Location of the redirect URL to the auth server to obtain access tokens | True | + +A sample configuration file for syntactic referense is below: + +```hcl + UserManagement "KeycloakAuth" { + plugin_data { + jwksURL = "http://localhost:8080/jwks" + redirectURL = "http://localhost:10000/*" + } + } +``` From 49753eea80a914de8a437a16d59d88a1666fcc60 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 15:28:59 -0500 Subject: [PATCH 12/25] nit cleanup Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0484293e..d9a9d78e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,7 @@ - [Build Requirements](#build-requirements) - [Building Executables and Images from Scratch](#building-executables-and-images-from-scratch) - [Development](#development) -- Testing - - frontend local testing section -TODO - Usermanagement? currently in usage +- [Local Testing](#local-testing) ## Pre-built images From 9229885952f7655535c83ec8783bac9e952092f6 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 15:33:08 -0500 Subject: [PATCH 13/25] removing redundant information Signed-off-by: Maia Iyer --- USAGE.md | 83 -------------------------------------------------------- 1 file changed, 83 deletions(-) diff --git a/USAGE.md b/USAGE.md index f8cdbc38..6ac2f71e 100644 --- a/USAGE.md +++ b/USAGE.md @@ -56,86 +56,3 @@ The above command is an example of how to run the frontend. This creates a UI av It is recommended to try a full deployment of the Tornjak frontend, backend, and SPIRE Server in minikube. Please see our [tutorial document](./docs/tornjak-quickstart.md) for step-by-step instructions. - - - -------------- - -### Running the Tornjak Manager -Once you have a Tornjak agent running, you may run the Tornjak manager by locally running - -``` -go run tornjak-backend/cmd/manager/manager.go -``` - -which starts listening on port 50000. To start the manager UI, run: - -``` -REACT_APP_API_SERVER_URI=http://localhost:50000/ -REACT_APP_TORNJAK_MANAGER=true npm start -``` - -In this view, there is an additional navigation bar tab titled "Manage Servers" where you may register Tornjak agents. - -Alternatively, one may also run these components in a container. - -### Testing and validating the Tornjak frontend -To start a local version of the Tornjak frontend, one must have a point at the running Tornjak APIs: - -```console -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http:/// npm start -``` - -Assuming `npm` is installed, this will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. - -## Enable User Management -User Management prevents un-authorized access to Tornjak and SPIRE APIs. -For more information on enabling the User Management and Keycloak configuration, -please check [docs/keycloak-configuration.md](docs/keycloak-configuration.md) document. - -First, start Keycloak instance locally: - -``` -docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev -``` - -Keycloak instance will start listening port on 8080 - -Next, start the Tornjak with Auth service: - -``` -cd tornjak-frontend -REACT_APP_API_SERVER_URI=http://localhost:10000/ -REACT_APP_AUTH_SERVER_URI=http://localhost:8080/ npm start -``` - -To build the frontend on a container as a separate image: - -Note: Make sure CONTAINER_TAG_FRONTEND point at your directory, as tsidentity can only be used for pulling but not pushing. - -``` -CONTAINER_TAG_FRONTEND=tsidentity/tornjak-fe:latest -make container-frontend-push -``` - -## User Management Disabled - -To test build image locally, run: - -``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' tsidentity/tornjak-fe:latest -``` - -Alternatively, to run the image with the authentication/authorization enabled on the local Keycloak instance, run: - -``` -docker run -p 3000:3000 -d -e REACT_APP_API_SERVER_URI='http://localhost:10000' -e REACT_APP_AUTH_SERVER_URI='http://localhost:8080' tsidentity/tornjak-fe:latest -``` - -This will start a server on `http://localhost:3000` -Please be patient, as it might take a few minutes to compile and start the server. - -Depending on the user used to signin, there will be two different views. -An Admin User will have an Admin portal with admin privilages and a viewer user will have restricted access for the Tornjak UI only for viewing. From 85b68aa475cfa2ae7faf1ab067a330670c4eada3 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Wed, 8 Feb 2023 16:10:06 -0500 Subject: [PATCH 14/25] cluster documentation Signed-off-by: Maia Iyer --- docs/tornjak-ui-api-documentation.md | 86 ++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/docs/tornjak-ui-api-documentation.md b/docs/tornjak-ui-api-documentation.md index 568d1e1a..9990e0f0 100644 --- a/docs/tornjak-ui-api-documentation.md +++ b/docs/tornjak-ui-api-documentation.md @@ -301,6 +301,29 @@ Content-Type: application/json; charset=utf-8 } } ``` + +##### /api/tornjak/clusters/list +``` +Request +api/tornjak/clusters/list +Example response: +HTTP/1.1 200 OK +Content-Type: application/json; charset=utf-8 + +{ + "clusters": [ + {"name":"clustername", + "editedName":"", + "creationTime":"Feb 08 2023 21:02:10", + "domainName":"", + "managedBy":"", + "platformType":"Docker", + "agentsList":["agent1"]} + ] +} +``` + + #### POST ##### /api/tornjak/selectors/register ``` @@ -321,6 +344,69 @@ Example response: SUCCESS ``` +##### /api/tornjak/clusters/create +``` +Request +api/tornjak/selectors/register +Example request payload: +HTTP/1.1 200 OK +Content-Type: application/json; charset=utf-8 + +{ + "cluster": + { + "name": "clusterName", + "platformType": "Docker", + "agentsList": ["agent1", "agent2"], + "domainName": "example.org", + } +} +Example response: +SUCCESS +``` + +##### /api/tornjak/clusters/edit +``` +Request +api/tornjak/selectors/register +Example request payload: +HTTP/1.1 200 OK +Content-Type: application/json; charset=utf-8 + +{ + "cluster": + { + "name": "clusterName", + "editedName": "newClusterName" + "platformType": "Docker", + "agentsList": ["agent1"], + "domainName": "example.org", + } +} +Example response: +SUCCESS +``` + +##### /api/tornjak/clusters/delete +``` +Request +api/tornjak/selectors/register +Example request payload: +HTTP/1.1 200 OK +Content-Type: application/json; charset=utf-8 + +{ + "cluster": + { + "name": "clusterName", + } +} +Example response: +SUCCESS +``` + + + ## 3.2. Manager API’s All of Tornjak agent APIs apply for manager APIs as well except that manager APIs are proxy calls of agent APIs (/manager-api/). In addition to the agent APIs manager API also includes server’s APIs as described below. From 03d7c002c6ba9e438f3db9ea19b82862890f6226 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Thu, 9 Feb 2023 10:21:16 -0500 Subject: [PATCH 15/25] revision of contributing Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9a9d78e..b3711984 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,28 +2,30 @@ - [Pre-built images](#pre-built-images) - [Build Requirements](#build-requirements) -- [Building Executables and Images from Scratch](#building-executables-and-images-from-scratch) +- [Building Executables and Images from Scratch](#building-executables-and-images) - [Development](#development) - [Local Testing](#local-testing) ## Pre-built images -For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). +You can use pre-built images for various versions and Tornjak components. For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). + +Otherwise, you can follow instructions below to build Tornjak images. ## Build Requirements -In order to build from scratch, we require the following installations: +In order to build, we require the following installations: - [Docker]() for the backend - [npm]() for the frontend -## Building Executables and Images from Scratch +## Building Executables and Images -Building Tornjak from scratch can be done with the Makefile. Notable make targets follow: +Building Tornjak manually can be done with the Makefile. Notable make targets follow: - `make bin/tornjak-backend`: makes the Go executable of the Tornjak backend - `make bin/tornjak-manager`: makes the Go executable of the Tornjak manager - `make ui-agent`: makes the ReactJS app for the Tornjak frontend - `make container-tornjak-be`: containerizes Go executable of the Tornjak backend -- `make container-manager`:`containerizes Go executable of the Tornjak manager +- `make container-manager`:containerizes Go executable of the Tornjak manager - `make container-frontend`: containerizes React JS app for the Tornjak frontend For usage instructions of the containers, please see our [USAGE document](./USAGE.md) to get started. From ebe6bedddb2ffdfeb4cd3cadf08c678f6110f70f Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Thu, 9 Feb 2023 10:25:19 -0500 Subject: [PATCH 16/25] contributing revision pointing to spiffe Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3711984..79aa7996 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,16 @@ # Contributing +- [Contributor Guidelines and Governance](#cnotributor-guildelines-and-governance) - [Pre-built images](#pre-built-images) - [Build Requirements](#build-requirements) - [Building Executables and Images from Scratch](#building-executables-and-images) - [Development](#development) - [Local Testing](#local-testing) +## Contributor Guidelines and Governance + +Please see [CONTRIBUTING](https://github.com/spiffe/spiffe/blob/main/CONTRIBUTING.md) and [GOVERNANCE](https://github.com/spiffe/spiffe/blob/main/GOVERNANCE.md) from the SPIFFE project. + ## Pre-built images You can use pre-built images for various versions and Tornjak components. For a list of supported public images of Tornjak along with usage instructions please see our [USAGE document](./USAGE.md). @@ -32,7 +37,7 @@ For usage instructions of the containers, please see our [USAGE document](./USAG ## Development -There are code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). +We welcome all development attempst and contributions from the community. The easiest place to start is by reviewing our code architecture diagrams available in our [api documentation](./docs/tornjak-ui-api-documentation.md#11-overview). ## Local testing From 8e98b65cbfb1422a6873d1433849d44d0845a31e Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Thu, 9 Feb 2023 10:26:27 -0500 Subject: [PATCH 17/25] fixed link Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79aa7996..e151d448 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -- [Contributor Guidelines and Governance](#cnotributor-guildelines-and-governance) +- [Contributor Guidelines and Governance](#contributor-guildelines-and-governance) - [Pre-built images](#pre-built-images) - [Build Requirements](#build-requirements) - [Building Executables and Images from Scratch](#building-executables-and-images) From 09f9fdf45bfdfe04111e4e1305ae09e8efbe0c6d Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Thu, 9 Feb 2023 10:27:33 -0500 Subject: [PATCH 18/25] fixing another link Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e151d448..df05e404 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -- [Contributor Guidelines and Governance](#contributor-guildelines-and-governance) +- [Contributor Guidelines and Governance](#contributor-guidelines-and-governance) - [Pre-built images](#pre-built-images) - [Build Requirements](#build-requirements) - [Building Executables and Images from Scratch](#building-executables-and-images) From fdc38740ed8a4670280b119a566e9edf924a99c8 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 10:20:24 -0500 Subject: [PATCH 19/25] nits for contributing Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df05e404..21cc537a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,8 +20,9 @@ Otherwise, you can follow instructions below to build Tornjak images. ## Build Requirements In order to build, we require the following installations: -- [Docker]() for the backend -- [npm]() for the frontend +- [Docker](https://docs.docker.com/engine/install/) for the backend build +- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for the frontend +- [Golang](https://go.dev/doc/install) is required if you would like to run the Go backends locally ## Building Executables and Images @@ -45,9 +46,12 @@ We highly recommend starting with our [quickstart tutorial](./docs/tornjak-quick Additionally, one may test out several other features including the following: - [Running the Frontend Locally](#running-the-frontend-locally) -- [Running the Tornjak Manager Backend and Frontend Locally](#running-the-tornjak-manager) +- [Running the Backend Locally](#running-the-backend-locally) +- [Running the Tornjak Manager Locally](#running-the-tornjak-manager) - [User Management](#user-management) +Usage documentation for each of the Tornjak components can be found in our [Usage document](./USAGE.md). + ### Running the Frontend Locally An excellent feature for frontend development is the ability to make changes to the frontend code without needing to restart the application. To start a local version of the Tornjak frontend, one must have it point at the running Tornjak APIs: @@ -60,6 +64,16 @@ REACT_APP_API_SERVER_URI=http:/// npm start Assuming `npm` is installed, this will start a server on `http://localhost:3000` Please be patient, as it might take a few minutes to compile and start the server. +### Running the Backend Locally + +The backend may also be run locally as well. + +```console +go run tornjak-backend/cmd/agent/agent.go +``` + +Note, the above command will print out usage documentation for the server. Please see our [Usage document](./USAGE.md) for more information. Additionally, full functionality of the server requires a SPIRE server to be running. + ### Running the Tornjak Manager You may run the uncontainerized Tornjak manager by locally running the following: @@ -83,4 +97,4 @@ Alternatively, one may also run these components in a container, as is described ### User Management -User Management prevents un-authorized access to Tornjak and SPIRE APIs. We have several comprehensive resources for getting started with integrating user management in this [User Management documentation](./docs/user-management.md). +User Management is an optional feature that prevents un-authorized access to Tornjak and SPIRE APIs. We have several comprehensive resources for getting started with integrating user management in this [User Management documentation](./docs/user-management.md). From fec1349904bccabd65834f41287f3555f67b8321 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 10:21:03 -0500 Subject: [PATCH 20/25] escaping characters Signed-off-by: Maia Iyer --- USAGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/USAGE.md b/USAGE.md index 6ac2f71e..2f023d00 100644 --- a/USAGE.md +++ b/USAGE.md @@ -13,8 +13,8 @@ This is meant to be deployed where it can access a SPIRE server. To run, the con | Flag | Description | Default | Arguments | Required | |:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| -| `-config\|-c` | Config file path for SPIRE server | | | true | -| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | | false | +| `-config\|-c` | Config file path for SPIRE server | | \ | true | +| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | \ | false | | `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` From 4676585bbe8808848ca24769e4336b04f93ece93 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 10:21:57 -0500 Subject: [PATCH 21/25] using code-like formatting Signed-off-by: Maia Iyer --- USAGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/USAGE.md b/USAGE.md index 2f023d00..ad321006 100644 --- a/USAGE.md +++ b/USAGE.md @@ -13,8 +13,8 @@ This is meant to be deployed where it can access a SPIRE server. To run, the con | Flag | Description | Default | Arguments | Required | |:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| -| `-config\|-c` | Config file path for SPIRE server | | \ | true | -| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | \ | false | +| `-config\|-c` | Config file path for SPIRE server | | `` | true | +| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | `` | false | | `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` From f45554f9509ddb5d7cde555918e1663954a9a842 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 10:25:45 -0500 Subject: [PATCH 22/25] adding frontend usage Signed-off-by: Maia Iyer --- USAGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/USAGE.md b/USAGE.md index ad321006..bcb9dc3d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -41,9 +41,9 @@ The frontend is meant to connect to either the Tornjak backend or the Tornjak ma | Variable | Description | Default | Argument | Required | |:----------------------------|-------------|--|--|--| -| `REACT_APP_API_SERVER_URI` | | | | | -| `REACT_APP_TORNJAK_MANAGER` | | | | | -| `REACT_APP_AUTH_SERVER_URI` | | | | | +| `REACT_APP_API_SERVER_URI` | URI for the Tornjak backend or Manager to connect to | | `http://localhost:10000` | true | +| `REACT_APP_TORNJAK_MANAGER` | Boolean for whether the connected server is a manager | false | `true` | false | +| `REACT_APP_AUTH_SERVER_URI` | URI for the Keycloak instance to obtain access tokens | `` | `http://localhost:8080` | false | ``` docker run -p 3000:3000 -e REACT_APP_API_SERVER_URI='http://localhost:50000' -e REACT_APP_TORNJAK_MANAGER=true ghcr.io/spiffe/tornjak-fe:latest From a8e0a7061bb0b11a51d5ef9a5f8621d92073e1ac Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 14:09:55 -0500 Subject: [PATCH 23/25] fixing flag documentation Signed-off-by: Maia Iyer --- USAGE.md | 4 ++-- run_backend.sh | 4 ++-- run_server.sh | 5 ++--- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/USAGE.md b/USAGE.md index bcb9dc3d..770a35a3 100644 --- a/USAGE.md +++ b/USAGE.md @@ -13,8 +13,8 @@ This is meant to be deployed where it can access a SPIRE server. To run, the con | Flag | Description | Default | Arguments | Required | |:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| -| `-config\|-c` | Config file path for SPIRE server | | `` | true | -| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | `` | false | +| `-config, -c` | Config file path for SPIRE server | | `` | true | +| `-tornjak-config, -t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | `` | false | | `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` diff --git a/run_backend.sh b/run_backend.sh index 49868c9b..70093a81 100755 --- a/run_backend.sh +++ b/run_backend.sh @@ -5,8 +5,8 @@ usage() { cat << EOF >&2 Usage: run_server [-c ] [-t ] --c | -config : SPIRE Config File --t | -tornjak-config : Tornjak Config File +-config,-c : SPIRE Config File +-tornjak-config,-t : Tornjak Config File -expandEnv : if flag included, expand environment variables expressed in Tornjak Config File EOF exit 1 diff --git a/run_server.sh b/run_server.sh index b1e9a437..0bd63c66 100755 --- a/run_server.sh +++ b/run_server.sh @@ -5,14 +5,13 @@ usage() { cat << EOF >&2 Usage: run_server [-c ] [-t ] --c | -config : SPIRE Config File --t | -tornjak-config : Tornjak Config File +-config,-c : SPIRE Config File +-tornjak-config,-t : Tornjak Config File EOF exit 1 } # argument parse - while [[ $# -gt 0 ]] do key="$1" From 3182a29b439c93cb357f717037ad93340cfd8074 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Mon, 20 Feb 2023 14:35:52 -0500 Subject: [PATCH 24/25] usage nits Signed-off-by: Maia Iyer --- CONTRIBUTING.md | 2 +- USAGE.md | 10 +++++----- run_backend.sh | 14 +++++++------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21cc537a..c747f13a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,7 +72,7 @@ The backend may also be run locally as well. go run tornjak-backend/cmd/agent/agent.go ``` -Note, the above command will print out usage documentation for the server. Please see our [Usage document](./USAGE.md) for more information. Additionally, full functionality of the server requires a SPIRE server to be running. +Note, the above command will print out usage documentation for the server. Please see our documentation for the backend [here](./docs/config-tornjak-agent.md) for more information. Additionally, full functionality of the server requires a SPIRE server to be running. ### Running the Tornjak Manager diff --git a/USAGE.md b/USAGE.md index 770a35a3..1c4cbb59 100644 --- a/USAGE.md +++ b/USAGE.md @@ -11,11 +11,11 @@ NOTE: Previously, we had images placing the Tornjak backend and SPIRE server in This is meant to be deployed where it can access a SPIRE server. To run, the container has three arguments: -| Flag | Description | Default | Arguments | Required | -|:----------------------|:------------------------------------------------------------|:--------|:----------|:---------| -| `-config, -c` | Config file path for SPIRE server | | `` | true | -| `-tornjak-config, -t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | `` | false | -| `-expandEnv` | If included, expand environment variables in Tornjak config | False | | false | +| Flag | Description | Default | Arguments | Required | +|:-----------------------|:------------------------------------------------------------|:--------|:----------|:---------| +| `--config, -c` | Config file path for SPIRE server | | `` | true | +| `--tornjak-config, -t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | `` | false | +| `--expandEnv` | If included, expand environment variables in Tornjak config | False | | false | ``` docker run -p 10000:10000 -d ghcr.io/spiffe/tornjak-be:latest -c -t -expandEnv diff --git a/run_backend.sh b/run_backend.sh index 70093a81..b421cf94 100755 --- a/run_backend.sh +++ b/run_backend.sh @@ -5,9 +5,9 @@ usage() { cat << EOF >&2 Usage: run_server [-c ] [-t ] --config,-c : SPIRE Config File --tornjak-config,-t : Tornjak Config File --expandEnv : if flag included, expand environment variables expressed in Tornjak Config File +--config,-c : SPIRE Config File +--tornjak-config,-t : Tornjak Config File +--expandEnv : if flag included, expand environment variables expressed in Tornjak Config File EOF exit 1 } @@ -20,18 +20,18 @@ key="$1" case $key in - -c|-config) + -c|--config) SPIRE_CONFIG="$2" shift shift ;; - -t|-tornjak-config) + -t|--tornjak-config) TORNJAK_CONFIG="$2" shift shift ;; - -expandEnv) - EXPAND_ENV="-expandEnv" + --expandEnv) + EXPAND_ENV="--expandEnv" shift ;; *) From acc21364cad7a72754d4bde8d05753557bb1c8a6 Mon Sep 17 00:00:00 2001 From: Maia Iyer Date: Tue, 21 Feb 2023 11:41:50 -0500 Subject: [PATCH 25/25] nit more links Signed-off-by: Maia Iyer --- USAGE.md | 2 +- docs/config-tornjak-agent.md | 2 +- docs/feature_auth.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/USAGE.md b/USAGE.md index 1c4cbb59..c2e82dce 100644 --- a/USAGE.md +++ b/USAGE.md @@ -43,7 +43,7 @@ The frontend is meant to connect to either the Tornjak backend or the Tornjak ma |:----------------------------|-------------|--|--|--| | `REACT_APP_API_SERVER_URI` | URI for the Tornjak backend or Manager to connect to | | `http://localhost:10000` | true | | `REACT_APP_TORNJAK_MANAGER` | Boolean for whether the connected server is a manager | false | `true` | false | -| `REACT_APP_AUTH_SERVER_URI` | URI for the Keycloak instance to obtain access tokens | `` | `http://localhost:8080` | false | +| `REACT_APP_AUTH_SERVER_URI` | URI for the Keycloak instance to obtain access tokens | | `http://localhost:8080` | false | ``` docker run -p 3000:3000 -e REACT_APP_API_SERVER_URI='http://localhost:50000' -e REACT_APP_TORNJAK_MANAGER=true ghcr.io/spiffe/tornjak-fe:latest diff --git a/docs/config-tornjak-agent.md b/docs/config-tornjak-agent.md index 4c4f1de4b..6a435760 100644 --- a/docs/config-tornjak-agent.md +++ b/docs/config-tornjak-agent.md @@ -23,7 +23,7 @@ server { | Type | Name | Description | | ---- | ---- | ----------- | | DataStore | [sql]() | Default SQL storage for Tornjak metadata | -| UserManagement | [keycloak](/docs/plugin_server_auth_keycloak.md) | Requires JWT Bearer Access Token provided for each request | +| UserManagement | [keycloak](/docs/plugin_server_auth_keycloak.md) | Requires JWT Bearer Access Token provided for each request. More details in [our auth feature doc](/docs/feature_auth.md) | ## Plugin configuration diff --git a/docs/feature_auth.md b/docs/feature_auth.md index 222a4c56..8d29d441 100644 --- a/docs/feature_auth.md +++ b/docs/feature_auth.md @@ -36,7 +36,7 @@ To configure the Auth server, please see our [Medium blog](https://medium.com/un Once the Auth server is set up, we can deploy the backend to require access tokens from our auth server, as detailed in [this followup Medium blog](https://medium.com/universal-workload-identity/guide-to-integrating-tornjak-with-keycloak-for-access-control-to-spire-40a3d5ee5f5a), with more details on the general configuration [here](https://github.com/spiffe/tornjak/blob/main/docs/config-tornjak-agent.md). -Finally, the frontend must be deployed and configured to obtain access tokens from this auth server. This can be done locally with the environment variable `REACT_APP_AUTH_SERVER_URI`: +Finally, the frontend must be deployed and configured to obtain access tokens from this auth server. More complete details of this are in [this Medium blog](https://medium.com/universal-workload-identity/guide-to-integrating-tornjak-with-keycloak-for-access-control-to-spire-40a3d5ee5f5a). This can be done locally with the environment variable `REACT_APP_AUTH_SERVER_URI`: ``` cd tornjak-frontend