docs: add details on how to configure SMTP settings (#4146)

docs/admin/developer/agama/flows-lifecycle.md

@@ -42,7 +42,7 @@ This is a feature that in conjuction with [template overrides](./dsl-full.md#tem
 
 Clearly a page at flow A can be overriden, however, how to abort A and make it jump to B? The answer is cancellation. Through flow cancellation, a running flow can be aborted and the control returned to one of its parents for further processing. This can achieved by overriding a template so that the POST to the current URL includes a form field named `_abort`.
 
-POSTing this way will provoke the associated `Trigger` call to return a value like `{ aborted: true, data: ... }` where `data` is a _map_ consisting of the payload (form fields) sent with the POST. Thus, developers can build custom pages and add for example a button to provoke the cancellation. Then, back in the flow implementation take the user to the desired path.
+POSTing this way will provoke the associated `Trigger` call to return a value like `{ aborted: true, data: ..., url: ... }` where `data` is a _map_ consisting of the payload (form fields) sent with the POST. Thus, developers can build custom pages and add for example a button to provoke the cancellation. Then, back in the flow implementation take the user to the desired path. The `url` property will hold the URL where cancellation took place relative to `https://your-server/jans-auth/fl/`.
 
 As an example, suppose there exists two flows that allow users to enter and validate a one-time passcode (OTP), one flow sends the OTP via e-mail while the other through an SMS. Assume these flows receive a user identifier as input and render a single UI page each to enter the received OTP. If we are interested in building a flow that prompts for username/password credentials and use the SMS-based OTP flow with a customization that consists of showing a link like "Didn't get an SMS?, send the passcode to my e-mail", the following is a sketch of an implementation:
 

docs/admin/developer/agama/samples.md

@@ -52,7 +52,7 @@ Source code [here](https://github.com/JanssenProject/jans/raw/main/docs/admin/de
 
 ## Email OTP authentication
 
-This is a two-stepped flow where the end-user initially is prompted to enter a username and corresponding password. Upon successful validation and assuming the user has an e-mail designated in his profile, a message with a one-time passcode (OTP) is sent to his inbox. The user is expected to enter the code in the browser to complete the authentication.
+This is a two-stepped flow where the end-user initially is prompted to enter a username and corresponding password. Upon successful validation and assuming the user has an e-mail designated in his profile, a message with a one-time passcode (OTP) is sent to his inbox. The user is expected to enter the code in the browser to complete the authentication. Note your server is required to have [SMTP settings](#smtp-configurations) set. 
 
 ### Implementation
 
@@ -77,7 +77,7 @@ Source code [here](https://github.com/JanssenProject/jans/raw/main/docs/admin/de
 
 - Lines 16-18. Initializes utility variables and declares that the block of indented statements (lines 20-35) will be executed repeatedly three times at most
 
-- Lines 20-22. Sends a message with a passcode to the e-mail of the user (stored in variable `email`) by calling method `send` of class `EmailOTPUtil`. If delivery was successful this method returns the passcode sent, otherwise `null`. The value is store in `otpCode` variable
+- Lines 20-22. Sends a message with a passcode to the e-mail of the user (stored in variable `email`) by calling method `send` of class `EmailOTPUtil`. If delivery was successful this method returns the passcode sent, otherwise `null`. The value is stored in `otpCode` variable. For this code to work properly you have to configure the **SMTP settings** in your server as explaind [below](#smtp-configurations)
 
 - Lines 24-26. If delivery failed, the flow is finished
 
@@ -101,6 +101,34 @@ Source code [here](https://github.com/JanssenProject/jans/raw/main/docs/admin/de
 
 If the user presses the enter key when the focus is on the text field, the form is submitted by means of the standard submission button.
 
+### SMTP configurations
+
+To supply details of the mail server to employ for message delivery, create a json file like the below with your specific details:
+
+```
+{
+  "valid": true,
+  "host": "outgoing-smtp-server.acme.co",
+  "port": 587,
+  "requires_ssl": true,
+  "trust_host": true,
+  "from_name": "Acme nofications",
+  "from_email_address": "no-reply@acme.co",
+  "requires_authentication": true,
+  "user_name": "admin@acme.co",
+  "password": "secret"
+}
+```
+
+Then log into your server, transfer the file to some location, `cd` to it, and run:
+
+```
+python3 /opt/jans/jans-cli/config-cli.py --operation-id=post-config-smtp --data path/to/your/file.json
+```
+
+If you had previously set a configuration, you may have to pass `put-config-smtp` instead for `operation-id`.
+
+
 ## Combined registration and authentication flow
 
 In this flow features like [template overrides](./dsl-full.md#template-overrides) and [flow cancellation](./flows-lifecycle.md#cancellation) are leveraged to bring a more sophisticated authentication journey. A description follows: