User Authentication

It is not unusual for a Botize application to make use of third party services that require user authentication. When that's the case, Botize will prompt the user to perform the appropriate authentication procedure when selecting the affected function to be used for a task.

Please be aware that the same authentication service will be shared by the trigger and the action of the task; at this time Botize does not allow to use separate services for the trigger and the action. However, it is possible to use different user credentials for the trigger and the action of a task.

An application declares that it needs the user to authenticate by returning the appropriate value in the user_auth_mode element of the data returned by the get_app_info command. There are two authentication mechanisms available: credentials and web.

The credentials authentication mode is the simplest of the two and works as follows:

1. Botize provides a form where the user introduces a username and password.
2. When the user submits the form Botize invokes the application's authenticate_user method, passing in the supplied username and password.
3. The application checks the credentials and returns a block of information that indicates whether the credentials were valid or not. If the credentials were valid, an application generated authentication token is returned as well.
4. Every time that Botize invokes the trigger or the action of the task, it will include the authentication token in the supplied data.

Please be aware that credentials data and authentication tokens are sent in plain text, therefore using HTTPS is strongly recommended if this authentication mode is used.

The web authentication mode is the most common mode and is used when the third party service requires the user to log in and supply his credentials in a web page provided by the service itself. This is primarily intended for (but not limited to) services that use OAuth for authentication.

The workflow for the web authentication mode is as follows:

1. Botize invokes the application's begin_authenticate_user command, passing in a callback URL in the Botize domain. The application returns the URL of the authentication page for the service; this URL must somehow include the supplied Botize callback address, how this is done is service dependant.
2. Botize shows a “Click here to begin authentication process” message to the user. The message links to the authentication URL provided by the application in the previous step.
3. The user performs the appropriate login and authorization process in the service page, which then invokes the Botize callback URL.
4. Botize invokes the application's end_authenticate_user command, passing in all the parameters included by the service in the GET request to the Botize callback.
5. The application examines the parameters returned by the service and returns a block of information that indicates whether the credentials were valid or not. If the credentials were valid, an application generated authentication token is returned as well.
6. Every time that Botize invokes the trigger or the action of the task, it will include the authentication token in the supplied data.

This authentication method is as secure as the service authentication page is, which usually means pretty secure since using HTTPS is commonplace for Internet services nowadays.