| Description | This article describes how to manually map users to agents in FortiDLP using the API. | ||||||||||||||||||||||||||||
| Scope | FortiDLP. | ||||||||||||||||||||||||||||
| Solution |
Introduction: Mapping users to nodes is an essential part of data tracking and visibility within the organization. Its vital to correlate any event from a user on a particular node or to track events from a specific node among multiple users. The FortiDLP Cloud can help make these associations and allow for easy tracking of data amongst users and nodes. This article will explain how the FortiDLP Cloud can manage this and the ways it can be set up.
How FortiDLP Handles User Mapping: The FortiDLP Cloud handles user mapping by associating User UUIDs to node UUID's. FortiDLP uses User URI's to help make these associations. A User URI is a mapping of an agent, security ID, email, or hostname that is part of a user's metadata as a FortiDLP User. For Example, if a domain joined user John@example.com logs in to a node running the FortiDLP Agent, The agent is able to detect this information and associate events to this user. If Tom@example.com logs into the same machine, those events will be shown against the same node, however the events will be associated with Tom instead of John. This relies on two factors:
This will add two schemes that can be used for mapping. The first is the mail:// scheme, mapped to Email_Address. The second is username:// scheme, mapped to user portion of email (E.g. john.smith for email address john.smith@example.com)
Methods: There are three methods available to set up user mapping in FortiDLP:
Assigned Enrollment Bundles: This method assumes that an LDAP or Azure directory source has already been synced to the FortiDLP Cloud, or that users have been manually created in the FortiDLP Cloud via the API
The FortiDLP platform allows operators to create enrollment bundles for specific users. This associates all activity on the machine to the user chosen at the time of creating the enrollment bundle. This method makes for manually assigning users to nodes.
The LDAP sync tool: This method assumes that users will be logging into the machines with the account synced from the directory source. IE. Their Active Directory domain account if active directory was the directory source
The LDAP sync tool allows users to be imported from any directory source that supports the Lightweight Directory Access Protocol (LDAP). When users are imported from LDAP, they are assigned a security ID (SID) that is unique to that user. When that user then logs in to their machine with this directory account, the SID is associated with that login. The FortiDLP Agent can then determine the SID for each user that logs in and associate each event to the users that created them. No additional configuration is required for user mapping.
If users are imported via the LDAP sync tool, but instead log in with a local account. The events will be mapped to an "unknown" user. This is because the FortiDLP Cloud is not aware of the user that is logged in or how to associate them.
The FortiDLP API: The FortiDLP API is at the root of the previous methods. In some fashion, each of the methods relies on the underlying APIs to create users, check/retrieve user information, retrieve node information, and update a user with a new URI to associate a node to it. The basic steps to Associate a user with a node follow this flow:
The APIs used to perform this flow currently are:
The API explorer can be utilized to perform these API calls and verify the results.
User Association Mapping: /api/v2/users/bulk/useruri: FortiDLP introduced a bulk user mapping API method, which takes a CSV file as a parameter. The API can be used to send a single API call to map hundreds of Users to a scheme(s) concurrently. The format of the CSV determines the method for identifying the User, as well as the scheme to use and what map type to apply.
The CSV requires a header, with two fields present. The first column is for the User definition. The second for the map (scheme) type.
For instance, take the following CSV that will be uploaded for processing:
This will create a new record in /user/{userUUID}/useruri array with a value of machinename://WIN-1036475 in case 2 above.
However, this requires knowledge of the User juid, which can be tedious and time-consuming. There is another easier option. Because the current useruri mappings per user, if there is a value already known to exist, it is possible to use that to identify the user in a much quicker, easier way.
The Sync UserName Mappings setting mentioned above can be useful in this case. If non-Windows users login with the username mapping scheme mentioned above (user portion of email address), the mapping is already associated, and this step is not necessary. But, if that is not the scheme for Corporate user logins, or Mac/Linux users use a local login account (quite common) for logins, it is still possible to utilize the mail scheme as a way to easily and reliably determine the User to associate with.
Here's another example CSV file that takes advantage of this UserURI being pushed via Directory Sync:
In this case, the User's name and Email Address are necessary, which is much easier to gather than the User JUID. When the CSV is processed by tenant API, it will do a search for john.smith@example.com, and reverse lookup to determine the UserUUID. It will then make the mapping just as in the first example.
It is possible to use different schemes per user. By using the URI header, however, this does require the fully qualified scheme:
It is possible to map multiple schemes for a user at one time. This can be accomplished easily be simply adding more columns:
Optional parameters to be aware of: There are two parameters to be aware of, and their default values:
Return code and JSON response: If successful, will return a 200 OK, as well as a JSON with counts for the following:
{ "user_uris_added": 0, "user_uris_reassigned": 0, "users_skipped": 0 }
user_uris_added: The URI was successfully added to this user user_uris_reassigned: The URI was successfully added, and has been removed from a User who previously had the scheme URI mapping. user_skipped: With skip_unknown_users set to true, these would be records that were skipped because the User could not be defined from the record property.
Note: If a record exists that contains a scheme value already associated with the mapped user in CSV, it will be skipped, but will not be registered in any of the three bucket counts.
UserURI Schemes:
sid://: Mapping scheme used by AD. SID will be matched depending on events. If another user logs in, their SID will be then associated to those events/detections. This would automatically be picked up in AD/LDAP import.
agent://: Will map all activity onthe agent node to the User associated to. If another user logs in, the associated user will still be associated with any events/detections
username://: Will map all events/detections within Org that the login user is associated with. This scheme only makes sense if users have unique login names across all computers in the Org.
machinename:// :Will map all events/detections within Org that machine name is associate with. If another user logs in, the associated user will still be associated to any events/detections.
mail://: For future concerning mail events. Not applicable currently
Verifying Association: Keep in mind that once the association has been run, it will not be reflected in FortiDLP platform until next heartbeat check-in of agent (every ~15 minutes).
To verify before that, the API Explorer can be used by sending a GET to `API/v2/users/{userUUID}/useruri` to verify. The User UUID will be needed, which can be found under Users, choosing the column for UserUUID:
|
