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/openappstack/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                                 |
| ------------------------------------ | ------------------------------------------------------- | -------------------------               |
| `consentProviderImage.repository`    | Name of image repository to be used for consent provider| open.greenhost.net:4567/openappstack/single-sign-on/consent_provider |
| `consentProviderImage.tag`           | Release version of consent provider image               | master                                  |
| `loginProviderImage.repository`      | Name of image repository to be used for login provider  | open.greenhost.net:4567/openappstack/single-sign-on/login_provider |
| `loginProviderImage.tag`             | Release version of login provider image                 | master                                  |
| `singleSignOnHost`                   | **FQDN of the openID Connect / oAuth2 server**          | **sso.oas.example.net**                 |
| `userpanel.ingress.host`             | **FQDN of the userpanel**                               | **admin.oas.example.net**               |
| `userbackend.username`               | Username of the admin user                              | admin                                   |
| `userbackend.password`               | Password of the admin user                              | YouReallyNeedToChangeThis               |
| `userbackend.email`                  | Email address of the admin user                         | admin@example.net                       |
| `userbackend.postgres.password`      | Root pw of the psql DB                                  | postgres                                |
| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server**                        | **https://sso.oas.example.net**         |
| `hydra.hydra.config.urls.login`      | **URI that will be used for the login page**            | **https://sso.oas.example.net/login**   |
| `hydra.hydra.config.urls.consent`    | **URI that will be used for permission checks**         | **https://sso.oas.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`**!) |

### 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.oas.example.net/callback"
# A list of scopes the client needs access to
scopes: "openid profile email openappstack_roles"
# A url that is displayed in the user-panel for the user to navigate to the application
clientUri: "https://admin.oas.example.net"
# Point to a logo for the application that will be displayed in the user-panel
clientLogoUri: "https://admin.oas.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/openappstack/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.