local_dev_remote_kratos.md

# Introduction

kratos manages the user database. It has profiles of all users and keeps track
of lost password policies, welcome e-mails, TOTP (future), First, Last name etc.

Kratos is a flexible identity manager where our own "schema" can be defined with
the information we want for Stackspin. 

Kratos has a public API, which should be accessible for the world, and an admin API
which is ONLY accessible for our panel/board to manage users.

At the point of writing BOTH end-point are not public yet. We can use SSH port
forwards during development.

# Installation

The current kratos version is not yet merged to master. However, this does not
prevent us from developing already. To use / add the kratos backend, the
following needs to be done:

On your provisioning machine, make sure to checkout:

`git@open.greenhost.net:openappstack/single-sign-on.git`

Be sure to choose the kratos branch: `76-use-kratos-as-identity-manager`

Once this is all fetched, installation can be done with the following steps:

1. Suspend the automatic updating: 
   As we are gonna use a non-release version, the flux subsystem will rollback
   changes to follow the released versions. However, during development we want
   to prevent this. We can suspend the service with:

```
flux suspend source chart oas-single-sign-on
```

2. Make a backup of the current keys and configuration values. We needs those
when we install the new version of the `single-sign-on` helmchart:

```
helm get values single-sign-on -n oas > /to/a/path/my_cluster_values.yaml
```

3. Install the single-sign-on helmchart with kratos service

```
cd helmchart/single-sign-on
helm upgrade -f /to/a/path/my_cluster_values.yaml single-sign-on . -n oas --debug
```

This will install the latest version. 

**Note**: Known issue, in some circumstances the installation fails because
kratos automigration kicks in too early. This needs more investigation. If you run 
into this problem, try the following: 

1. Open the file `helmchart/single-sign-on/values.yaml`
2. Set the `autoMigrate` on line 151 to `false`
3. Rerun the upgrade.

After successful upgrade, adjust the value back to `true` and rerun the upgrade
once again. As the PVC and database server are now up and running, the
automigration works as expected

It looks there is some kind of race condition, by first disabling the
automigration, the storage to store the database is created, so on the second run, 
this race condition is not hit. This *should* not happen with kubernetes, so 
maybe the cause is something else.

# Development

To develop, one needs access to kratos from the development system. A helper 
script is available in this directory to setup the redirect the ports, 
giving access to localhost port 8000 and 8080 for the admin/public port of
kratos.

```
./set-ssh-tunnel.sh `oas.example.com`
```

(the tunnel goes to the kubernetes node, so *not* to your provisioning machine.

kratos API is specified on their website:

https://www.ory.sh/kratos/docs/reference/api/

Some example can be found in:

```
./api-examples.sh
```