Initial QSfera import

Server/services/auth-app/README.md

@@ -0,0 +1,139 @@
+# Auth-App
+
+The auth-app service provides authentication for 3rd party apps unable to use
+OpenID Connect. The service is enabled by default and started automatically. It
+is possible to disable the service by setting:
+
+```bash
+OC_EXCLUDE_RUN_SERVICES=auth-app # deployment specific. Removes service from the list of automatically started services, use with single-binary deployments
+PROXY_ENABLE_APP_AUTH=false      # mandatory, disables app authentication. In case of a distributed environment, this envvar needs to be set in the proxy service.
+```
+
+## App Tokens
+
+App Tokens are password specifically generated to be used by 3rd party applications
+for authentication when accessing the КуСфера API endpoints. To
+be able to use an app token, one must first create a token. There are different
+options of creating a token.
+
+## Important Security Note
+
+When using an external IDP for authentication, App Token are NOT invalidated
+when the user is disabled or locked in that external IDP. That means the user
+will still be able to use its existing App Tokens for authentication for as
+long as the App Tokes are valid.
+
+## Managing App Tokens
+
+### Via API
+
+Please note: This API is preliminary. In the future we will provide endpoints
+in the `graph` service for allowing the management of App Tokens.
+
+The `auth-app` service provides an API to create (POST), list (GET) and delete (DELETE) tokens at the `/auth-app/tokens` endpoint.
+
+* **Create a token**\
+  The POST request requires:
+  * A `expiry` key/value pair in the form of `expiry=<number><h|m|s>`\
+    Example: `expiry=72h`
+  ```bash
+  curl --request POST 'https://<your host:9200>/auth-app/tokens?expiry={value}' \
+       --header 'accept: application/json'
+  ```
+  Example output:
+  ```
+  {
+  "token": "3s2K7816M4vuSpd5",
+  "expiration_date": "2024-08-08T13:42:42.796888022+02:00",
+  "created_date": "2024-08-07T13:42:42+02:00",
+  "label": "Generated via API"
+  }
+  ```
+
+  Note, that this is the only time the app token will be returned in cleartext. To use the token
+  please copy it from the response.
+
+* **List tokens**\
+  ```bash
+  curl --request GET 'https://<your host:9200>/auth-app/tokens' \
+       --header 'accept: application/json'
+  ```
+
+  Note that the `token` value in the response to the "List Tokens` request is not the actual
+  app token, but the UUID of the token. So this value cannot be used for authenticating
+  with the token.
+
+  Example output:
+  ```
+  [
+    {
+      "token": "155f402e-1c5c-411c-92d4-92f3b612cd99"
+      "expiration_date": "2024-08-08T13:44:31.025199075+02:00",
+      "created_date": "2024-08-07T13:44:31+02:00",
+      "label": "Generated via Impersonation API"
+    },
+    {
+      "token": "8c606bdb-e22e-4094-9304-732fd4702bc9"
+      "expiration_date": "2024-08-08T13:46:41.936052281+02:00",
+      "created_date": "2024-08-07T13:46:42+02:00",
+      "label": "Generated via Impersonation API"
+    }
+  ]
+  ```
+
+* **Delete a token**\
+  The DELETE request requires:
+  * A `token` key/value pair in the form of `token=<token_issued>`. The value needs to be the hashed value as returned by the `List Tokens` respone.\
+    Example: `token=8c606bdb-e22e-4094-9304-732fd4702bc9`
+  ```bash
+  curl --request DELETE 'https://<your host:9200>/auth-app/tokens?token={value}' \
+       --header 'accept: application/json'
+  ```
+
+### Via Impersonation API
+
+When setting the environment variable `AUTH_APP_ENABLE_IMPERSONATION` to
+`true`, admins will be able to use the `/auth-app/tokens` endpoint to create
+tokens for other users. This can be important for migration scenarios, but
+should not be considered for regular tasks on a production system for security
+reasons.
+
+To impersonate, the respective requests from the CLI commands above extend with
+the following parameters, where you can use one or the other:
+
+* The `userID` in the form of: `userID={value}`\
+  Example:\
+  `userID=4c510ada- ... -42cdf82c3d51`
+
+* The `userName` in the form of: `userName={value}`\
+  Example:\
+  `userName=alan`
+
+Example:\
+A final create request would then look like:
+```bash
+curl --request POST 'https://<your host:9200>/auth-app/tokens?expiry={value}&userName={value}' \
+     --header 'accept: application/json'
+```
+
+### Via CLI (developer only)
+
+As the CLI is using the internal CS3Apis this needs access to the reva gateway
+service. This is mainly of developer (and admin) usage.
+Replace the `user-name` with an existing user. For the `token-expiration`, you
+can use any time abbreviation from the following list: `h, m, s`. Examples:
+`72h` or `1h` or `1m` or `1s.` Default is `72h`.
+
+```bash
+qsfera auth-app create --user-name={user-name} --expiration={token-expiration}
+```
+
+## Authenticating using App Tokens
+
+To autenticate using an App Token simply use the username for which token was generated
+and the token value as returned by the "Create Token" request.
+
+```bash
+curl -u <username>:<tokenvalue> 'https://<your host>/graph/v1.0/me' \
+     --header 'accept: application/json'
+```