Skip to content
Snippets Groups Projects
Commit 57d765a4 authored by Mark's avatar Mark
Browse files

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

Resolve "Document SSO"

Closes #18

See merge request openappstack/single-sign-on!11
parents 3d0e2e63 9a118803
No related branches found
No related tags found
2 merge requests!13Apply new changes to 0.2 release branch,!11Resolve "Document SSO"
Pipeline #2383 failed with stage
Stage:
    in 2 minutes and 2 seconds
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 380 additions and 115 deletions
    .gitignore
    + 1
    − 0
    View file @ 57d765a4
    docs/_build/
    .env
    __pycache__
    *.lock
    ......
    README.md
    + 1
    − 49
    View file @ 57d765a4
    # 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
    VERSION 0 → 100644
    + 1
    − 0
    View file @ 57d765a4
    0.2
    docs/Makefile 0 → 100644
    + 20
    − 0
    View file @ 57d765a4
    # 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)
    docs/conf.py 0 → 100644
    + 60
    − 0
    View file @ 57d765a4
    # 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'
    docs/helmchart.md 0 → 100644
    + 114
    − 0
    View file @ 57d765a4
    # 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.
    docs/index.rst 0 → 100644
    + 19
    − 0
    View file @ 57d765a4
    .. 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
    docs/local_development.md 0 → 100644
    + 92
    − 0
    View file @ 57d765a4
    # 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>
    ```
    docs/make.bat 0 → 100644
    + 35
    − 0
    View file @ 57d765a4
    @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
    docs/requirements.txt 0 → 100644
    + 3
    − 0
    View file @ 57d765a4
    sphinx>=2.3.1
    sphinx_rtd_theme>=0.4.3
    recommonmark>=0.6.0
    docs/usage.md 0 → 100644
    + 28
    − 0
    View file @ 57d765a4
    # 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/)
    helmchart/single-sign-on/README.md
    + 1
    − 62
    View file @ 57d765a4
    # 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)
    helmchart/single-sign-on/values.yaml
    + 5
    − 4
    View file @ 57d765a4
    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"
    ......
    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