update docs

docs/30_Installation.md

@@ -33,6 +33,8 @@ return [
     "appid" => "c1cabd22fbdb698861ad08b27de7399a",
     "shared_secret" => "p9wjjXSewZq0VkM1t5Sm3ZbI4ATEVetU",
 
+    // "user"=> $_SERVER['REMOTE_USER']??'',
+
     "debug" => false,
 
 ];
@@ -61,65 +63,20 @@ A good place is the user profile page in your app.
 
 ```php
 <?php
-...
 // load class
 require "<APPROOT>/vendor/mfa-client/mfaclient.class.php";
 
 // initialize client
 $oMfa = new mfaclient();
-// $oMfa->debug(true);
 
-// set the user
-$oMfa->setUser($this->getUserid());
+// $oMfa->debug(true);
+// $oMfa->setUser($this->getUserid());
 
 // show a button; set a complete url where to jump back
 echo $oMfa->getButtonSetup(
   "<button>MFA settings</button>",
   "https://myapp.example.com/profile"
 );
-...
 ```
 
 This renders an html form with hidden fields to transmit app id, user id and a HMAC code to the MFA server. This form is valid for 1 minute.
-
-### Troubleshooting
-
-There is a debug mode.
-It prints detailed information about the connection to the mfa server and actions on the client.
-
-!!! danger "Security warning"
-    Do not acrivate it globally and/ or for all users on a productive web app!
-
-#### Globally enabled debugging
-
-In the "mfaconfig.php" you can enable a flag "debug":
-
-```php
-<?php
-
-return [
-
-    "api" => ...
-    "appid" => ...
-    "shared_secret" => ...
-
-    "debug" => true,
-
-];
-```
-
-#### Enable by debug method
-
-Inside php code you can use the method `debug(<bool>)` to enable and disable the debugging. 
-
-```php
-<?php
-require "<APPROOT>/vendor/mfa-client/mfaclient.class.php";
-$oMfa = new mfaclient();
-
-// enable debugging
-$oMfa->debug(true);
-```
-
-In real life applications you add additional conditions, like a user restriction plus a $_GET variable to limit the debug code to you only.
-

docs/40_Usage/10_First_access_on_mfa_server.md

@@ -15,44 +15,9 @@ We make a 1st request and are logged in. The MFA client gets the answer from MFA
 
 The MFA client will redirect the user to the MFA server.
 
-### Overview page
+There the user must setup one of the available methods.
 
-Any user of a registered app will be accepted by the mfa server and let's him configure mfa methods.
+To get an impression of the 1st visit of a user at the MFA server see the docs of the MFA server: \
+📗 <https://os-docs.iml.unibe.ch/mfa-server/Installation/First_user_visit.html>
 
-The setup page shows
-
-* The application with a link to jump back
-* The username in the web application
-* The ip address of the user when accessing the app
-
-![alt text](screenshot__first_visit__01.png)
-
-If a new user vistes the mfa server then it has no mfa configuration yet. The user needs to setup minimum one of the given methods.
-
-Click on one of the buttons to setup TOTP or email.
-
-### Setup TOTP
-
-When setting up TOTP the system generates a secret.
-You see the secret as text and as qr code.
-
-![alt text](screenshot__first_visit__02.png)
-
-Configure your TOTP client to add a new app.
-
-If it is done then enter the current key to finish the setup.
-The browser jumps back to the web application.
-
-### Setup email
-
-To setup an email you enter your own email address.
-
-![alt text](screenshot__first_visit__03.png)
-
-The ystem sends a verification code to the entered address and waits for the correct code.
-
-The sent email has a subject with a timestamp including minutes and seconds to identify the email in the inbox.
-
-![alt text](screenshot__first_visit__04.png)
-
-If the entered code is correct the email address will be stored for email mfa. The browser jumps back to the web application.
+If an error occurs that does not allow to access the MFA server you get an html page with the error message (fromn reponse of then api request).

docs/40_Usage/20_Following_logons.md

@@ -4,8 +4,5 @@ After a user has added a mfa method and loggs in into the web application... the
 
 The MFA client will redirect to the MFA server and offers the 1st found mfa method from the list.
 
-![alt text](screenshot__solve_totp.png)
-
-On the right hand you can switch to other configured mfa methods:
-
-![alt text](screenshot__solve_email.png)
+Follow the docs of the MFA server: \
+📗 <https://os-docs.iml.unibe.ch/mfa-server/Usage/User_view/Solve_challenge.html>

docs/40_Usage/30_Setup_mfa.md

@@ -4,40 +4,11 @@ After Solving a challenge after login the user is redirected to the application.
 
 Don't forget to offer a setup link to the MFA server.
 
-### Overview
-
 The overview page is nearly the same like on the very first visit.
 
-![alt text](screenshot__setup_overview.png)
-
-On top left the button to jump back to the application is green because a challenge was solved already. Now are all links are enabled.
-
-* My sessions - show stored sessions of the last 4 weeks
-* Methods TOTP and email can be viewed and deleted to reconfigure this method
-* A challenge can be tested.
-
-### My sessions
-
-![alt text](screenshot__setup_my_sessions.png)
-
-### View TOTP
-
-!!! warning "Important!"
-    Save your TOTP backup codes!
-
-You can see the stored secret for the totp challenge and the backup codes. Used backup codes are marked with an icon and date of its usage.
-
-**Options**:
-
-* You should save your backup codes locally on your computer. They allow you to login when you have no access to your TOTP app.
-* You can delete the stored totp secret. Afterwards you can setup a new totp secret for your application
-
-![alt text](screenshot__setup_view_totp.png)
-
-### View Email
-
-**Options**:
+But after login the mfa methods can be viewed/ deleted.
 
-* You can delete the stored email. Afterwards you can setup a email
+A user can see his sessions.
 
-![alt text](screenshot__setup_view_email.png)
+Follow the docs of the MFA server: \
+📗 <https://os-docs.iml.unibe.ch/mfa-server/Usage/User_view/Startpage.html>

docs/40_Usage/60_Troubleshooting.md

+## Troubleshooting
+
+### Timeout
+
+If you offer a setup link and you get an error message
+
+```txt
+403 Forbidden
+Token is too old. Send a new request.
+```
+
+The generated button is a form with hidden fields. Clicking on the button sends a POST request to the MFA server. This form is valid for 60 sec. If a user is spending more time on the page and then clicks the MFA setup button he will get that error.
+
+**Solution**:
+
+* Go back and reload the page to generate a new button. That one can be clicked.
+* If it still does not work the clock on your application server or mfa server could be out of sync.
+
+### Debugging
+
+There is a debug mode if you want to dive deeper when a behaviour is not like expected.
+It prints detailed information about the connection to the mfa server and actions on the client.
+
+!!! danger "Security warning"
+    Do not acrivate it globally and/ or for all users on a productive web app!
+
+#### Globally enabled
+
+In the "mfaconfig.php" you can enable a flag "debug":
+
+```php
+<?php
+
+return [
+
+    "api" => ...
+    "appid" => ...
+    "shared_secret" => ...
+
+    "debug" => true,
+
+];
+```
+
+#### Enable by debug method
+
+Inside php code you can use the method `debug(<bool>)` to enable and disable the debugging. 
+
+```php
+<?php
+require "<APPROOT>/vendor/mfa-client/mfaclient.class.php";
+$oMfa = new mfaclient();
+
+// enable debugging
+$oMfa->debug(true);
+```
+
+In real life applications you add additional conditions, like a user restriction plus a $_GET variable to limit the debug code to you only.
+

docs/50_Technical_details/10_Processes.md

+## Processes
+
+### API
+
+The API request is a Http POST request.
+
+A check request detects if
+
+* the given application id exists
+* the token is ok
+  * correct value
+  * timestamp is wihin 60 sec
+  * used only once
+* a user
+  * needs to setup (first visit at MFA server)
+  * has a valid mfa challenge within the ttl (12 h)
+  * has an outdated mfa challenge
+
+#### Request
+
+The API request is an Http POST request.
+
+🌐 Target **url**: url in key `'api'` in your config file (given by mfa server)
+
+📄 Data **fields**
+
+| Name       | Description
+|---         |---
+| action     | action to perform; one of "check"\|"urls"
+| username   | user id of logged in user
+| appid      | application id from config (given by mfa server)
+| ip         | ip address of the user request to the web application
+| request    | url path and query string of traget url on mfa server
+| timestamp  | timestamp (with milliseconds)
+| token      | generated HAMC token using the fields "request" + "timestamp" plus "POST" - encrypted with the application secret (given by the mfa server)
+| useragent  | user agent of the user visiting the web aplication
+
+#### Response
+
+The response is JSON.
+
+The basic fields are:
+
+| Name       | Description
+|---         |---
+| status     | http status code
+| error      | on error: a clear text message (en)
+| message    | message text
+
+Posiible Keys of "check" response:
+
+| Name       | Description
+|---         |---
+| url        | depending on status: url to jump in into mfa server (eg user needs to setup first or can solve a challenge). This field does not exist if the check failed and a user action is not possible.
+
+Posiible Keys of "urls" response:
+
+| Name       | Description
+|---         |---
+| setup      | url to open users mfa setup page
+| verify     | url to solve a challenge
+
+### Jump to MFA server
+
+To jump in into the setup page or to solve a token an Http POST request is needed.
+
+🌐 The target url is taken from the response of a "check" or "urls" request.
+
+📄 The fields are mostly similiar to the api request.
+
+| Name       | Description
+|---         |---
+| username   | user id of logged in user
+| appid      | application id from config (given by mfa server)
+| ip         | ip address of the user request to the web application
+| request    | url path and query string of traget url on mfa server
+| timestamp  | timestamp (with milliseconds)
+| token      | generated HAMC token using the fields "request" + "timestamp" plus "POST" - encrypted with the application secret (given by the mfa server)
+| backurl    | url for mfa server where to jump back to the application

docs/50_Technical_details/mfaclient.class.php.md

+## 📦 Class \mfaclient
+
+```txt
+
+```
+
+## 🔶 Properties
+
+(none)
+
+## 🔷 Methods
+
+### 🔹 public __construct()
+
+Intialize mfa client - optional set config and user@see setConfig@see setUser
+
+**Return**: ``
+
+**Parameters**: **2**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<optional\> $aConfig | `array` | optional: configuration with app id and base url
+| \<optional\> $sUser | `string` | optional: user id that was logged in
+
+### 🔹 public check()
+
+Check MFA server api about user status
+
+**Return**: `array`
+
+**Parameters**: **0**
+
+
+### 🔹 public debug()
+
+Enable or disable debugging
+
+**Return**: `void`
+
+**Parameters**: **1**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<required\> $bDebug | `bool` | flag: new value for debugging; true = debug enabled
+
+### 🔹 public ensure()
+
+Check if MFA login is needed and jump to its url
+
+**Return**: `int`
+
+**Parameters**: **0**
+
+
+### 🔹 public getButtonSetup()
+
+Get an html button to open mfa setup page
+
+**Return**: `string`
+
+**Parameters**: **2**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<optional\> $sSubmitBtn | `string` | html code for a submit button
+| \<optional\> $sBackUrl | `url *` | url to return from mfa server to the application
+
+### 🔹 public getClientIp()
+
+Get IP of current client (to be sent to MFA server)
+
+**Return**: `string`
+
+**Parameters**: **0**
+
+
+### 🔹 public getUrls()
+
+get list of urls from MFA server
+
+**Return**: `array`
+
+**Parameters**: **0**
+
+
+### 🔹 public jumpform()
+
+Generate html code for jump form.With it a user can jump from current app to mfa server to setup mfa methods or solve a challenge
+
+**Return**: `string`
+
+**Parameters**: **4**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<required\> $sUrl | `string` | url to jump (mfa server setup page or page to solve challenge)
+| \<optional\> $sSubmit | `string` | html code for a submit button
+| \<optional\> $sBackUrl | `string` | url to return from mfa server to the application
+| \<optional\> $sFormId | `string` | form id
+
+### 🔹 public loadConfig()
+
+Load configuration file from current directory
+
+**Return**: `void`
+
+**Parameters**: **0**
+
+
+### 🔹 public logout()
+
+Logout; unset user in session scope
+
+
+**Return**: `void *`
+
+**Parameters**: **0**
+
+
+### 🔹 public setConfig()
+
+Apply a given config with app id and base url
+
+**Return**: `void`
+
+**Parameters**: **1**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<required\> $aConfig | `array` | configuration with app id and base url
+
+### 🔹 public setUser()
+
+Set a user id that is logged in
+
+**Return**: `void *`
+
+**Parameters**: **1**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<required\> $sUser | `string` | user id of current user
+
+### 🔹 public showHtml()
+
+Show html message and abort to prevent visibility of the app without solved mfa
+
+**Return**: `never *`
+
+**Parameters**: **2**
+
+| Parameter | Type | Description
+|--         |--    |--
+| \<required\> $iHttpStatus | `int` | http statuscode to set
+| \<required\> $sHtmlcode | `string` | http body to show
+
+---
+Generated with Axels PHP class doc parser.
\ No newline at end of file

docs/_index.md

@@ -8,7 +8,7 @@
 👤 Author: Axel Hahn; Institute for Medical Education; University of Bern \
 📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/mfa-client> \
 📜 License: GNU GPL 3.0 \
-📗 Docs: <https://os-docs.iml.unibe.ch/mfa-client/> (TODO)
+📗 Docs: <https://os-docs.iml.unibe.ch/mfa-client/>
 
 
 **Related projects**: