This page describes external authentication protocol for ReCodEx and parameters that affect its configuration. We have decided to completely outsource external authentication using our own protocol since it is much simpler than rely on robust protocols like CAS. The disadvantage is that any external authentication system now require an adapter script or application that handles the authentication and then generates token for ReCodEx. On the other hand, if appropriate client libraries exist for selected authentication system, it should me a matter of simple script.

At present, ReCodEx may have but one external authenticator; however, it would not be difficult to extend this.

As an example, you may examine the [CAS authentication adapter](https://github.com/ReCodEx/cas-auth-ext) for ReCodEx, which we currently maintain.


## Fundamentals

* The external authentication service must be identified by unique string. This string is also stored in database as discriminator for external user IDs.
* The authentication service must have its own URL (it may very well run on the same server as ReCodEx, but in that case, it must have its own path or domain).
* The authentication service is also used to directly register new users into ReCodEx. Hence, it must provide some information, such as full name, email, or possibly suggested role.


## Protocol

1. If the external service is configured, the web-app shows appropriate button at the login page. This button opens external dialog window with the URL of the service (no parameters are passed to this window, all necessary data must be already in the configuration of external authenticator).

2. Once the external service do its bidding, it is supposed to generate a [JWT](https://jwt.io/) token and pass it back to the dedicated web-app page `recodex-base/login-extern/<service-id>` where the token is assigned to URL query parameter `token`.

3. The `login-extern` web-app page extracts the token from the URL and passes it back to original window using DOM message interface.

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.

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).