# 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 | | ------------------------------------ | ------------------------------------------------------- | ------------------------- | | `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`**!) | ### 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. 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.