# Single Sign-on 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`
* A PostgreSQL database with 3 users and 3 databases called
- `stackspin`
- `hydra`
- `kratos`
Note that you need to enter the URI, usernames and passwords for these
databases as values when you run `helm install`. See
[Configuration](#configuration) for more information.
## 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 before installation.
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 |
|--------------------------------------|---------------------------------------------------------|-----------------------------------------|
| `singleSignOnHost` | **FQDN of the openID Connect / OAuth 2 server** | **sso.stackspin.example.net** |
| `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.user` | Username of user to create during installation | admin@example.com |
| `login.password` | **Password of user to create during installation** | **ThisIsNotASecurePassword** |
| `login.db.hostname` | **Database hostname for backend** | **single-sign-on-database** |
| `login.db.password` | **Database password for backend** | **YouReallyNeedToChangeThis** |
| `login.db.database` | Database name for backend | stackspin |
| `login.db.user` | Database user for backend | stackspin |
| `kratos.kratos.identitySchemas` | Tuple of filenames and JSON data to install as available schema file | See values.yaml |
| `kratos.kratos.config.identity.default_schema_url` | Location of default schema file | file:///etc/config/identity.default.schema.json |
| `kratos.kratos.config.dsn` | **Database endpoint** | postgres://kratos:kratos@single-sign-on-postgresql:5432/kratos |
| `kratos.kratos.serve.public.base_url` | **URL where to find kratos public API** | **https://sso.stackspin.example.net/api/** |
| `kratos.kratos.selfservice.default_browser_return_url` | **Default URL to return to with unknown request** | **https://sso.stackspin.example.net/login/login** |
| `kratos.kratos.selfservice.flows.recovery.lifespan` | Time recovery link is valid for password reset | 15m |
| `kratos.kratos.selfservice.flows.recovery.ui_url` | **Where to link to for recovery** | **https://sso.stackspin.example.net/login/recovery** |
| `kratos.kratos.selfservice.flows.login.ui_url` | **Where to link to for login** | **https://sso.stackspin.example.net/login/login** |
| `kratos.kratos.selfservice.flows.settings.ui_url` | **Where to link to for setting/profile update** | **https://sso.stackspin.example.net/login/settings** |
| `kratos.kratos.selfservice.flows.registration.ui_url` | **Where to link to for account registration** | **https://sso.stackspin.example.net/login/registration** |
| `kratos.kratos.secrets.session` | **Array of strings for session secrets** | See values.yaml |
| `kratos.kratos.courier.smtp.connection_uri` | **Config of SMTP server** | **smtps://username:password@smtp.example.net:456/** |
| `kratos.kratos.courier.smtp.from_address` | **From email address** | **no-reply@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.dsn` | **Database endpoint for Hydra** | postgres://hydra:hydra@single-sign-on-postgresql:5432/hydra |
| `hydra.hydra.config.secrets.system` | **Secret that is used to generate secure tokens** (`str[]`) | ["YouReallyNeedToChangeThis"] |
### Manipulating user database
Normally one would use the [Stackspin Dashboard](https://open.greenhost.net/stackspin/dashboard) to manage users. However, it is also possible to
use the command line with `kubectl`
```
kubectl get pod -n stackspin -l 'app.kubernetes.io/name=single-sign-on-login'
```
This will get the pod which provides the login panel. The pod name looks like
`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.
#### Step 1. Configure Hydra
We use Hydra Maester to register the clients with Hydra. This means that you
need to create a Kubernetes object that looks like this:
```yaml
apiVersion: hydra.ory.sh/v1alpha1
kind: OAuth2Client
metadata:
name: dashboard-oauth-client
# Has to live in the same namespace as the secret mentioned below
namespace: default
spec:
# Specifies the methods the client can use to retrieve access tokens from the
# OAuth server
grantTypes:
- authorization_code
- refresh_token
- client_credentials
- implicit
# Resource types the client is allowed to use to perform authentication and
# userinfo requests
responseTypes:
- id_token
- code
# A list of scopes the client needs access to
scope: "openid profile email stackspin_roles"
# A secret that contains `client_id` and `client_secret`, used by both Hydra
# and the client.
secretName: stackspin-dashboard-oauth-variables
# The url the browser will be redirected to by Hydra when the authentication
# process is completed
redirectUris:
- https://dashboard.${domain}/_oauth/oidc
# Set the method that the oAUth client uses to authenticate agains the OAuth
# server i.e. to retrieve tokens or userinfo
tokenEndpointAuthMethod: client_secret_post
```
Refer to the [Hydra Maester
documentation](https://github.com/ory/k8s/blob/master/docs/helm/hydra-maester.md) for more information.
### Step 2. Configure client application
The next step is to configure the client application. Most software that
supports this will have a page in your documentation that describes how to do
so. You will have to change the values given in the example oauth specification
above according to the application's specifications.
During the application configuration, you'll need to enter the "Client ID" and
the "Client secret". You can find these in the secret referenced by the
OAuth2Client. If the secret exists before you create the `OAuth2Client`, Maester
will read the `client_id` and `client_secret` from it and use it. If not,
Maester will generate a secret and use that. In both cases the secret needs to
be in the same namespace as the `OAuth2Client` object.
## Installing and uninstalling the Chart
To install the chart, add our helm repository[^1] and run the installation:
```
# helm repo add single-sign-on https://open.greenhost.net/api/v4/projects/8/packages/helm/api/stable
$ helm install -n single-sign-on single-sign-on/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
```
> **WARNING**: Executing the `delete` command 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.
## Known issues
Short after the installation, the Hydra and Kratos pod will error a few times
before they run correctly and enter the "Ready" state. This is because the Hydra
helm chart is not built for running your PostgresQL server in
the same Kubernetes cluster as the helm chart. The problem is that the Hydra
"automigration" usually runs as a pre-install step of the helm chart. We cannot
do that because in this chart the Hydra database is actually installed after
pre-install hooks have finished running. Ory doesn't want to solve this issue,
because they're fundamentally against running databases on Kubernetes.
As a result, we've had to include [jobs that run the
[Hydra](https://open.greenhost.net/stackspin/single-sign-on/-/blob/main/helmchart/single-sign-on/templates/job-migration-hydra.yaml)
and [Kratos
migration](https://open.greenhost.net/stackspin/single-sign-on/-/blob/main/helmchart/single-sign-on/templates/job-migration-kratos.yaml)
inside our single sign-on helm chart. However, we can't modify the Hydra and
Kratos pods without forking the whole helm charts. As a result the Hydra and
Kratos container will fail to come up before those jobs have finished.
Once the jobs have finished, they should work well, though. The migration jobs
are run on upgrades as well, but might cause less issues there because they take
less time.
[^1]: If you want to test a version that is not on the `main` branch yet, use `https://open.greenhost.net/api/v4/projects/8/packages/helm/unstable`