Auth logs

When a user tries to sign into an app that is protected by Kolide Device Trust, you may have questions about the user’s experience. Auth logs are designed to answer the most common questions administrators have, including:

• What browser did the user sign in from?
• Was the Kolide agent successfully detected?
• Was the device initially blocked?
• Did the user click any Checks to view more details?
• Did they attempt to recheck their device?
• What country did the authentication originate from?

…and more!

Viewing auth logs

There are several ways you can access Auth Logs within Kolide.

For a single device

Auth logs are available for all registered devices in Kolide. Just go to any Device’s overview page, and click Auth Logs in the tabbed menubar.

Not only will you see authentication attempts from the registered user of the device, you may also see notification attempts from other users who attempted to sign into apps with this device. Those attempts will be unsuccessful unless the device allows authentications from multiple users.

For a person

Auth Logs are also available for every user listed in the People in Kolide. Just go to any Person’s details page, and click Auth Logs in the tabbed menubar.

Unlike the device-scoped view, here you can get insight into failed authentication attempts where the agent was not detected.

Viewing everything

If you don’t have a particular person or device in mind and want to see Auth Logs across the entire system, you can do so by clicking on Tools > Auth Logs in the main navigation.

Unlike the other views, viewing the global Auth Log shows both the person and the device that signed in. Additionally, to aid in searching, the view can be filtered by different fields recorded in each Auth Log.

Viewing programmatically

Auth logs are also accessible programmatically through the Kolide API. If you haven’t already, create an API Key. There are no special permissions needed to access audit log entires programmatically.

Refer to Kolide’s API Reference for documentation on how to programmatically access auth logs.

curl --request GET \
     --url 'https://api.kolide.com/auth_logs?per_page=25' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <TOKEN>' \
     --header 'x-kolide-api-version: {{latest_api_version}}'

{
  "data": [
    {
      "id": "id5566707866140862015275017",
      "timestamp": "2023-11-26T15:38:09.179Z",
      "person_name": "Jason Meller",
      "person_email": "jason@kolide.co",
      "person_info": {
        "identifier": 1,
        "link": "https://api.kolide.com/people/1"
      },
      "device_info": {
        "identifier": 135129,
        "link": "https://api.kolide.com/devices/1"
      },
      "result": "Success",
      "initial_status": "all_good",
      "ip_address": "123.123.123.123",
      "agent_version": "1.2.1",
      "country": "United States",
      "city": "Winchester",
      "browser_name": "Safari",
      "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15",
      "issues_displayed": [],
      "events": [
        {
          "timestamp": "2023-11-26T15:38:09.116Z",
          "event_type": "sign_in_attempt",
          "event_description": "SAML session started by jason@kolide.co"
        },
        {
          "timestamp": "2023-11-26T15:38:09.559Z",
          "event_type": "agent_detection_success",
          "event_description": "Kolide agent found"
        },
        {
          "timestamp": "2023-11-26T15:38:10.844Z",
          "event_type": "sign_in_success",
          "event_description": "SAML session completed successfully"
        }
      ]
    }
    // SNIP
  ],
  "pagination": {
    "next": "https://api.kolide.com/auth_logs?per_page=25&cursor=aWQ2NDMwNzY1NDUzMzMyMjA1MjI4ODgzNDksMjAyMy0wMy0wOCAxNDoyNzo1MC41ODMwMDA=",
    "next_cursor": "aWQ2NDMwNzY1NDUzMzMyMjA1MjI4ODgzNDksMjAyMy0wMy0wOCAxNDoyNzo1MC41ODMwMDA=",
    "current_cursor": "",
    "count": 25
  }
}

Auth log anatomy

An auth log is a visualization of an Auth Log Session which contains many Auth Log Events. An Auth Log Session is created when an end-user is first redirected to Kolide to complete the Device Trust authentication flow and the events that happen in that flow are associated with that session.

Auth Log Sessions are a summarization of the end-user’s authentication experience and is modified while the session is still open. Once the session ends (either with a successful or failed authentication event), the session is no longer updated.

Data available

A session contains the following information:

• Result - Describes if the end-user’s authentication attempt was successful or not. Can be either Success or Fail.

• Person - The full name of the end-user who attempted to authenticate.

• Device - The display name and icon for the device that was used to authenticate. This will show as No Agent Detected if Kolide could not communicate with the agent.

• Initial Status - The Device’s initial authentication status at the start of the Auth Log Session. Can be one of All Good, Will Block, Blocked or -- (if the device could not be identified)

• Location - A flag representing the country the authentication originated from, along with the city and country’s two-letter code.

• Date - The start time of the authentication attempt shown in the user’s local time.

• Browser - The common name of the browser along with its major version number (for example, Safari 17). You can hover on this field to view the User Agent associated with this authentication attempt.

• Agent Version - The Semantic Version number of the Kolide agent detected during authentication or Unknown Version if agent detection failed

• IP Address - The remote IP addresses Kolide saw the authentication request originate from. Both IPv4 and IPv6 formats are displayed

• Issues Displayed To End User - A list of Issue titles and their blocking status icons for each issue shown to an end-user during authentication. Note: Issues listed here may be skipped if the user was previously warned about them in a previous authentication attempt in the last 24 hours.

• Events - A list of events and when they occurred, represented as the amount of minutes and seconds elapsed since the start of the authentication session. For a list of possible events, see the Event Types section.

Event types

Below, you will find a listing of the different events collected during the authentication process and when Kolide began collecting them.

Limiting access

Since authentication logs can be considered sensitive (they reveal the time and the general location of the authenticated user), you may want to limit access to this feature.

Disabling the feature

To disable viewing authentication logs for all users, including full administrators:

1. Click your avatar in the upper-right corner of the app.
2. Click Settings.
3. Click Restrictions in the left sidebar menu.
4. Tick the checkbox Disable Viewing Auth Logs for All Users.
5. Click Save (this action will be logged in the audit log).

Disabling for a specific user

Kolide users with Limited Access can either be invited with the Auth Log restricted, or have their access revoked later.

To restrict a Kolide Admin’s access:

1. Click your avatar in the upper-right corner of the app.
2. Click Settings.
3. Click Users & Access in the left sidebar menu.
4. Locate the user you want to restrict and click Edit.

5. In the modal that opens, make sure the Restricted Access radio button is selected. This will reveal Feature Restrictions options.
6. Check the Restrict Auth Logs box.
7. Click Save to apply the changes.

Glad to hear it! If you have anything you'd like to add, feel free to contact us.

Sorry to hear that. Please contact us if you'd like to provide more details.