{"_id":"574f9788a82f03190063bd00","user":"56688ec8ee1dbf0d008f62ae","__v":3,"githubsync":"","category":{"_id":"560b22739c7be70d00100bd8","pages":["560b229caf40a70d003df309","56bcb2cf9afb8b0d00d62df6"],"project":"55db8f8f1a91690d007ad975","version":"55db8f901a91690d007ad978","__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-29T23:44:51.456Z","from_sync":false,"order":6,"slug":"advanced-configurations","title":"Advanced configurations"},"parentDoc":null,"project":"55db8f8f1a91690d007ad975","version":{"_id":"55db8f901a91690d007ad978","project":"55db8f8f1a91690d007ad975","__v":17,"createdAt":"2015-08-24T21:41:36.034Z","releaseDate":"2015-08-24T21:41:36.034Z","categories":["55db8f901a91690d007ad979","55db9856b3d6540d00886426","55dc751b00a8811900c230e3","55dc766255be9f21004ee250","55dc769200a8811900c230ed","55e4c701177b6e0d003330fa","55f4915caf0bc71900a53130","55f491b2be9c2b2100f0635d","560b22739c7be70d00100bd8","57488c53e8c6a420000b729c","574cefd95953e20e00f40f9f","5798edfd7700d30e00ad250c","579ac88234b5fd0e00b9e140","57c81c6d690c200e0047b72e","57d9b8fbda17c30e003897f1","57d9b90e608ea00e00f358d8","57d9b91cda17c30e003897f4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-02T02:18:48.207Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"In most cases, the IMMUNIO agent will automatically instrument your app to detect all supported threat types.\n\nIf your app uses some features or libraries that Immunio does not yet support, you can still get full protection by calling the Immunio API from your app code to provide any missing information.\n\n## Authentication API\n\nIf you're using Passport, Immunio will automatically hook into your authentication system to protect you against attacks.\n\nIf you're not using the above framework, you will need to manually tell Immunio when authentication occurs. Use the following methods to do so.\n\nAfter a user logs in: *immunio.authentication.login(user, req)*\nAfter a failed login attempt:* immunio.authentication.failedLogin(user, req)*\nAfter a user logs out: *immunio.authentication.logout(user)*\nAfter the current user is changed (or set): *immunio.authentication.setUser(user, req)*\nAfter a user requests a password reset: *immunio.authentication.passwordReset(user, req)*\nAfter a failed requests for resetting a password: *immunio.authentication.failedPasswordReset(user, req)*\nNote: immunio.authentication.setUser(user, req) should be called for every request where user data is available, not just when authentication mechanisms are used.\n\nThese methods take a user object with the following properties their first argument:\n\nuser_id: String or Number\nusername, login or name: String\nemail: String\nreason: String (for failures)\nThe second argument should be the Node HTTP request (req) or response (res) object, if available.\n\nHere's an example:\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var immunio = require('immunio');\\n\\n// ...\\n\\napp.use(function(req, res, next) {\\n  // Assuming req.user is populated with the current user in a previous middleware.\\n  if (req.user) {\\n    immunio.authentication.setUser(req.user, req);\\n  }\\n});\\n\\napp.post('/login', function(req, res) {\\n  var username = req.body.username;\\n  var password = req.body.password;\\n\\n  db.findUser(username, password, function(err, user) {\\n    if (err) {\\n      // On failed login\\n      // ...\\n      immunio.authentication.failedLogin({ username: username }, req);\\n    } else {\\n      // On successful login\\n      // ...\\n      immunio.authentication.login({\\n        user_id: user.id,\\n        username: user.name,\\n        email: user.email\\n      }, req);\\n    }\\n  });\\n});\\n\\napp.get('/logout', function(req, res) {\\n  // Get the current user\\n  var user = req.user;\\n\\n  immunio.authentication.logout({\\n    user_id: user.id,\\n    username: user.name,\\n    email: user.email\\n  }, req);\\n\\n  // Your logout code ...\\n});\",\n      \"language\": \"text\",\n      \"name\": \"JavaScript\"\n    }\n  ]\n}\n[/block]\n## Waiting for Agent readiness\n\nBy default your app will start before Immunio is ready to protect it. If you want to prevent this behavior and wait for Immunio to be fully active before starting your app, use the following:\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var immunio = require('immunio');\\n\\n// ...\\n\\nimmunio.on('ready', function() {\\n  // Start your web server here.\\n  server.listen(port);\\n});\",\n      \"language\": \"text\",\n      \"name\": \"JavaScript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"node-agent-api","type":"basic","title":"Node.js Agent API"}
In most cases, the IMMUNIO agent will automatically instrument your app to detect all supported threat types. If your app uses some features or libraries that Immunio does not yet support, you can still get full protection by calling the Immunio API from your app code to provide any missing information. ## Authentication API If you're using Passport, Immunio will automatically hook into your authentication system to protect you against attacks. If you're not using the above framework, you will need to manually tell Immunio when authentication occurs. Use the following methods to do so. After a user logs in: *immunio.authentication.login(user, req)* After a failed login attempt:* immunio.authentication.failedLogin(user, req)* After a user logs out: *immunio.authentication.logout(user)* After the current user is changed (or set): *immunio.authentication.setUser(user, req)* After a user requests a password reset: *immunio.authentication.passwordReset(user, req)* After a failed requests for resetting a password: *immunio.authentication.failedPasswordReset(user, req)* Note: immunio.authentication.setUser(user, req) should be called for every request where user data is available, not just when authentication mechanisms are used. These methods take a user object with the following properties their first argument: user_id: String or Number username, login or name: String email: String reason: String (for failures) The second argument should be the Node HTTP request (req) or response (res) object, if available. Here's an example: [block:code] { "codes": [ { "code": "var immunio = require('immunio');\n\n// ...\n\napp.use(function(req, res, next) {\n // Assuming req.user is populated with the current user in a previous middleware.\n if (req.user) {\n immunio.authentication.setUser(req.user, req);\n }\n});\n\napp.post('/login', function(req, res) {\n var username = req.body.username;\n var password = req.body.password;\n\n db.findUser(username, password, function(err, user) {\n if (err) {\n // On failed login\n // ...\n immunio.authentication.failedLogin({ username: username }, req);\n } else {\n // On successful login\n // ...\n immunio.authentication.login({\n user_id: user.id,\n username: user.name,\n email: user.email\n }, req);\n }\n });\n});\n\napp.get('/logout', function(req, res) {\n // Get the current user\n var user = req.user;\n\n immunio.authentication.logout({\n user_id: user.id,\n username: user.name,\n email: user.email\n }, req);\n\n // Your logout code ...\n});", "language": "text", "name": "JavaScript" } ] } [/block] ## Waiting for Agent readiness By default your app will start before Immunio is ready to protect it. If you want to prevent this behavior and wait for Immunio to be fully active before starting your app, use the following: [block:code] { "codes": [ { "code": "var immunio = require('immunio');\n\n// ...\n\nimmunio.on('ready', function() {\n // Start your web server here.\n server.listen(port);\n});", "language": "text", "name": "JavaScript" } ] } [/block]