helmchart.md

# Helm chart

Single sign-on adds an Authentication server to your k8s cluster, that can be used by
applications within your cluster and by external applications to log in your users.

This chart also includes a minimalistic
[user-panel](https://open.greenhost.net/stackspin/user-panel), which can be used to create
new users, assign roles to users and grant users access to applications.

## Prerequisites

 * Kubernetes 1.13+ with Beta APIs enabled
 * helm 2.14.3+
 * ORY helm chart repository installed
   * `helm repo add ory https://k8s.ory.sh/helm/charts && helm repo update`

## Configuration

You can configure the chart by changing the default values in the `./values.yaml` file.
The following table lists the configurable parameters of the single sign-on chart and their
default values. Values in **bold** letters need to be changed for Routing and TLS to work.

Please also replace all the variables that have the value `YouReallyNeedToChangeThis` to strong
passwords.

This table lists the variables you are most likely to change. Take a look at the
`values.yaml` file to see more configuration options available.

| Parameter                            | Description                                             | Default                                 |
| ------------------------------------ | ------------------------------------------------------- | -------------------------               |
| `login.image.repository`             | Name of image repository to be used for login provider  | open.greenhost.net:4567/stackspin/single-sign-on/login |
| `login.image.tag`                    | Release version of login provider image                 | main                                    |
| `login.login`                        | Username of user to create during installation          | admin@example.com                       |
| `login.password`                     | Password of user to create during installation          | ThisIsNotASecurePassword                |
| `login.db.user`                      | Database user for backend                               | stackspin                               |
| `login.db.password`                  | Database password for backend                           | stackspin                               |
| `login.db.database`                  | Database name for backend                               | stackspin                               |
| `login.db.user`                      | Database user for backend                               | stackspin                               |
| `singleSignOnHost`                   | **FQDN of the openID Connect / oAuth2 server**          | **sso.stackspin.example.net**                 |
| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server**                        | **https://sso.stackspin.example.net**         |
| `hydra.hydra.config.urls.login`      | **URI that will be used for the login page**            | **https://sso.stackspin.example.net/login**   |
| `hydra.hydra.config.urls.consent`    | **URI that will be used for permission checks**         | **https://sso.stackspin.example.net/consent** |
| `hydra.hydra.config.secrets.system`  | Secret that is used to generate secure tokens           | YouReallyNeedToChangeThis               |
| `oAuthClients`                       | A list of clients that need to be registered after installation. See [Registering clients](#registering-clients) for more info | user-panel configuration (**Change the `clientSecret`**!) |


### Manupulating user database

Normally one would use the backend panel to manage users. However, it is also possible to 
use the command line with `kubectl`

```
kubectl -n stackspin get pods
```

This will get a list of pods, we need the pod which is called `single-sign-on-login-xxxx`,
once you found the name you can interact with the flask app:

List users:

```
# kubectl exec single-sign-on-login-xxxx -- flask user list
[2021-12-07 12:18:37,065] INFO in app: Listing users
"Stackspin Admin" <admin@stackspin.net>
"Joe" <joe@stackspin.net>
"Liao" <liao@stackspin.net>
```

For all commands, please type:
```
# kubectl exec single-sign-on-login-xxxx -- flask user --help
Usage: flask user [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  create       Create a user in the kratos database.
  delete       Delete an user from the database :param email: Email...
  list         Show a list of users in the database
  recover      Get recovery link for a user, to manual update the...
  setpassword  Set a password for an account :param email: email address...
  show         Show user details.
  update       Update an user object.
```


### Registering clients

To use OpenID Connect or oAuth you need to set up an oAuth Client for every
application that needs to authenticate it's users. Setting up a client happens
in two steps: registering the client with `single-sign-on`, and configuring the
client application.

The `oAuthClients` variable in `values.yaml` contains an array of client configurations. For
each of these configurations, a `Job` will be created during the helm installation that will
do the necessary Hydra API calls to create that client. Note, however, that you still need to
[configure your application](usage#step-2--configuring-the-application) to be able to use SSO
to log in.

The `oAuthClients` variable is an array with objects. One object should be made for each
application that will use the SSO server. Each client will also be shown in the user-panel
application, so users know where to find them. This example configures the user-panel
application:

```yaml
# The name of the oauth client that needs to be the same as the application name in your 
# application configuration
clientName: user-panel
# The secret the client uses to authenticate
clientSecret: "YouReallyNeedToChangeThis"
# The url the browser will be redirected to by Hydra when the authentication process is 
# completed
redirectUri: "https://admin.stackspin.example.net/callback"
# A list of scopes the client needs access to
scopes: "openid profile email stackspin_roles"
# A url that is displayed in the user-panel for the user to navigate to the application
clientUri: "https://admin.stackspin.example.net"
# Point to a logo for the application that will be displayed in the user-panel
clientLogoUri: "https://admin.stackspin.example.net/favicon.ico"
# Set the method that the oAUth client uses to authenticate agains the oAuth server i.e. to
# retrieve tokens or userinfo
tokenEndpointAuthMethod: "client_secret_basic"
# Resource types the client is allowed to use to perform authentication and userinfo requests
responseTypes:
  - "token"
# Specifies the methods the client can use to retrieve access tokens from the oAuth server
grantTypes:
  - "implicit"
```

## Installing and uninstalling the Chart

To install the chart with the realease name `single-sign-on` first clone the repository,
and then run helm install.

```
$ git clone https://open.greenhost.net/stackspin/single-sign-on
$ cd single-sign-on/helmchart/single-sign-on/
$ helm install -n single-sign-on .
```

The last command will deploy the single sign-on components on your server and applies a
default configuration. You should change the default configuration before running the command.
The [configuration](#configuration) section lists all configuration parameters.

In case you already ran the install command, you can uninstall the deployment by executing:

```
$ helm list     # [OPTIONAL] - Lists all deployed releases
$ helm delete single-sign-on --purge
```

> **WARNING**: Executing the `delete` command with the `purge` flag will delete all data that is related to the applications. Don't run this command in a production environment if you are not absolutely sure that you have a restorable backup of your data.