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, 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 for more info	user-panel configuration (Change the clientSecret!)

Manipulating user database

Normally one would use the 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 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:

# 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 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.