3. Web services

In this mode, the raw username and password are sent (over HTTPS, so should be secure) on every request. Uses the "WebServices" channel by default and doesn't require any additional configuration, besides having the channel enabled. The drawback is that the username and password need to be stored in the client application, and changing the password on the web (if the same password type is used) will make the application stop working.

In this mode, a first request is made to LoginService.login() operation, returning a session token. Subsequent requests should pass this session token instead in the subsequent requests. To finish a session, a request to LoginService.logout() using the session token invalidates the session. This form also uses the "WebServices" channel by default, and doesn't require any additional configuration.

Access clients can be configured to prevent the login name and password to be passed on every request by clients, decoupling them from the actual user password, which can then be changed without affecting the client access, and improving security, as each client application has its own authorization token.

To configure access clients, first a new identification method of thist type must be created by administrators. Then, in a member product of users which can use this kind of access, permissions over that type should be granted. Finally, the user (or an admin) should create a new access client in Cyclos main access, and get the activation code for it. The activation code is a short (4 digits) code which uniquely identifies an access client pending activation for a given user. To use the access client, on the application side (probably a server-side application or an interactive application), an HTTP POST request should be performed, with the following characteristics:

The result will be a token which should be passed in requests. The activation process should be done only once, and the token will be valid until the access client in Cyclos is blocked or disabled.

Here is an example which can be called by the command-line program curl:

curl http[s]://<cyclos-root-url>[/network]/activate-access-client \
    -u "<username>:<password>"
    -d "<4-digit code>"

The generated token will be printed on the console, and should be stored on the client application to be used on requests.

Additionally, clients can improve security if they can have some unique identifier which can be relied on, and don't need to be stored. For example, Android devices always provide an unique device identifier. In that case, this identification string can be passed on the moment of activation, and will be stored on the server as a prefix to the generated token. The server will return only the generated token part, and this prefix should be passed on requests together with the generated token. The prefix is passed in the activation command, having the body of the request as: [4-digit activation code]:prefix. So, for example:

curl https://www.some-cyclos-instance.com/activate-access-client \
    -u "john:johnpassword"
    -d "1234:XYZW"

Imagining the server returns the fictional token ABCDEFG (the actual token is 64 characters long), the token to be used on requests would be XYZWABCDFG.

Alternatively, it is possible to do a request authenticated by username and password to the AccessClientService.activate() web service method, passing the activation code and prefix parameters. This can be more convenient for client applications that activate an access client interatively, for example, when the end user types in his username, password and 4-digit activation code.