Newer
Older
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 |
| ------------------------------------ | ------------------------------------------------------- | ------------------------- |
| `singleSignOnHost` | **FQDN of the openID Connect / oAuth2 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.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 |
| `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"] |
| `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`**!) |
Normally one would use the [Stackspin Dashboard](https://open.greenhost.net/stackspin/dashboard) to manage users. However, it is also possible to
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.
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, 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
> **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.
[^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`