local_development.md

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 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:

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 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, support OpenID Connect out-of-the-box. Other applications, like Nextcloud, require a plugin 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>