Logging in Bitbucket

For more information on audit and regular logging in Bitbucket, please refer to this page:
https://wiki.resolution.de/doc/api-token-authentication/latest/admin-guide/logging/logging-in-bitbucket

Audit Logging 

The Jira and Confluence audit log holds records of key activities, such as adding new users, changing group memberships and many others.
Read more about it here: 
https://confluence.atlassian.com/adminjiraserver/auditing-in-jira-938847740.html 
https://confluence.atlassian.com/doc/auditing-in-confluence-829076528.html

Default Audit Logging

Creating and deleting tokens is always added to the audit log. It contains a few details of the token along with its ID which is intended to cross-reference tokens (i.e. to identify the revocation of a token)

Example Audit Log Jira

Advanced Audit Logging

Sys admins have more control over what events should be added to the audit log.

Please consider carefully what type of authentication events you want to audit-log. Depending on the number of REST requests and the event types, the audit log size might increase very quickly.
Having a long audit log retention period combined with a lot of recorded events may affect your database and its performance.


In the Audit Logging tab, you can select the following events to be logged. All these are turned off by default.

  1. Successful Authentication
  2. Failed Authentication Attempts
    1. Audit-log failed API token basic authentication attempts
    2. Audit-log failed API token bearer authentication attempts
    3. Audit-log failed API token verification
  3. Permission Denied

Examples

With 1 - Successful Authenticationactivated, a successful authentication with an API token is recorded into the audit log.
Because of technical limitations, the author is shown as "Anonymous".  
The "Affected object(s)" column, however, shows the reference to the user who logged in.



Option 2 - Audit-log failed API token basic authentication attempts - a) is only available, if basic authentication with regular passwords is disabled.
A valid API token is expected and if this is not the case, an audit record like the one below is created.

It also includes logging of attempts coming from an IP address that is restricted by the app:


Option 3 - Audit-log failed API token bearer authentication attempts - a) is only available, if bearer authentication with other authenticators is disabled.
A valid API token is expected and if this is not the case, an audit record like the one below is created. It also includes logging attempts coming from an IP address that is restricted by the app.

For failed bearer authentication we can't show the username because it can only be derived from a valid token. 




With 2 c) - Audit-log failed API token verification - activated, many other API interactions with regular passwords or bearer tokens might be recorded
since there is no way to tell for certain if the authentication header contains an API token, a password or a token from another authenticator app.
Thus, it might lead to a lot of events being recorded and is usually not advised.






With 3 - Permission Denied - activated,
Using tokens with a "Read Only" scope for a write operation will result in a record like the one below:

Audit Logging in Confluence

It seems that Confluence is showing the client IP address in the Load balancer/proxy IP address field and reverse. This is already the case for audit-log records not created by the API Token app and seems to be a Confluence issue.


Logfile

After changing the log level for the package de.resolution.apitokenauth to INFO our app writes additional entries to the log file.
Jirahttps://your-jira/secure/admin/ViewLogging.jspa

You need to adjust your log4j configuration so that the logging persists across Jira restarts. Atlassian describes that here: https://confluence.atlassian.com/confkb/how-to-change-logging-and-profiling-settings-to-permanent-setting-641663141.html
For your convenience, please find below a log4j configuration example that redirects all INFO logging to a file called apitokenservice.log
The log4j configuration needs to be adjusted on each node of the cluster.

log4j.logger.de.resolution.apitokenauth=INFO, apitokenservice
log4j.additivity.de.resolution.apitokenauth=false  

log4j.appender.apitokenservice=com.atlassian.jira.logging.JiraHomeAppender
log4j.appender.apitokenservice.File=apitokenservice.log
log4j.appender.apitokenservice.MaxFileSize=20480KB
log4j.appender.apitokenservice.MaxBackupIndex=10
log4j.appender.apitokenservice.layout=com.atlassian.logging.log4j.NewLineIndentingFilteringPatternLayout
log4j.appender.apitokenservice.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSSZ} %t %p %X{jira.username} %X{jira.request.id} %X{jira.request.assession.id} %X{jira.request.ipaddr} %X{jira.request.url} [%q{2}] %m%n
CODE


Confluencehttps://your-confluence/admin/viewlog4j.actionRead here on how to make the log level persistent


You'll then see the authentication-related entries below in the Jira or Confluence log file. These entries contain:

  • a description of the event
  • the token description (if applicable to the event)
  • the token scope (if applicable for the event) 
  • the username
  • the path of the REST endpoint for the call

When using Datacenter, the log file entries might be distributed across one or multiple nodes, depending on where the load balancer directed the request to.
You might not see anything on one node but on others instead.


Successful Authentication

2020-09-22 15:20:50,922+0000 http-nio-8080-exec-11 INFO anonymous 920x447x1 - 87.173.216.109,100.120.0.11 /rest/de.resolution.apitokenauth/latest/user/token [d.r.a.platform.auth.ApiTokenAuthSharedBase] Found a matching token "API Token from 2020-09-22" with Read & Write scope and authenticated user admin. Token was created on Sep 22, 2020 2:43:30 PM. REST endpoint: /rest/de.resolution.apitokenauth/latest/user/token

2020-09-22 15:20:50,922+0000 http-nio-8080-exec-11 INFO admin 920x447x1 - 87.173.216.109,100.120.0.11  /rest/de.resolution.apitokenauth/latest/user/token [d.r.a.platform.auth.ApiTokenAuthenticationFilter] User successfully authenticated

The second line was introduced with version 2.1 and it contains the username in a format that most log file analyzers can extract with default templates.

Failed Authentication Attempts

Only if basic authentication with a regular password is disabled in the app settings, it's safe to tell if a token provided was wrong, causing the below message in the log file:

2020-09-22 15:20:10,658+0000 http-nio-8080-exec-21 INFO anonymous 920x445x1 - 87.173.216.109,100.120.0.11 /rest/de.resolution.apitokenauth/latest/user/token [d.r.a.platform.auth.ApiTokenAuthSharedBase] Token verification for user admin failed: No valid API token was provided and basic auth with password is disabled. REST endpoint: /rest/de.resolution.apitokenauth/latest/user/token

Another reason for a failed authentication attempt might be an IP restriction:

2020-09-22 15:18:44,234+0000 http-nio-8080-exec-3 INFO anonymous 918x438x1 - 87.173.216.109,100.120.0.11 /rest/de.resolution.apitokenauth/latest/user/token [d.r.a.platform.auth.ApiTokenAuthSharedBase] Token verification for user admin failed: IP address 87.173.216.109 of request is not allowed to access the REST API and basic auth with password is disabled. REST endpoint: /rest/de.resolution.apitokenauth/latest/user/token


If basic authentication with a regular password is enabled, it might still be a valid password that is accepted by the Jira- or Confluence password authenticator. Hence, the log message reads like this:

2020-09-22 15:17:34,151+0000 http-nio-8080-exec-6 INFO anonymous 917x429x1 - 87.173.216.109,100.120.0.11 /rest/de.resolution.apitokenauth/latest/user/token [d.r.a.platform.auth.ApiTokenAuthSharedBase] User automation-user tried to authenticate with an invalid token or regular password. Passing the request further to the default authenticator. REST endpoint: /rest/de.resolution.apitokenauth/latest/user/token

Permission Denied Events

If a token with a "Read Only" scope is used during a write operation, a 403 error is returned as REST response and leaves a log file entry like the one below.
Other 403 errors logged by de.resolution.apitokenauth.ApiTokenAuthenticationService should only occur in rare events.

2020-09-22 15:14:05,087+0000 http-nio-8080-exec-16 INFO anonymous 914x405x1 - 87.173.216.109,100.120.0.11 /rest/api/2/myself [d.r.a.platform.auth.ApiTokenAuthSharedBase] Token verification for user automation-user failed: The token scope is read-only and only covers GET, HEAD and OPTIONS requests. Request method type was PUT. REST endpoint: /rest/api/2/myself

Rate Limited Requests

If rate-limiting is enabled, logging the package de.resolution.apitokenauth.platform.auth.ApiTokenRateLimiter on INFO level provides the below record in the log file. This has been added in version 1.9.4.

2022-02-08 13:37:58,047+0000 http-nio-8080-exec-24 INFO anonymous 817x2506x1 1gs98du 90.26.72.124,100.100.0.45 /rest/api/2/myself [d.r.a.platform.auth.ApiTokenRateLimiter] User admin has been rate limited. The API token allows executing 5 requests within 5 minutes.