diff --git a/docs/index.rst b/docs/index.rst
index 7a59ea267199a6f0cd4baf11c39e38d7a0829234..4b52fde20be43edf4f7886944d9cb8832c98aa97 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,9 +27,10 @@ For more information, go to `the OpenAppStack website`_.
    :caption: Contents:
 
    installation_instructions
-   upgrading
    testing_instructions
+   usage
    troubleshooting
    maintenance
+   upgrading
    design
    reference
diff --git a/docs/installation_instructions.md b/docs/installation_instructions.md
index 434fa038b650289753c5e8819e4fb9774304c8d7..dc975734e9173f5c31a3aa6efecd7933da97346a 100644
--- a/docs/installation_instructions.md
+++ b/docs/installation_instructions.md
@@ -207,7 +207,7 @@ meets our [prerequisites](#prerequisites).  You'll need its *hostname* and its
 > you are automating this, please use this to ensure you use "staging"
 > certificates from Let's Encrypt, to reduce the stress on their servers.
 > However, ONLYOFFICE and single sign-on integration require valid (live)
-> certificates to work properly so please don't use this option by default. 
+> certificates to work properly so please don't use this option by default.
 
 If you want your cluster to be reachable under the fully qualified domain name
 (`FQDN`) `oas.example.org`, the corresponding parameters would be:
@@ -289,81 +289,3 @@ continue to the Usage section.
 Because OpenAppStack is still under development, we would like you to follow our
 [testing instructions](testing_instructions) to make sure that the setup process
 went well.
-
-## Usage
-
-After all the applications are installed, the first thing to do is log into
-https://admin.oas.example.org. Here you can find the "user panel", a place where
-you can create, edit and delete users. You can log in with the user "admin". The
-password can be found in
-`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
-will see an overview of all the applications your user has access to. For more
-information on how to create users and give them access to applications, take a
-look at the [user panel
-documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
-
-> **NOTE:** at the moment none of the applications are available at
-> `oas.example.org`, we only provide applications in subdomains. In the future
-> this might change.
-
-These applications should be available after the installation is completed:
-
-* [OAS User panel](https://open.greenhost.net/openappstack/user-panel/), our
-  user panel can be used to create and edit users. These users can be used to
-  log into the applications listed below
-* [Nextcloud](https://nextcloud.com/), a file sharing and communication
-  platform;
-  - Your Nextcloud is available at https://files.oas.example.org
-* [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
-  document editing suite;
-  - Your documents saved in Nextcloud will be opened in ONLYOFFICE
-* [Rocket.Chat](https://rocket.chat/), a team chat application;
-  - Rocket.Chat is available at https://chat.oas.example.org. Single sign-on is
-    not implemented yet for Rocket.Chat. You need to log in with the `admin`
-    user. Its password can be found in
-    `clusters/my-cluster/secrets/rocketchat_admin_password`.
-* [WordPress](https://wordpress.com), a website content management system.
-  - WordPress is available at https://www.oas.example.org. Click the "Log in"
-    button and then click "Login with OpenID Connect" to use the single sign-on
-    server. Note that if you log in with the single sign-on server, you will not
-    have "admin" rights within WordPress. For that, use the admin credentials in
-    the `secrets` folder.
-* [Grafana](https://grafana.com) that shows you information about the status of
-  your cluster.
-  - Read more about Grafana in the [monitoring chapter below](#monitoring)
-
-### Known limitations
-
-- Single sign-on is still in an experimental phase. We are still working on
-  transferring "roles" from users in the central database to applications, so
-  your SSO's admin user gets admin permissions in all the applications.
-  - This means that if you need to login as an Admin user, you need to use the
-    admin credentials in `clusters/my-cluster/secrets/<app_admin_password>`.
-  - To use single sign-on with Grafana, your user *needs* to have an email
-    address set in the user database.
-- Nextcloud does not send emails yet. You can configure sending emails by going
-  to Settings -> Basic settings -> Email server and entering SMTP email
-  credentials.
-- Rocket.Chat does not send emails yet either
-- Rocket.Chat is not integrated with the single sign-on system. This will be
-  implemented soon in a new release.
-
-### Monitoring
-
-You should be able to access the visual interface to the monitoring system,
-Prometheus, at `https://grafana.oas.example.org/`. Admin users can log into
-Grafana. You can create and add admin users through the User panel.
-
-### Other applications installed into the cluster
-
-Besides these applications, some other auxiliary components are installed:
-
-* [OAS local-storage](https://open.greenhost.net/openappstack/local-storage) provides an easy way for the cluster to use a directory on
-  the node (by default `/var/lib/OpenAppStack/local-storage`) for storage;
-* [NGINX](https://www.nginx.com) is a webserver that functions as a so-called ingress controller,
-  routing web traffic that enters the cluster to the various applications;
-* [cert-manager](https://cert-manager.io) acquires and stores [Let's
-  Encrypt](https://letsencrypt.org/) certificates, enabling encrypted web
-  traffic to all applications running in the cluster;
-* [Flux](https://fluxcd.io) checks for application updates approved by the
-  OpenAppStack team and installs them automatically.
diff --git a/docs/maintenance.md b/docs/maintenance.md
index 883a23cfc31369e60975eeef4f96906873a8f4ee..2816e2782f4f589006a42a65550ff7bf5850e1ae 100644
--- a/docs/maintenance.md
+++ b/docs/maintenance.md
@@ -50,6 +50,10 @@ Filter out redundant `flux` messages:
 
     { app = "flux" } !~ "(unchanged | event=refreshed | method=Sync | component=checkpoint)"
 
+Debug oauth2 single sign-on with rocketchat:
+
+    {container_name=~"(hydra|rocketchat)"}
+
 
 #### Cert-manager
 
diff --git a/docs/testing_instructions.md b/docs/testing_instructions.md
index 52d7d99492604b42555e6b7063ac009558eecd42..a3ae01b6ca2db9dda8e8fcb84fcff93b45e44128 100644
--- a/docs/testing_instructions.md
+++ b/docs/testing_instructions.md
@@ -21,26 +21,20 @@ First we'd like you to setup an OpenAppStack cluster by yourself, following the
 Please run the [command line tests](troubleshooting.md) which checks the overall
 functionality of your cluster and include the output in your feedback.
 
-## User panel
+## Usage
 
-Please open https://admin.oas.example.org in the browser. You should see
-"Welcome to OpenAppStack" and a Login button. Please try logging in.
-
-An admin user was generated with the username `admin`. The password is saved in
-`clusters/my-cluster/secrets/userbackend_admin_password` in the OpenAppStack
-directory on your local machine.
-
-After logging in to the user panel, please try to make a new user. Don't forget
-to give it a username and password, and press "Save" afterwards.
+Please go through the [Usage documentation](./usage.md) and make sure you
+complete all steps.
 
 ## Nextcloud
 
 ### Logging into Nextcloud
 
-Please browse to https://files.oas.example.org and try to log in. You should
-have a buttin saying "Login with OpenAppStack". Try that button. Please try
-logging in with your admin account, as well as the user you created in the user
-panel.
+Please browse to https://files.oas.example.org and try to log in using single
+sign-on. Use the button labeled `Login with OpenAppStack`.
+Please try logging in with your admin account and configure the email settings
+as shown in the Usage doc.
+After that please login with the user you created in the user panel.
 
 ### Nextcloud client application
 
@@ -48,7 +42,7 @@ panel.
 * If you feel like it, please try the [Nextcloud mobile client](https://nextcloud.com/clients/) for your smartphone, connect it to your OpenAppStack instance, and use it to download and/or open some files, upload a new file, etc.
 
 
-## ONLYOFFICE
+## Onlyoffice
 
 ### Creating a new office document
 
@@ -59,17 +53,30 @@ From the main Nextcloud webpage, please try to create a new office document, by
 This part of the test requires the cooperation of another person; feel free to skip it now if that's not convenient at this point.
 
 * First, try to share your document with a different user.
-* Then, try to open the shared document from a few different user accounts simultaneously, and let all participants edit the document mercilessly. There are also some collaboration features that you may want to try: on the left of the OnlyOffice screen there are buttons for chat and for text comments.
+* Then, try to open the shared document from a few different user accounts simultaneously, and let all participants edit the document mercilessly.
+  There are also some collaboration features that you may want to try: on the left of the Onlyoffice screen there are buttons for chat and for text comments.
+
+
+## Rocketchat
+
+You can find Rocketchat at https://chat.oas.example.org.
+Once you configured Rocketchat for single sign-on as desribed in the Usage docs
+please login using single sign-on as `admin` and afterwards as the user you
+created.
+
+
+## Wordpress
 
-## Rocket.Chat
+You can find Wordpress at https://www.oas.example.org.
+Please try to login as the new user you created earlier by pressing "Log in" and
+using the `Login with OpenID Connect` button.
 
-You can find Rocket.Chat at https://chat.oas.example.org. Please go there and
-try to log in.
+At the moment Administrator privileges will not be available for single sign-on
+users of WordPress. You can sign in with the automatically created administrator
+account. The username is `admin` and the password can be found in the
+`wordpress_admin_password` file in the `secrets` folder of your provisioning
+machine's config directory.
 
-Note that at the moment we have not integrated Rocket.Chat with the single
-sign-on system yet. You can only sign in with the automatically created
-administrator account. The username is `admin` and the password can be found in
-`clusters/my-cluster/secrets/rocketchat_admin_password`
 
 ## Providing feedback
 
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000000000000000000000000000000000000..8b936efb23e5829393cf4c05848bfe6df87ee505
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,150 @@
+# Usage
+
+After all the applications are installed, the first thing to do is log into
+https://admin.oas.example.org. Here you can find the "user panel", a place where
+you can create, edit and delete users. You can log in with the user "admin". The
+password can be found in
+`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
+will see an overview of all the applications your user has access to. For more
+information on how to create users and give them access to applications, take a
+look at the [user panel
+documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
+
+> **NOTE:** at the moment none of the applications are available at
+> `oas.example.org`, we only provide applications in subdomains. In the future
+> this might change.
+
+## Applications
+
+These applications are available after the installation is completed
+successfully:
+
+
+### OAS User panel
+
+The [OAS user panel](https://open.greenhost.net/openappstack/user-panel/)
+can be used to create and edit users. These users can be used to log into the
+applications listed below.
+The user panel is available at https://admin.oas.example.org. You can login
+as `admin` using the `userbackend_admin_password` password from your secrets
+folder.
+
+After logging in to the user panel follow the [user panel documentation](https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user)
+to create a new user.
+
+*Note*: The email address is important because some applications need a valid
+email address for notification mails.
+Single sign-on with Grafana will fail for users lacking an email address.
+
+You can now use the new user to log in to all apps which were granted access to
+in the last step using single sign-on.
+
+
+### Nextcloud
+
+[Nextcloud](https://nextcloud.com/) is a file sharing and communication
+platform and is available at https://files.oas.example.org.
+
+#### Single sign-on
+
+Nextcloud needs to be configured to properly send out emails.
+You can do so by logging in as `admin` using signle sign-on and then going to
+`Settings -> Basic settings -> Email server` and entering your SMTP email
+config and credentials.
+Please complete this configuration before you login as non-admin user using
+single sign-on, otherwise the [first login will not succeed](https://open.greenhost.net/openappstack/openappstack/issues/508).
+
+
+### Onlyoffice
+
+[Onlyoffice](https://www.onlyoffice.com/connectors-nextcloud.aspx) is an online
+document editing suite. Your can open documents in Onlyoffice by clicking them in Nextcloud. You can open new documents by clicking the "Plus" button in Nextcloud and selecting Document, Spreadsheet or Presentation.
+
+
+### Rocketchat
+
+[Rocketchat](https://rocket.chat/) is a team chat application and available at
+https://chat.oas.example.org.
+
+#### Single sign-on
+
+Until we [fully automate SSO integration for Rocketchat](https://open.greenhost.net/openappstack/openappstack/issues/516)
+manual intervention is neccessary to activate it. You need to follow these steps once:
+
+- Log in as `admin` using the `rocketchat_admin_password` from your secrets
+  folder.
+- On the top left side click on the `Options` button (three dots) and then click
+  on `Administration`
+- In the left menu scroll down and click on `OAuth` (not `oauth apps`)
+- Click on `add custom oauth` and enter `Openappstack`
+- Click on the newly added `Custom OAuth: Openappstack` provider
+- Change the following settings (leave all others like they are):
+  - Enable: `True`
+  - URL: `https://sso.oas.example.org` (change `oas.example.org` to your domain)
+  - Token Path: `/oauth2/token`
+  - Identity Path: `/userinfo`
+  - Authorize Path: `/oauth2/auth`
+  - Scope: `openid profile openappstack_roles email`
+  - Id: `rocketchat`
+  - Secret: Paste the `rocketchat_oauth_client_secret` from your secrets folder
+  - Login Style: `Redirect`
+  - Button Text: `Login with OpenAppStack`
+  - Username field: `preferred_username`
+  - Name files: `name`
+  - Roles/Groups field name: `openappstack_roles`
+  - Merge roles from SSO: `True`
+  - Merge users: `True`
+- Click `Save changes`, log out and you are done.
+
+Next time you log in to Rocketchat you will be able to use single sign-on using
+the `Login` button.
+
+### Known issues
+
+- [Rocketchat isn't configured yet to send out email notifications](https://open.greenhost.net/openappstack/openappstack/issues/510)
+
+
+### Wordpress
+
+[Wordpress](https://wordpress.com) is a website content management system and
+available at https://www.oas.example.org.
+Click the `Log in` button and then click `Login with OpenID Connect` to use
+single sign-on.
+
+#### Single sign-on
+
+- If you [log in as `admin` using single sign-on, you will not have
+admin rights within Wordpress](https://open.greenhost.net/openappstack/single-sign-on/issues/33).
+In order to use admin rights you need to log in without single sign-on using the
+`wordpress_admin_password` password in the `secrets` folder.
+
+
+### Grafana
+
+[Grafana](https://grafana.com) that shows you information about the status of
+your cluster.
+Read more about Grafana in the [monitoring chapter below](#monitoring)
+
+#### Single sign-on
+
+- If you [log in as `admin` using single sign-on, you will not have
+admin rights within Grafana](https://open.greenhost.net/openappstack/single-sign-on/issues/32).
+In order to use admin rights you need to log in without signgle sign-on using the
+`grafana_admin_password` password in the `secrets` folder.
+
+
+### Other applications installed into the cluster
+
+Besides these applications, some other components are installed.
+These are part of the OpenAppStack back end and they dont't have a user facing
+web interfaces, but we like to list them here for reference:
+
+* [OAS local-storage](https://open.greenhost.net/openappstack/local-storage) provides an easy way for the cluster to use a directory on
+  the node (by default `/var/lib/OpenAppStack/local-storage`) for storage;
+* [NGINX](https://www.nginx.com) is a webserver that functions as a so-called ingress controller,
+  routing web traffic that enters the cluster to the various applications;
+* [cert-manager](https://cert-manager.io) acquires and stores [Let's
+  Encrypt](https://letsencrypt.org/) certificates, enabling encrypted web
+  traffic to all applications running in the cluster;
+* [Flux](https://fluxcd.io) checks for application updates approved by the
+  OpenAppStack team and installs them automatically.