Enabling Authentication
tcWebhooks support two forms of Authentication.
- Username/Password Authentication (Basic Auth) Since 0.9.80.83 and 1.1-alpha5.81.121
- Bearer Token Authentication (Bearer) Since 1.1-alpha16
This page explains the options on the Authentication section on the Extra Config tab (shown below for Basic Authentication).
When Username/Password Authentication (Basic Auth) is selected as the authentication Type, the following options are shown:
The webhook will send credentials on the first request (pre-emptively) rather than waiting for a 401 Authentication Required response from the server (which would include the Realm to authenticate against).
When preemptive is disabled, each WebHook request makes two requests. The first without the Authorization header, which prompts the server to return 401. The HttpClient then checks that the realm returned in the response matches. If it does then a second request is sent with the Authorization header populated.
When preemptive is enabled, the Realm field is ignored and the Authorization header is sent with the first (and only) request. This could be considered a small security risk, in that the client is sending the username and password before being requested to, but it saves having to do two requests for every webhook.
The username to present. It is combined with the password then Base64 encoded and sent as the value in the Authorization header.
The password to present. It is combined with the username then Base64 encoded and sent as the value in the Authorization header. Be aware that the password is stored in plugin-settings.xml on the server in clear text. See issue #53.
The authentication realm you are expecting the endpoint point to challenge with. This setting is only effective if Preemptive is disabled. If Preemptive is disabled, then the webhook will send the request without the Authorization header. If a 401 is returned requesting Basic Authenication with a Realm that matches this value, then the request is sent again with the Authorization header populated.
Base64 is not considered at all secure and is akin to sending username and password as clear text. It is designed to be easily decoded. Basic Authentication should only be used over HTTPS.
To read more about Basic Authentication, please see the wikipedia article.
When Bearer Token Authentication (Bearer) is selected as the authentication Type, the following options are shown:
The webhook will send credentials on the first request (pre-emptively) rather than waiting for a 401 Authentication Required response from the server.
When preemptive is disabled, each WebHook request makes two requests. The first without the Authorization header, which prompts the server to return 401. The HttpClient then checks that host, port and http protocol (http or https) in the response matches. If it does then a second request is sent with the Authorization header populated.
When preemptive is enabled, the Authorization header is sent with the first (and only) request. This could be considered a small security risk, in that the client is sending the token before being requested to, but it saves having to do two requests for every webhook. In some cases it's also a requirement. See note below.
Preemptive must be enabled for Bearer authentication to work with Atlassian Stride. This is because the 401 response from Stride does not include the WWW-Authenticate: Bearer header, which tells HttpClient to use the Bearer authentication scheme to resolve the credentials.
The token to present to the server. It is sent as the value in the Authorization header. eg Authorization: Bearer my_token