From 25f0e1c9f1ed35b9822eec33cbc1343628d41cfd Mon Sep 17 00:00:00 2001
From: Scott Koranda <skoranda@gmail.com>
Date: Tue, 31 Mar 2020 09:43:41 -0500
Subject: [PATCH] Added details for simple development sandbox

Added details to the documentation for the simple development sandbox
for how to add more test users and how to mock up Apache CGI environment
variables.
---
 docs/simple-development.md | 90 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/docs/simple-development.md b/docs/simple-development.md
index 3f94345..ee4f1f2 100644
--- a/docs/simple-development.md
+++ b/docs/simple-development.md
@@ -139,6 +139,96 @@ docker-compose stop
 docker-compose down
 ```
 
+### Adding more test users
+
+The simple development sandbox uses 
+[standard HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication),
+and in particular the 
+[Apache HTTP Server implementation of basic authentication](https://httpd.apache.org/docs/2.4/howto/auth.html).
+The default user is `registry.admin` and the default password is `password`.
+
+To add more test users begin by copying the default basic authentication file
+from a running container to your file system, for example
+
+```
+docker cp comanage-registry:/etc/apache2/basic-auth basic-auth
+```
+
+Move that file to somewhere on your filesystem where you can use it as another
+bind-mount volume for the COmanage Registry container, for example
+
+```
+mkdir -p /srv/docker/etc/apache2/
+cp basic-auth /srv/docker/etc/apache2/basic-auth
+```
+
+Edit the docker-compose file and add the bind-mount for the `comanage-registry`
+service, for example
+
+```
+volume:
+    - /srv/docker/etc/apache2/basic-auth:/etc/apache2/basic-auth
+```
+
+Edit the basic-auth file using the `htpasswd` command. For example
+to add the user `skoranda` run
+
+```
+htpasswd /srv/docker/etc/apache2/basic-auth skoranda
+```
+
+Restart the services and you can now authenticate to COmanage Registry
+using the username and password combination you added to the password
+file.
+
+### Mocking Apache CGI environment variables
+
+Some COmanage Registry functionality, such as the
+[Env Source](https://spaces.at.internet2.edu/x/swr9Bg)
+Organizational Identity Source, requires that the Apache HTTP Server
+set Apache CGI environment variables. These environment variables are
+usually set by more sophisticated authentication modules like the
+Shibboleth Service Provider (SP). You can mock up the same 
+behavior using the
+[SetEnv](https://httpd.apache.org/docs/2.4/mod/mod_env.html)
+directive for Apache.
+
+To mock up an environment variable begin by copying the default Apache
+configuration file from a running container to your file system, for example
+
+```
+docker cp comanage-registry:/etc/apache2/sites-available/000-comanage.conf
+```
+
+Move that file to somewhere on your filesystem where you can use it as another
+bind-mount volume for the COmanage Registry container, for example
+
+```
+mkdir -p /srv/docker/etc/apache2/
+cp basic-auth /srv/docker/etc/apache2/sites-available/000-comanage.conf
+```
+
+Edit the docker-compose file and add the bind-mount for the `comanage-registry`
+service, for example
+
+```
+volume:
+    - /srv/docker/etc/apache2/sites-available/000-comanage.conf:/etc/apache2/sites-available/000-comanage.conf
+```
+
+Edit the `000-comanage.conf` file and add a `SetEnv` directive, for example
+
+```
+SetEnv OIS_ENV_NAME_GIVEN Scott
+SetEnv OIS_ENV_NAME_FAMILY Koranda
+SetEnv OIS_ENV_MAIL skoranda@gmail.com
+```
+
+Restart the services and authenticate to COmanage Registry.
+After authenticating COmanage Registry should "see" those
+environment variables defined for the authenticated user.
+
+
 ### Important Notes
 The instructions above are *not suitable for a production deployment* 
 since the deployed services use default and easily guessed passwords.