Updated External Authenticators (markdown)

External-Authenticators.md

@@ -22,4 +22,19 @@ As an example, you may examine the [CAS authentication adapter](https://github.c
 
 4. The token is sent to the API instead of credentials to perform the internal authentication process in the ReCodEx (the response is processed the same way as regular local login).
 
-When the API verifies the token, it tries to find exact match for the user external ID first. If it is missing, but there is a local account with the same e-mail address, the account is bound to the external ID and its local password is reset to void. If no account are found, the ReCodEx tries to register new user. For that, it requires ID of an instance to which the user belongs and role. The instance ID may be passed down in the token, but it also may be omitted if there is only one instance (typical case). The role must be also specified in the token, or default role must be set in core-api configuration (`defaultRole`) of that particular autenticator.
+When the API verifies the token, it tries to find exact match for the user external ID first. If it is missing, but there is a local account with the same e-mail address, the account is bound to the external ID and its local password is reset to void. If no account are found, the ReCodEx tries to register new user. For that, it requires ID of an instance to which the user belongs and role. The instance ID may be passed down in the token, but it also may be omitted if there is only one instance (typical case). The role must be also specified in the token, or default role must be set in core-api configuration (`defaultRole`) of that particular autenticator.
+
+The JWT token must hold following properties in the payload.
+* `iat` - unix timestamp when the token was created (expiration delay is set in the core-api, not in external auth service)
+* `id` - external ID of the user (string)
+* `mail` - e-mail address (string)
+* `firstName` - given name of the user (may be needed for the registration process)
+* `lastName` - family name of the user (may be needed for the registration process)
+* `role` - role identifier (`student`, `supervisor`, ...), needed for the registration, have no effect on authentication (optional)
+* `instanceId` - ID of an instance where the user should be registered if missing (optional)
+
+Actually, the token is loaded into [UserData](https://github.com/ReCodEx/api/blob/master/app/helpers/ExternalLogin/UserData.php) structure. For more details, se its declared properties for other optional JWT items.
+
+The token must be signed using a secret string that is shared between ReCodEx and external authentication service. Core-api holds this string in `jwtSecret` property of the authenticator configuration.
+
+Finally, the web-app needs to be configured to know about the external authenticator. See [web app configuration](https://github.com/ReCodEx/web-app#configuration).