feat(agama): add utility classes for inbound identity (#2417)

* docs: udpate docs #2197

* chore: remove smells #2197

* chore: shorten inbound identity flow code #2197

agama/inboundID/src/main/java/io/jans/inbound/JwtUtil.java

@@ -69,4 +69,6 @@ public static Map<String, Object> partialVerifyJWT(String jwt, String iss, Strin
 
     }
 
+    private JwtUtil() { }
+
 }

agama/inboundID/src/main/java/io/jans/inbound/oauth2/CodeGrantUtil.java

@@ -99,8 +99,6 @@ public Map<String, Object> getTokenResponse(String authzCode)
 
         HTTPRequest httpRequest = request.toHTTPRequest();
         httpRequest.setAccept(MediaType.APPLICATION_JSON);
-        //httpRequest.setContentType("application/x-www-form-urlencoded");
-        //httpRequest.setHeader("User-Agent", "curl");
 
         TokenResponse response = TokenResponse.parse(httpRequest.send());
         if (!response.indicatesSuccess()) {

docs/admin/developer/agama/faq.md

@@ -22,6 +22,17 @@ A java invocation is attempting to call a method that is not part of the given c
 
 This occurs when no `Finish` statement has been found in the execution of a flow and there are no remaining instructions.
 
+### Serialization errors
+
+Agama engine saves the state of a flow (see *continuations* [here](./hello-world-closer.md)) every time an [RRF](./dsl.md#rrf) or [RFAC](./dsl-full.md#rfac) instruction is reached. For this purpose the [KRYO](https://github.com/EsotericSoftware/kryo) library is employed. If kryo is unable to serialize a variable in use by your flow, a serialization error will appear in the screen or in the logs. Normally the problematic (Java) class is logged and this helps reveal the variable that is causing the issue. Note variables that hold "native" Agama values like strings or maps are never troublesome; the problems may originate from values obtained via [Call](./dsl-full.md#java-interaction).
+
+To fix a serialization problem, try some of the following:
+
+- Check if the value held by the variable is needed for RRF/RFAC or some upcoming statement. If that's not the case, simply set it to `null` before RRF/RFAC occurs
+- Adjust the given class so it is "serialization" friendlier. With kryo, classes are not required to implement the `java.io.Serializable` interface 
+- Find a replacement for the problematic class
+- As a last resort, set `serializerType` property of the [engine](./engine-config.md) to `null`. Note this will switch to standard Java serialization. This setting applies globally for all your flows
+
 ## Classes added on the fly
 
 ### A class does not "see" other classes in its own package

docs/admin/developer/agama/lifecycle.md

@@ -11,7 +11,7 @@ In this page an overview of the flow development process is presented. In short,
 As usual, several iterations will take place until you get it right.
 
 !!! Note
-    Throughout this document it is assumed you have a working single VM standard Janssen installation
+    Throughout this document it is assumed you have a standard single-VM Janssen installation
 
 ## Design and code
 

docs/admin/developer/agama/otp-email/io.jans.flow.sample.otp.email

@@ -1,10 +1,10 @@
 Flow io.jans.flow.sample.otp.email
     Basepath "samples/otp-email"
-    
+
 //Launch usr/pwd authentication
 obj = Trigger io.jans.flow.sample.basic
 When obj.success is false
-    Finish obj 
+    Finish obj
 
 userId = obj.data.userId
 email = Call io.jans.agama.samples.EmailOTPUtil#emailOf userId

docs/script-catalog/agama/inboundID/io.jans.inbound.ExternalSiteLogin

@@ -10,12 +10,12 @@ When providerId is null
 
     When providerId is null
         //Launch basic authn 
-        obj = Trigger io.jans.flow.sample.basic    
+        obj = Trigger io.jans.flow.sample.basic
         Log "Basic authentication finished with success:" obj.success
         Finish obj
 
 provider = providers.$providerId
-//See class io.jans.inbound.oauth2 for reference
+//See class io.jans.inbound.Provider for reference
 
 When provider is null or provider.enabled is false
     msg = Call java.lang.String#format "Provider '%s' not recognized. Is it enabled?" providerId
@@ -54,15 +54,13 @@ When profile.mail is null or profile.mail.empty is true
         When mail is null
             obj = { success: false, error: "Unable to complete profile data: e-mail not provided" }
             Finish obj
-        Otherwise
-            profile.mail = [ mail ]
-
-id | E = Call idProc process profile
 
-When id is not null
-    obj = { success: true, data: { userId: id } }
-Otherwise
-    Log "@e Unable to process the incoming user" E
-    obj = { success: false, error: E.message }
-
+        profile.mail = [ mail ]
+
+uid | E = Call idProc process profile
+When E is null
+    Finish uid
+
+Log "@e Unable to process the incoming user" E
+obj = { success: false, error: E.message }
 Finish obj