Castle.Sdk 2.3.0

.NET SDK for Castle

Supporting .NET 8.0 and .NET Standard 2.1. Refer to Microsoft's documentation for compatibility information.

Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.

Usage

See the documentation for how to use this SDK with the Castle APIs.

Installation

Install the Castle.Sdk NuGet package.

.NET CLI

dotnet add package Castle.Sdk

Package Manager Console

Install-Package Castle.Sdk

Visual Studio

1. Go to Tools → Package Manager → Manage NuGet Packages for Solution...
2. Click the Browse tab and search for Castle.Sdk
3. Click the Castle.Sdk package in the search results, select version and what projects to apply it to on the right side, and click Install

Configuration

Go to the settings page of your Castle account and find your API Secret. Use it to create a new instance of the CastleClient class.

var client = new CastleClient(new CastleConfiguration("YOUR SECRET"));

It's a good idea to set up your CastleClient instance using an IoC container.

ASP.NET Core

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton(new CastleClient(new CastleConfiguration("YOUR SECRET")));
}

The CastleConfiguration object has a number of properties that control the SDK.

API Actions

All API action methods accept an ActionRequest object and are async.

Risk

var response = await client.Risk(new ActionRequest()
{
    Event = "$login",
    Status = "$succeeded",
    UserId = "user-123",
    RequestToken = "token-from-castle-js",
    Context = Castle.Context.FromHttpRequest(Request)
});

// response.Risk       - risk score (float)
// response.Policy     - policy evaluation result
// response.Signals    - signal details
// response.Device     - device information

Filter

var response = await client.Filter(new ActionRequest()
{
    Event = "$registration",
    Status = "$attempted",
    UserId = "user-123",
    RequestToken = "token-from-castle-js",
    Context = Castle.Context.FromHttpRequest(Request)
});

Log

await client.Log(new ActionRequest()
{
    Event = "$profile_update",
    UserId = "user-123",
    Context = Castle.Context.FromHttpRequest(Request)
});

Advanced: Build and Send

Each action supports a two-step pattern where you build the JSON request, optionally modify it, and then send it separately.

var jsonRequest = client.BuildRiskRequest(new ActionRequest()
{
    Event = "$login",
    UserId = "user-123",
    Context = Castle.Context.FromHttpRequest(Request)
});

// Inspect or modify jsonRequest (JObject) if needed

var response = await client.SendRiskRequest(jsonRequest);

This pattern is available for all actions: BuildRiskRequest / SendRiskRequest, BuildFilterRequest / SendFilterRequest, BuildLogRequest / SendLogRequest.

Request Context

Use Castle.Context.FromHttpRequest() to extract client context (IP, headers, client ID) from the current HTTP request.

ASP.NET Core

public class IndexModel : PageModel
{
    public void OnGet()
    {
        var actionRequest = new ActionRequest()
        {
            Context = Castle.Context.FromHttpRequest(Request),
            Event = "$login",
            UserId = "user-123"
        };
    }
}

Logging

The SDK allows customized logging by way of implementing the ICastleLogger interface and passing in an instance as part of the CastleConfiguration. Exactly what gets logged can be controlled by setting the LogLevel property of CastleConfiguration.

var client = new CastleClient(new CastleConfiguration("secret") {
    Logger = new MyLogger()
});

Logger example

public class DebugLogger : ICastleLogger
{
    public void Info(string message)
    {
        Debug.WriteLine($"INFO: {message}");
    }

    public void Warn(string message)
    {
        Debug.WriteLine($"WARNING: {message}");
    }

    public void Error(string message)
    {
        Debug.WriteLine($"ERROR: {message}");
    }
}

Demo application

There is a sample application using ASP.NET Core Razor Pages and this SDK here.