.NET Core

Overview

.NET Core provides login hooks using the .NET Core service and dependency injection frameworks. The hooks are API calls which pass login information to the tCell Agent as a part of monitoring and protection for Account Takeover. The tCell Agent initializes the hooks at startup time by dependency injection. These calls do nothing if tCell is not installed, so there is no requirement to have the tCell Agent installed for the code to function.

Service Registration

Register the hooks in the application's Startup class.

  1. Add using Tcell.Agent.AspNetCore; to the namespace declarations at the top of the Startup class
  2. Add services.AddTcellHooks(); to the Configure Services method. See the following example:
Sample ConfigureServices method
1
public void ConfigureServices(IServiceCollection services)
2
{
3
services.AddMvc();
4
services.AddTcellHooks();
5
}
6

Using the Hooks

Once registered as a service, the agent login hooks are used by the standard .NET Core controller Dependency Injection mechanism. Follow these steps to implement:

  1. Store the login hooks as a member variable in the constructor, which was populated by dependency injection. Here’s an example:
Sample Hooks Dependency Injection
1
using Tcell.Agent.Hooks;
2
...
3
4
5
private readonly ILoginHooks _loginHooks;
6
7
public LoginController(ILoginHooks loginHooks)
8
{
9
_loginHooks = loginHooks;
10
}
11
  1. Next, invoke the hooks' LoginSuccess or LoginFailed in the controller method(s) that performs authentication.

LoginSuccess

There are two variants of LoginSuccess method - one with a password, one without. As this information is fed into the Account Takeover feature, if a password is available, we recommend using that method to provide additional data to the Account Takeover algorithm.

LoginSuccess API Definition
1
public void LoginSuccess(string userName);
2
public void LoginSuccess(string userName, string password);

Parameters:

  • userName: the username of user successfully logged in
  • password: the password of user successfully logged in with; See Password Hash section for additional details on the password usage.

LoginFailed

LoginFailed has 4 variations which all require userName. Some have optional password or userValid arguments, signifying the password of a failed login and whether the username passed is valid, respectively. All of this information is fed into the Account Takeover feature, so we recommend using the method with the most information, if available.

LoginFailed API Definition
1
public void LoginFailed(string userName);
2
public void LoginFailed(string userName, string password);
3
public void LoginFailed(string userName, bool userValid);
4
public void LoginFailed(string userName, string password, bool userValid);
5

Parameters:

  • userName: the username of user failed to login
  • password: the password of user failed to login; see Password Hash section for additional usage details
  • userValid: Whether the username of failed login is a valid username

Example

The following is an example of a simple controller that sends a login hook event based on a simple hardcoded authentication algorithm. It assumes a helper model LoginModel. For simplicity, the controller is also given with no namespace.

Sample controller using hooks
1
using Microsoft.AspNetCore.Mvc;
2
using Tcell.Agent.Hooks;
3
4
public class LoginController : Controller
5
{
6
private readonly ILoginHooks _loginHooks;
7
8
public LoginController(ILoginHooks loginHooks)
9
{
10
_loginHooks = loginHooks;
11
}
12
13
public IActionResult Default(LoginModel model)
14
{
15
var validUser = model.UserName == "username";
16
var validPassword = model.Password == "password";
17
if (validUser && validPassword)
18
{
19
_loginHooks.LoginSuccess(model.UserName, model.Password);
20
}
21
else
22
{
23
_loginHooks.LoginFailed(model.UserName, model.Password, validUser);
24
}
25
return Ok();
26
}
27
}