development.md



Development
The main role for this repo is provide Single-Sign-On. The architecture to make
this happen has a lot of moving components. A quick overview:


Hydra: Hydra is an Identity Provider, or IdP for short. It means connected
applications connect to Hydra to start a session with a user. Hydra provides
the application with the username and other roles/claims for the application.
This is done using the OIDC protocol. Hydra is developed by Ory and has
security as one of their top priorities. Also it is fully OpenSource.


Login application: If hydra hits a new session/user, it has to know if this
user has access. To do so, the user has to login. Hydra does not support
this, so it will redirect to a login application. This is developed by the
Stackspin team (Greenhost) and part of this repository. It is a Python Flask
application.
Because the security decisions made by kratos (see below), a lot of the
interaction is done in the web-browser, rather then server-side.
This means the login application has an UI component which relies heavily on
JavaScript. As this is a relatively small application, it is based on
traditional Bootstrap + Jquery. This elements the requirement for yet an
other build environment.


Kratos: This is Identity Manager and contains all the user profiles and
secrets (passwords). Kratos is designed to work mostly between UI (browser)
and kratos directly, over a public API endpoint without an extra server side
component/application. So authentication, form-validation etc, are all handled
by Kratos. Kratos only provides an API and not UI itself.
Kratos provides a Admin API, which is only used from the server-side flask
app to create/delete users.


Postgres: All three components need to store data. This is done in a postgres
database server. There is once instance, with three databases. As all
databases are very small this will not lead to resource limitation problems.


Prerequisites
The current login panel is not yet installed available in released  versions
of Stackspin. However, this does not prevent us from developing already on the
login panel. Experience with helm and kubernetes is expected when you follow
this manual.
On your provisioning machine, make sure to checkout:
git@open.greenhost.net:stackspin/single-sign-on.git
Be sure to check out the latest main branch. Or select a more modern branch if you
want to test / install (optional) improvements of login panel.
Once this is all fetched, installation can be done with the following steps:


Create an overwrite ConfigMap file:
For local development, we have to configure the endpoint of the application to
be pointing to our development system. In this example, we use localhost on
http.
Because of CORS and strict configuration, all needs to end up on the same
system. With modern browser, it even have to run on the same port (at least with
firefox). As we want to mimic the real life setup as much as possible as,
we will do this by running a local proxy. In production this will be handled by
kubernetes ingress configuration.
First we will tell kratos and hydra where to find the right endpoints. An
overview of all relevant end-points:
The endpoints used by the browser are (public accessible)


localhost/api -> kratos public API

localhost/login -> login flask app

The endpoint used by the login app/API are:


localhost:8000 -> kratos Admin API (only local accessible)

localhost/api  -> kratos Public API

localhost:4445 -> hydra Admin API (only local accessible)

localhost:5432 -> PostgreSQL

To reflect those public endpoints in your cluster, we have to override the
default URLs in the cluster. We do this with a ConfigMap.
It is essential SMTP/e-mail is working during development, so an example
is included on how to override those if SMTP is not working on your
cluster. Otherwise those lines are irrelevant.
Create a file with the following content: