Rework doc about oidc-agent usage

Closes #81 (closed)

docs/helmholtz-aai/howto-users.md

@@ -80,10 +80,8 @@ A growing number of Linux distributions have `oidc-agent` already in their repos
 
 `oidc-agent` comes with a number of pre-configured public client configurations. There is also a public client for the Helmholtz AAI which makes configuration easy.
 
--   In order to start the configuration process:
-`oidc-gen --pub <shortname>`
-
--   Enter `https://login.helmholtz.de/oauth2/` as issuer.
+-   In order to start the configuration process: `oidc-gen --pub <shortname>`
+-   Enter `https://login.helmholtz.de/oauth2/` as issuer or select the corresponding number from the presented list.
 -   Select the scopes you want to access or accept the preconfigured list.
 -   Enter the desired redirection URLs (you have to add at least one - if you only plan to use the CLI agent, this doesn't really matter, so you can use e.g. `http://localhost:8080`)
 -   Important: Login with your home IdP in the browser window which opens. This step is necessary to complete the account configuration.
@@ -91,6 +89,10 @@ A growing number of Linux distributions have `oidc-agent` already in their repos
 - start `oidc-agent` and set the necessary environment variables with ``eval `oidc-agent` ``
 - check if your configuration works with `oidc-token <short name of your configuration>`
 
+!!!warning "Nota bene"
+    - If you are configuring the `oidc-agent` on a computer without an XSession (e.g. on a machine where you are logged in with pure `ssh`, you will need to use the command `oidc-gen --pub --no-url-call --no-webserver <shortname>`. The agent will then print out a URL you can copy into a browser of your choice, log in as usual and you will get a message "Page not found". Copy the URL in the URL-bar of the browser and follow the instructions given by `oidc-agent` in your `ssh`-session before.
+    - If you are logged into a machine via `ssh` and the `$DISPLAY` environment variable is not set, `oidc-agent` will assume that you are on a "dumb" device and invoke an authorization flow that is deactivated in the Helmholtz AAI. Your configuration attempt will fail unless you set `export DISPLAY=0:` assuming you are on a Linux machine.
+
 #### Accessing user information
 
 After configuring `oidc-agent` and logging in you can now start using it. You can, for example, request your users information with `curl`:
@@ -108,33 +110,30 @@ This should give you something like:
                                  Dload  Upload   Total   Spent    Left  Speed
 100  1227  100  1227    0     0   7967      0 --:--:-- --:--:-- --:--:--  7967
 {
-  "sub": "576a03d3-39a0-4f3a-b32a-f7b3bd29111c",
+  "sub": "06b05656-ad50-11ed-ac2b-3f78a68a37a7",
   "email_verified": true,
   "groups": [
-    "/DESY",
     "/Helmholtz-member",
     "/HDF",
     "/"
   ],
-  "preferred_username": "carsten.heidmann",
-  "display_name": "Carsten Heidmann",
-  "given_name": "Carsten",
-  "eduperson_principal_name": "cheidman@desy.de",
+  "preferred_username": "sam.scientist",
+  "display_name": "Sam Scientist",
+  "given_name": "Sam",
+  "eduperson_principal_name": "sam.scientist@helmholtz.de",
   "eduperson_entitlement": [
     "urn:geant:h-df.de:group:HDF#login.helmholtz.de",
-    "urn:geant:h-df.de:group:DESY#login.helmholtz.de",
     "urn:geant:h-df.de:group:Helmholtz-member#login.helmholtz.de"
   ],
-  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAyqvhXPY0ETi7c954y3vV+c6bWdIihvrWokmv3GrndaFMyX2cKpzZofKXKdnK7Nv6TFJASCKeLqAyON0CGlE3ZgRw44bnJD5lWNN9uKInZ+EMKKyO4XqgTYoEIsGNTElyHjRw2hvArlQpP89ULnPWsVemdJza+8TTEMtTSVN/fX9ofOk63GJcuOpkH+x7CIWjc7QW5KmLc0Jc2+Xzu4IBmRKRXk9uaI/e7sFXPPLa+PHMtywxmVFhDANyElBSAeRmjo5RHJ1Azd08obMJMJCrfEKoZgLlfz5OpUiF6Ntqu00dSeIVvcyNEgXgfXPX55G5jTEwp7B1H7nakdUVH6e46Q== Carsten Heidmann (RSA)\n",
-  "name": "Carsten Heidmann",
-  "eduperson_unique_id": "576a03d339a04f3ab32af7b3bd29111c@login.helmholtz.de",
-  "sn": "Heidmann",
+  "name": "Sam Scientist",
+  "eduperson_unique_id": "06b05656ad5011edac2b3f78a68a37a7@login.helmholtz.de",
+  "sn": "Scientist",
   "eduperson_assurance": [
     "https://refeds.org/assurance/ATP/ePA-1m",
     "https://refeds.org/assurance/ID/unique",
     "https://refeds.org/assurance/IAP/low"
   ],
-  "family_name": "Heidmann",
-  "email": "carsten.heidmann@desy.de"
+  "family_name": "Scientist",
+  "email": "sam.scientist@helmholtz.de"
 }
 ```