# 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-points are not public yet. We can use SSH port
forwards during development.

# Installation

The current kratos version is not yet installed in the released versions of 
Stackspin. However, this does not prevent us from developing already with
kratos. To use / add the kratos backend, the following needs to be done:

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. Or select a more modern brach if you
want to test / install (optional) improvements of the kratos system. 

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 application management system 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 stackspin-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 stackspin > /to/a/path/my_cluster_values.yaml
```

3. Install all helm dependencies

```
helm dep update
```

4. Configure variables

Currently the is a default password configured for postgresql in `values.yaml`.
It is advised to change this password before installation.

The password can be found at:

```
postgresql:
  postgresqlDatabase: kratos
  postgresqlUsername: kratos
  postgresqlPassword: ChangeThisPassword
```

Please make sure it is in sync with the password at

```
kratos:
  kratos:
    config:
      dsn: postgres://kratos:ChangeThisPassword@single-sign-on-postgresql:5432/kratos
``` 

Same is true for the SMTP service, this config entry can be found at:

```
kratos:
  kratos:
    config:
      courier:                                                                   
        smtp:                                                                    
          connection_uri: smtps://username:password@smtp.example.com:456/
```

5. 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 stackspin --debug
```

This will install the latest version. 

# 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 `stackspin.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
```