Add contributing md

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing
+
+- [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)
+- [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).
+
+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
+
+## Building Executables and Images
+
+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-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
+
+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
+
+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. 
+
+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)
+
+### 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:
+
+```console
+cd tornjak-frontend
+REACT_APP_API_SERVER_URI=http://<tornjak_API>/  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
+
+You may run the uncontainerized Tornjak manager by locally running the following:
+
+```
+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, as is described in our [USAGE doc](./USAGE.md).
+
+### 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).

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)
@@ -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://<tornjak_API>/  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.  

USAGE.md

@@ -0,0 +1,58 @@
+# 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
+
+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                           |         | <path>    | true     |
+| `-tornjak-config\|-t` | Config file path for Tornjak (see our [configuration reference](./docs/config-tornjak-agent.md)) | | <path> | 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 <SPIRE CONFIG PATH> -t <TORNJAK CONFIG PATH> -expandEnv
+```
+
+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. 
+
+For more instructions on Tornjak config formatting, please see our [configuration reference](./docs/config-tornjak-agent.md).
+
+## 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 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. 
+
+

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
 

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.  

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/*"
+        }
+    }
+```