Commit 57d765a4 authored by Mark's avatar Mark

Merge branch '18-document-sso' into 'master'

Resolve "Document SSO"

Closes #18

See merge request !11
parents 3d0e2e63 9a118803
Pipeline #2383 failed with stage
in 2 minutes and 2 seconds
docs/_build/
.env
__pycache__
*.lock
......
# Install
Clone the repo and make sure to also fetch the submodules.
```
git submodule update --init
```
Installation should be done via the helm using the helmchart contained in `./helmchart`.
Make sure to edit the values in `./helmchart/single-sign-on/values.yaml` according to your needs
For Details on how to configure the chart. Refer to `./helmchart/single-sign-on/README.md`
# Using SSO
To use OpenID Connect or oAuth you need to set up an oAuth Client for every application that
needs to authenticate it's users. You can leverage the Hydra Admin API to create oAuth clients.
As a starting point, you can have a look at the script provided in `test/`.
To use SSO, configure your oAuth client (for example nextcloud) and create a new oAuth client object.
After your server is running, refer to `https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` as a reference on how to configure your openID Connect or oAuth client.
# Testing
In order to run tests locally, you can start the environment via `docker-compose`.
Install docker-compose via `pip install docker-compose` after you [insalled
docker](https://docs.docker.com/v17.12/install/) on your machine.
Running `docker-compose up --build` after that builds and starts all containers.
The default configuration works if you are running the setup on your local
machine. You need to change the following values in the docker-compose.yml file in case
you run the containers on a remote machine:
```
environment:
- URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
- URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
- URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
- URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
- URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/
```
Notice that you need to create users and applications before being able to login.
You can use the scripts located in `user-panel/utils` to create users for testing.
If you don't have a test application yourself, you can use the small OpeinID Connect
test application located at `test/login_logout/`. Instructions on how to run the test
application can be found in `test/login_logout/README.md`.
Also refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests that are
contained in this repository.
Please refer to the [online documentation](...) for all the details
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'single-sign-on'
copyright = '2020, OpenAppStack'
author = 'OpenAppStack'
# The full version, including alpha/beta/rc tags
with open('../VERSION') as version_file:
release = version_file.read()
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'recommonmark'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Readthedocs.io needs us to tell it what the index file is. This defaults to
# 'contents'
master_doc = 'index'
# 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.
.. single-sign-on documentation master file, created by
sphinx-quickstart on Thu Jan 9 10:37:53 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to single-sign-on's documentation!
==========================================
This project provides a single sign on solution based on
[hydra](https://github.com/ory/hydra) and in combination with a [user
panel](https://open.greenhost.net/openappstack/user-panel).
.. toctree::
:maxdepth: 2
:caption: Contents:
usage
helmchart
local_development
# Local development
In order to run the single-sign-on system locally, you can start the environment
via `docker-compose`. Install docker-compose via `pip install docker-compose`
after you [insalled docker](https://docs.docker.com/v17.12/install/) on your
machine.
Build and start all docker containers by running:
```
docker-compose up --build
```
The default configuration works if you are running the setup on your local
machine. You need to change the following values in the docker-compose.yml file
in case you run the containers on a remote machine:
```yaml
environment:
- URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
- URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
- URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
- URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
- URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/ ```
```
Notice that you need to create users and applications before being able to
login. You can use the scripts located in `user-panel/backend/utils` to create
users for testing.
If you don't have an application you want to use as an OIDC client, you can use
the small OpeinID Connect test application located at `test/login_logout/`.
Instructions on how to run the test application can be found in
`test/login_logout/README.md`.
Refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests that
this repository contains.
## Adding clients
This section covers how you can manually add clients to the single-sign-on
server.
Note that we recommend using the helm chart installation if you want to add
clients. Take a look at the [helmchart documentation](helmchart) to see how you
can register clients if you install `single-sign-on` with the helm chart.
However, if you just want to test something on your docker-compose setup, keep
reading.
### Step 1: registering the client
`single-sign-on` uses Hydra to provide an API for creating clients. As a
starting point, you can have a look at `test/create-hydra-client.bash`. For more
information on the available scopes and endpoints, you can take a look at
`https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration`.
Remember the `client_name` and `client_secret` you use to register your
application. You will need to enter the same name and secret in your application
configuration in the next step.
### Step 2: configuring the application
You still need to configure the application you want to be able to log into to
use the client you just registered. Some applications, like
[Grafana](https://grafana.com/docs/grafana/latest/auth/generic-oauth/), support
OpenID Connect out-of-the-box. Other applications, like
[Nextcloud](https://nextcloud.com/), require [a
plugin](https://apps.nextcloud.com/apps/sociallogin) to add this support.
Different applications support different authentication methods. Again, take a
look at the information available at
`https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` to see the methods
available to you with this single sign on server.
### Step 3: configure the user backend
After Step 2 you should be able to use the single sign-on function of your
application. After starting the authentication via single sign-on you should be
redirected to a login page that looks different from your application's default
login page. The only thing you need to do now is add the application to the user
panel and add application permission to your users.
The easiest way to do so is to use the `utils` scripts in
`user-panel/backend/utils`.
If you are running your setup with docker compose simply execute:
```
docker exec -it $(docker ps | grep backend | awk '{ print $1 }') bash ./utils/create-application.bash <application-name> "<description>"
docker exec -it $(docker ps | grep backend | awk '{ print $1 }') bash ./utils/grant-access.bash <username> <application-name>
```
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
sphinx>=2.3.1
sphinx_rtd_theme>=0.4.3
recommonmark>=0.6.0
# Usage
## Installlation instructions
Clone the repo and make sure to also fetch the submodules.
```
git submodule update --init
```
Installation should be done via the helm using the helmchart contained in
`./helmchart`. Make sure to edit the values in
`./helmchart/single-sign-on/values.yaml` according to your needs. To install the
helm chart, make sure Helm is properly set up in your Kubernetes cluster, then:
```
cd helmchart # Enter the helm chart directory
helm dep update # Download helm charts this chart relies on
helm install . # Run the installation command
```
For Details on how to configure the chart. Refer to [the Helm chart
chapter](helmchart)
### Managing users
`single-sign-on` includese a simple `user-panel` to manage users. To read more
about this, see the [user panel
documentation](https://docs.openappstack.net/projects/user-panel/)
# Single sign-on
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.
| Parameter | Description | Default |
| ------------------------------------ | ------------------------------------------------------- | ------------------------- |
| `singleSignOnHost` | **FQDN of the openID Connect / oAuth2 server** | **sso.oas.example.net** |
| `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 |
| `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 |
| `userpanel.ingress.host` | **FQDN of the userpanel** | **admin.oas.example.net** |
| `userpanel.oAuth.client_secret` | oAuth2 client secret | YouReallyNeedToChangeThis |
| `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 |
## 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.
Please refer to the [online documentation](.../helmchart)
replicaCount: 1
consentProviderImage:
# consentProviderImage.tag and consentProviderImage.pullPolicy should be the same as
# loginProviderImage.tag and loginProviderImage.pullPolicy as the images are released
# together in order to guarantee compatibility
# consentProviderImage.tag and consentProviderImage.pullPolicy should be the same as
# loginProviderImage.tag and loginProviderImage.pullPolicy as the images are released
# together in order to guarantee compatibility
<< : &IMAGE_DEFAULTS_SSO { tag: "master", pullPolicy: "Always" }
repository: "open.greenhost.net:4567/openappstack/single-sign-on/consent_provider"
loginProviderImage:
<< : *IMAGE_DEFAULTS_SSO
repository: "open.greenhost.net:4567/openappstack/single-sign-on/login_provider"
......@@ -131,7 +132,7 @@ oAuthClients:
# oAuthClients[].tokenEndpointAuthMethod sets the method that the oAUth client uses to
# authenticate agains the oAuth server i.e. to retrieve tokens or userinfo
tokenEndpointAuthMethod: "client_secret_basic"
# oAuthClients[].responseTypes specifies the type of ressource an oAuth client uses to perform
# oAuthClients[].responseTypes specifies the type of resource an oAuth client uses to perform
# authentication and userinfo requests
responseTypes:
- "token"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment