Basic doc in README

README.md

@@ -0,0 +1,81 @@
+# OIDC test application
+
+*oidc-test* is a simple web application for testing different OIDC providers,
+and a template for Python FastAPI.
+
+It has been tested with some OIDC providers like Auth0 (public),
+Keycloak (private), Forgejo (private and public with Codeberg).
+
+It should work with Google, Azure and other cloud services providing
+an OIDC authentication service.
+
+It is a *stateless* application (no data are saved and it restarts as vanilla),
+and there is no database connection,
+although models are defined with the SQLModel library and it is designed
+as a template for integration in other FastAPI/SQLModel applications.
+
+Feedback welcome.
+
+## RBAC
+
+The application is also a playground for RBAC (Role Based Access control)
+implemented with OIDC.
+The application has few different resources (web pages) for testing RBAC.
+The home page checks (with Javascript) if those are accessible
+by the end user for convenience, color-coding the links to those pages.
+
+2 roles are defined in the application: foorole and barrole.
+
+If the user has these roles defined in the ID provider and they are exposed
+in the `userinfo` endpoint,
+the return code of these pages should be HTTP success (200).
+
+If the user does not have the required role(s),
+a HTTP access denied (401) code is returned.
+
+## Deployment
+
+A Python package and a container are provided.
+
+## Configuration
+
+The application reads a simple `yaml` file that you should configure
+to expose different login options in the application's "Login" box, with values
+given by the OIDC providers.
+
+For example:
+
+```text
+oidc:
+  secret_key: "ASecretNoOneKnows"
+  show_session_details: yes
+  providers:
+    - id: auth0
+      name: Okta / Auth0
+      url: "https://<your_auth0_app_URL>"
+      client_id: "<your_auth0_client_id>"
+      client_secret: "client_secret_generated_by_auth0"
+      hint: "A hint for test credentials"
+
+    - id: keycloak
+      name: Keycloak at somewhere
+      url: "https://<the_keycloak_realm_url>"
+      client_id: "<your_keycloak_client_id>"
+      client_secret: "client_secret_generated_by_keycloak"
+      hint: "User: foo, password: foofoo"
+
+    - id: codeberg
+      name: Codeberg
+      url: "https://codeberg.org"
+      client_id: "<your_codeberg_client_id>"
+      client_secret: "client_secret_generated_by_codeberg"
+```
+
+The application reads the `OIDC_TEST_SETTINGS_FILE` environment variable
+to determine the location of this file at startup.
+
+For example, to run on port 8000 in a container, with the setting file in the current working directory:
+
+```sh
+OIDC_TEST_CONFIG_FILE=/app/settings.yaml podman run -p 8000:80 --mount type=bind,source=settings.yaml,destination=/app/settings.yaml code.philo.ydns.eu/philorg/oidc-fastapi-test:latest
+```