{"__v":4,"_id":"5719767ec863120e0012a04f","category":{"project":"56008ba98c0c9d0d00dcaeb0","version":"5719767ec863120e0012a042","_id":"582b71b15403840f008c0410","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-11-15T20:36:01.349Z","from_sync":false,"order":2,"slug":"faq","title":"FAQ"},"parentDoc":null,"project":"56008ba98c0c9d0d00dcaeb0","user":"56008b651503430d007cc929","version":{"__v":3,"_id":"5719767ec863120e0012a042","hasDoc":true,"hasReference":true,"project":"56008ba98c0c9d0d00dcaeb0","createdAt":"2016-04-22T00:55:26.295Z","releaseDate":"2016-04-22T00:55:26.295Z","categories":["5719767ec863120e0012a043","5719767ec863120e0012a044","5719767ec863120e0012a045","5719767ec863120e0012a046","5719767ec863120e0012a047","5719767ec863120e0012a048","5719767ec863120e0012a049","57f45a18da14e71700d12e4a","582b71b15403840f008c0410"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-03T23:43:17.434Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"There are many places you can add our tracking code. This guide will walk you through the best places in your app to add ThisData’s Login Intelligence tracking. In principle, any part of your app which deals with authentication or account security is a great spot.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6IfIkbFjQgGSWl8TODLq_Track%20Events.png\",\n        \"Track Events.png\",\n        \"1503\",\n        \"918\",\n        \"#3371bc\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nIn most apps, you’ll have the following flow:\n\n- Ask a visitor for their username and password\n- If they get it right, they’re logged in\n- If they got it wrong, show them the log in form again.\n\nYou will probably have some other sensitive actions, like helping users reset their password.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Secure your successful log-in flow\"\n}\n[/block]\nThe most crucial path to monitor is the successful login path. After validating that a username and password are correct, it’s time to let ThisData know about it. Using your language of choice, send us a POST request with metadata about this. Read our [Event documentation](doc:apiv1events) to find out how and what to send.\n\nIt will probably end up looking something like this psuedocode:\n\n```\nif the user was successfully logged in\n  remember them with a cookie\n\n  and send an event to ThisData\n  url = “https://api.thisdata.com/v1/events?api_key=MY_API_KEY”\n\n  MyHTTPLibrary.post_request(url, {\n    \"verb\" :       ‘log-in’,\n    \"ip\" :         request.real_ip_address\n    \"user_agent\" : request.user_agent\n    \"user\" : {\n      \"id\" :       user.id,\n      \"email\" :    user.email,\n      \"name\" :     user.name\n    }\n  })\n\n  show them their home page\nendif\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Will this break my app?\",\n  \"body\": \"Good question! The answer is no, and we explain why on our [How do you not break my app?](doc:how-do-you-not-break-my-app) page.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Track when a user or attacker gets an account password wrong\"\n}\n[/block]\nWhen a password is incorrect, but the username or email address is correct, we can track failed login attempts to their account. This is useful for detecting when an attacker is trying to guess someone's password.\n\nNote: currently we DO NOT send \"was this you\" notifications for `log-in-denied` events\n\n```\nif the user was successfully logged in\n  ... see above ...\nelse\n  // was it a valid account?\n  if user with email address exists?\n  url = “https://api.thisdata.com/v1/events?api_key=MY_API_KEY”\n\n  MyHTTPLibrary.post_request(url, {\n    \"verb\" :       ‘log-in-denied’,\n    \"ip\" :         request.real_ip_address\n    \"user_agent\" : request.user_agent\n    \"user\" : {\n      \"id\" :       user.id,\n      \"email\" :    user.email,\n      \"name\" :     user.name,\n      \"authenticated\" : false\n    }\n  )\n```\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"{authenticated: false}\",\n  \"body\": \"When the user is logged in and performing actions, send their user id. They've successfully authenticated.\\nWhen the user is *not* logged in yet, make sure to also send the `authenticated` parameter, set to false. It's an event about that user, but they're not yet authenticated.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"We only send emails for suspicious login events\",\n  \"body\": \"Events you send for anything other than `log-in` events are fantastic - but we won't send your end users emails about them. [Read more about when and where we send Was This You notifications](doc:was-this-you-notifications-when-and-where)\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Track when a user or attacker gets an account email and password wrong.\"\n}\n[/block]\nIf both the username and email are incorrect, there is no \"User\" to tie the event to. You don't have to track this event, but if you do it can help detect when an attacker is trying to guess both a username and password.\n\nWe recommend that you use the special ID `\"anonymous\"`, so that all of these requests are grouped together as a single ThisData Profile. But by providing the attempted username and/or email address in the email and name fields, you can still have detailed logs. This behaviour is the default when you don't send a user ID.\n\n```\n  if user with email address exists?\n\n    ... see above ...\n\n  else\n\n    // We don't know who it was, but track it as a special case\n\n    MyHTTPLibrary.post_request(url, {\n      \"verb\" :       ‘log-in-denied’,\n      \"ip\" :         request.real_ip_address\n      \"user_agent\" : request.user_agent\n      \"user\" : {\n        \"email\" :    attempted_email_address,\n        \"name\" :     attempted_email_address\n      }\n    )\n```\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Don't know who it was?\",\n  \"body\": \"You can still track events, even when they don't match an existing user on your website. You can exclude sending the user ID when this is the case.\\nNote - you don't *need* to send `authenticted: false`, but you can if you want to be explicit. :)\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using two-factor auth?\"\n}\n[/block]\nGood on you! We do too, for customers who want it turned on. The steps above cover when your users log in with just a username and password. When you use 2FA we recommend you:\n\n- send a `login-challenge` event when the user provides the right email address and password, but is challenged to provide a second factor code\n- if they provide a valid two factor code, send a `log-in` event\n- if they fail to provide a valid code, send a `log-in-denied` event\n\nIn these cases, you can send the user's ID, because they have partially authenticated as that user. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using SSO? (Sign in with Google / Sign in with Facebook, etc)\"\n}\n[/block]\nUs too! Those providers do a great job with security, but it’s still prudent to track those logins. Particularly because if, for example, your user's Google account is compromised and used to log in to your app, any email Google might send does not get user feedback, preventing you from creating security workflows and responding to incidents quickly.\n\nWhat we recommend is tracking `log-in` events when a user is logged in using SSO.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Track when an account gets its password reset\"\n}\n[/block]\nAccount recovery functions are a common target for compromising an account. Usually this is done via email; someone puts in their email address, and you send an account recovery message to their email address.\n\nFor auditing purposes, you should also notify ThisData. We won't email them - because you already have! But if their account is then logged in to from a new location and you've done the steps above, we'll alert you and them about this strange activity. And when you look at ThisData's Audit log for that user.","excerpt":"This guide will walk you through the best places in your app to add ThisData’s Login Intelligence tracking. In principle, any part of your app which deals with authentication or account security is a great spot.","slug":"what-events-should-i-track","type":"basic","title":"What Events Should I Track?"}

What Events Should I Track?

This guide will walk you through the best places in your app to add ThisData’s Login Intelligence tracking. In principle, any part of your app which deals with authentication or account security is a great spot.

There are many places you can add our tracking code. This guide will walk you through the best places in your app to add ThisData’s Login Intelligence tracking. In principle, any part of your app which deals with authentication or account security is a great spot. [block:image] { "images": [ { "image": [ "https://files.readme.io/6IfIkbFjQgGSWl8TODLq_Track%20Events.png", "Track Events.png", "1503", "918", "#3371bc", "" ], "sizing": "full" } ] } [/block] In most apps, you’ll have the following flow: - Ask a visitor for their username and password - If they get it right, they’re logged in - If they got it wrong, show them the log in form again. You will probably have some other sensitive actions, like helping users reset their password. [block:api-header] { "type": "basic", "title": "Secure your successful log-in flow" } [/block] The most crucial path to monitor is the successful login path. After validating that a username and password are correct, it’s time to let ThisData know about it. Using your language of choice, send us a POST request with metadata about this. Read our [Event documentation](doc:apiv1events) to find out how and what to send. It will probably end up looking something like this psuedocode: ``` if the user was successfully logged in remember them with a cookie and send an event to ThisData url = “https://api.thisdata.com/v1/events?api_key=MY_API_KEY” MyHTTPLibrary.post_request(url, { "verb" : ‘log-in’, "ip" : request.real_ip_address "user_agent" : request.user_agent "user" : { "id" : user.id, "email" : user.email, "name" : user.name } }) show them their home page endif ``` [block:callout] { "type": "info", "title": "Will this break my app?", "body": "Good question! The answer is no, and we explain why on our [How do you not break my app?](doc:how-do-you-not-break-my-app) page." } [/block] [block:api-header] { "type": "basic", "title": "Track when a user or attacker gets an account password wrong" } [/block] When a password is incorrect, but the username or email address is correct, we can track failed login attempts to their account. This is useful for detecting when an attacker is trying to guess someone's password. Note: currently we DO NOT send "was this you" notifications for `log-in-denied` events ``` if the user was successfully logged in ... see above ... else // was it a valid account? if user with email address exists? url = “https://api.thisdata.com/v1/events?api_key=MY_API_KEY” MyHTTPLibrary.post_request(url, { "verb" : ‘log-in-denied’, "ip" : request.real_ip_address "user_agent" : request.user_agent "user" : { "id" : user.id, "email" : user.email, "name" : user.name, "authenticated" : false } ) ``` [block:callout] { "type": "warning", "title": "{authenticated: false}", "body": "When the user is logged in and performing actions, send their user id. They've successfully authenticated.\nWhen the user is *not* logged in yet, make sure to also send the `authenticated` parameter, set to false. It's an event about that user, but they're not yet authenticated." } [/block] [block:callout] { "type": "info", "title": "We only send emails for suspicious login events", "body": "Events you send for anything other than `log-in` events are fantastic - but we won't send your end users emails about them. [Read more about when and where we send Was This You notifications](doc:was-this-you-notifications-when-and-where)" } [/block] [block:api-header] { "type": "basic", "title": "Track when a user or attacker gets an account email and password wrong." } [/block] If both the username and email are incorrect, there is no "User" to tie the event to. You don't have to track this event, but if you do it can help detect when an attacker is trying to guess both a username and password. We recommend that you use the special ID `"anonymous"`, so that all of these requests are grouped together as a single ThisData Profile. But by providing the attempted username and/or email address in the email and name fields, you can still have detailed logs. This behaviour is the default when you don't send a user ID. ``` if user with email address exists? ... see above ... else // We don't know who it was, but track it as a special case MyHTTPLibrary.post_request(url, { "verb" : ‘log-in-denied’, "ip" : request.real_ip_address "user_agent" : request.user_agent "user" : { "email" : attempted_email_address, "name" : attempted_email_address } ) ``` [block:callout] { "type": "warning", "title": "Don't know who it was?", "body": "You can still track events, even when they don't match an existing user on your website. You can exclude sending the user ID when this is the case.\nNote - you don't *need* to send `authenticted: false`, but you can if you want to be explicit. :)" } [/block] [block:api-header] { "type": "basic", "title": "Using two-factor auth?" } [/block] Good on you! We do too, for customers who want it turned on. The steps above cover when your users log in with just a username and password. When you use 2FA we recommend you: - send a `login-challenge` event when the user provides the right email address and password, but is challenged to provide a second factor code - if they provide a valid two factor code, send a `log-in` event - if they fail to provide a valid code, send a `log-in-denied` event In these cases, you can send the user's ID, because they have partially authenticated as that user. [block:api-header] { "type": "basic", "title": "Using SSO? (Sign in with Google / Sign in with Facebook, etc)" } [/block] Us too! Those providers do a great job with security, but it’s still prudent to track those logins. Particularly because if, for example, your user's Google account is compromised and used to log in to your app, any email Google might send does not get user feedback, preventing you from creating security workflows and responding to incidents quickly. What we recommend is tracking `log-in` events when a user is logged in using SSO. [block:api-header] { "type": "basic", "title": "Track when an account gets its password reset" } [/block] Account recovery functions are a common target for compromising an account. Usually this is done via email; someone puts in their email address, and you send an account recovery message to their email address. For auditing purposes, you should also notify ThisData. We won't email them - because you already have! But if their account is then logged in to from a new location and you've done the steps above, we'll alert you and them about this strange activity. And when you look at ThisData's Audit log for that user.