Supported Platforms

Thoughtfully architected and insanely flexible, ASPSecurityKit (ASK) provides several absolutely essential features to rapidly develop highly reliable, secure and scalable web apps and APIs on all major .NET platforms including ASP.NET Core (both Mvc/Api are supported), ASP.NET Mvc, ASP.NET Web Api and ServiceStack (both .NET Framework and .NET Core are supported).

Library and Source Packages

ASPSecurityKit comes in two forms.

Library Features

Security Pipeline

A comprehensive security pipeline that’s built on zero-trust security model, is extremely flexible and extensible. The pipeline provides a multi-stage, checks and verifications workflow that includes cross-site scripting (XSS), authentication (multiple schemes/methods supporting different integration scenarios), multi-factor, IP-firewall, user verification, activity-based, data-aware authorization (ADA), suspension and much more.

Authentication

Authentication answers the question ‘Who are you?’ latest web systems are expected to support connectivity with many kinds of callers including browsers, mobile apps, IoT devices, backend jobs, third-party services etc. each of which may likely need a different authentication scheme or method to identify itself securely. The pipeline supports multitude of authentication schemes, each of which can support multiple types of identities (if applicable).

Authentication Schemes

An authentication scheme represents the protocol that identifies the type of the auth token being used to authenticate.

HMAC

First-class support for authenticating requests signed with a strong HMAC scheme that considers URL, HTTP method, request body, timestamp and a nonce (random GUID) as signature input, protecting against request tampering. Used as primary scheme for connecting with API platforms. AuthUrn as another input component ensures that any type of identity (be it API key, user session, etc. can be used with HMAC scheme).

BHIS would like to commend Forge Trust on their implementation of the authorization header. The dynamic nature of this header helps to secure the application by preventing replay attacks and request tampering. (by Black Hills Information Security (BHIS), part of its PENTEST report for ISCP)

Service HMAC (SHMAC)

a special-purpose, flexible and lighter version of HMAC tokens, Service HMAC is used for securing callbacks (redirects/webhooks) from third-party services such as payment gateways, digital signature providers (DocuSign) etc., with a flexible signature format that allows for additional URL params and per-endpoint based delay in callbacks.

AuthCookie

A cookie based authentication scheme, AuthCookie is usually used for MVC web applications. Works along with user sessions. Together these give you out-of-the-box both short and long term sessions (depending on the selection of ‘remember me’) and sliding expiration.

The AuthCookie stores a proper auth token as value including authUrn. Thus you can use other types of identities such as special-purpose feature API keys etc. – to create cookie as you do with HMAC.

Service Key

A simple API key based authentication scheme, Service Key is best suited for integrating with third-party services (such as payment gateways) that do not provide capability to configure Service HMAC based dynamic callbacks.

Provides several options to guard against the vulnerabilities associated with using simple key based authentication including IP firewall, mandatory secure connection, restricted to only explicitly designated endpoints, works only with special purpose feature keys having only specific permits, etc.

Identities

In security parlance, identity represents a set of attributes by which a caller is definitively recognized and its permits (access privileges) are determined. User is the core identity in any multi-user systems. However, a user can also be represented by specialized identities such as API keys, user sessions, etc. Such specialized identities can further restrict what privileges are available for the currently executing request. Note: The concrete implementations of following identities can be found in source packages.

User Sessions

For real users to login with username and password. In addition to being a primary identity choice for AuthCookie scheme, works equally well as part of the HMAC scheme (acting like a temporary API key) – so API platforms can support browser based single-page applications (SPA) clients out-of-the-box.

Supports sliding expiration in both short and long lived sessions.
IP firewall is also enforceable in case you need it (say for high valued user accounts).

Site-to-site API Keys

For long-term access to protected data (back office or site-to-site integration). A site key lets you specify a permit group to define its privilege context; usually, site keys give access to most, if not all, operations permitted to the associated user/organization.

You can protect a site key with IP firewall (recommended) and by default it cannot be used from a browser client and is prohibited to be used with ServiceKey scheme given the highly sensitive nature of site keys.

Public API Keys

For anonymously or publicly (from browser clients) callable APIs requiring no secret credentials. Example: analytics or error logging APIs. Public keys help in identifying institutional clients (integrators) calling public APIs from their front-end systems, and prevents accidental cross-environment data leakage (such as non-production environment portals calling production APIs) with the help of origin white listing.

Feature API Keys

For short-term access to a limited set of sensitive data and operations usually for the end-users. For instance, in ISCP we leveraged this key type to create auth tokens that were only permitted to let users fund account with cash. When the system detects an account running low on cash, it fires an email with a link to the funding page. The customer can click on the link and is able to immediately fund the account without having to login because the linked URL also contains a FundAccount feature token.

You can protect a feature key with IP firewall (usually not required), it is allowed to be used from browser clients unlike site keys and is recommended to be used for ServiceKey scheme based integrations with limited permit. Leverage sliding expiration to support a session-like API key but with limited permits enough for the required operations and associated data.

Multi-Factor Authentication (MFA)

MFA adds another layer of security challenge (with a dynamic secret) to establish identity of the caller. The pipeline enforces MFA verification out-of-the-box as the second step. You can have MFA verification done once per session or have its own expiry based on the specified inactivity interval.

Multiple options to selectively disable MFA including on unsupported identities (such as API keys), for specific operations, for requests originating from white-listed networks (with no-personal-mobile-in-office policy), etc.

Option to enforce MFA on users which will then require them to enable MFA before continuing, and selectively opting-out designated users from such enforcements.

You get an end-to-end workflow for email-based Two-Factor auth as part of Premium MVC source packages. Support for API packages for the same is coming very soon. Multiple channels (SMS, call and TOTP) and multiple service providers (Twilio, Nexmo, etc.) support can also be provided on request as an optional package (will be made available generally in near future).

Activity-Based, Data-Aware Authorization (ADA)

ASK’s ADA is a unique access control mechanism that gives you granular and complete control on what operations (activities) a caller can execute and on what data it can execute those operations. It decouples operations from roles so administrators can manage permits at run-time instead of hard-wiring roles with code.

The ADA module comes with a convention-based approach to automatically discover operations (and determine their PermissionCodes) and sensitive data fields (resources) in each operation based on zero-trust security principle, and gives you several options to override these conventions either partially or completely, including writing a custom authorization logic for specific operations.

It is battle-tested in systems like ISCP and out-of-the-box handles challenges such as authorizing multiple data fields in an operation reliably and efficiently.

IP Firewall

Sensitive site-to-site API keys should always be protected with an IP firewall – a pre-defined set of one or more IP ranges – to restrict calls from only intended networks. The pipeline enforces IP firewall as a necessary check for all kinds of identities (except Public keys) which includes user sessions. This lets you even restrict high-valued user accounts (such as system administrators) to be only operable from secure corporate networks.

Of course, you can disable firewall for the entire system with one setting, or for specific types of identities, etc.

You get an end-to-end workflow for IP firewall management at user-level along with email notifications for events related to it, as part of the Premium MVC source packages (coming very soon for APIs additionally with APIKey firewall management).

User Verification

Apart from authentication and authorization, there’s one more additional check that is useful in most web applications and that is verification. If your registration process requires user to provide his email and/or phone number, you also require that user must verify that he actually owns that email or phone number before he could do anything useful with the system.

The pipeline enforces verification check as part of the authorization step. You can disable verification for the entire application or for the specific operations (so that certain APIs or pages become accessible to unverified users such as account settings).

You get an end-to-end workflow for email verification as part of Starter or higher source packages.

Suspension

Often business applications need capability to suspend users due to various reasons. Additionally, certain kinds of businesses (E.G. financial ones) require a capability to suspend other business entities like financial accounts while the associated users are still active. ASK provides capability to manage both kinds of suspensions integrated with the security pipeline.

User Suspension

The pipeline enforces user suspension check as part of the authentication step. You can disable the enforcement for the entire application or for the specific operations (so that certain APIs or pages become accessible to suspended users).

When you suspend users, all existing sessions are immediately marked as expired For immediate enforcement.

Premium source packages give you user management operations to suspend and activate users.

Entity Suspension

If you want to stop user temporarily from performing certain operations on certain data, you can use entity suspension feature. For example, KYC required, fraud detected, account inactive, etc. Entity suspension checks are performed as part of data authorization step and hence awareness of entity-hierarchy ensures that suspension is automatically applied on descendant entities, if any of the ancestors are found suspended during suspension check. For example, suspended account can prohibit changing related investment assets.

The pipeline lets you define allowed operations even during suspension of the given EntityId. Premium source packages give you complete logic to manage and utilize the exclusion rules, based on entity type, suspension reason, request verb, operation names and possession of permissions. This lets you define rules like below (assuming a financial account as the suspended entity):

  1. A rule to allow all get* operations on the suspended account to have read-only access.
  2. A rule to allow UploadDocument operation to investors on the suspended account so account holder can upload KYC docs.
  3. A rule to allow all kinds of operations on the suspended account if user possesses an admin permission.

Cross-Site Scripting (XSS) Protection

A successful Cross-site scripting (XSS) attack can cause the hacker to steal credentials and other valuable data of targeted users. Detecting XSS injection is available as a pre-execution step of the pipeline in all supported platforms.

We also provide a comprehensive guide with a real-world implementation examples to show various measures needed in your web application to holistically sanitize data across various subsystems (emails, APIs, back-end/front-end) to protect users against XSS.

Impersonation

Sometimes, support staff requires access to user’s login to help him troubleshoot a peculiar issue or assist in performing certain steps. Sharing credentials (passwords) is never an acceptable practice. Impersonation helps in such situations.

ASK supports two kinds of impersonation:

  1. Simple impersonation – Impersonate a user in the current session, and freely stop impersonation or change user being impersonated. This is especially useful for administrators for health checkups, monitoring and similar usage where the user being impersonated isn’t involved.
  2. Bound impersonation – Create a user session bound to only impersonate a particular user. Useful for support staff in assisting the customer as they can start a fresh parallel session (in a private/incognito window) impersonating the customer, without having to lose access to their admin interfaces. This way they can also serve multiple customers simultaneously if needed.

Impersonation in ASK also follows zero-trust security and you can indicate which operations are allowed during impersonation either by explicitly indicating every such operation or implicitly with a set of rules. The default rule configured for implicit method only allows GET operations (for read-only access), based on the least-privilege access principle.
In addition to matching allowed operations by HTTP verb and operation name, the implicit method lets you define different rules for different type of users by configuring such rules to require a corresponding permission.

Password Expiration

Password expiration is useful to force user to change password upon login. Setup new users with expired password or force existing user to change password by setting the password expiration. The authorization step enforces password expiration check – only operations you’ve explicitly allowed can be executed when the password expires.

Changing or resetting password automatically resets password expiration so user can continue with the business as usual.

Password Blocking

If user credentials are considered compromised, ASK lets you block user’s password along with specifying a reason of blocking. ASK also expires all active sessions as you block password.

The login attempt is subsequently denied for such an account. ASK then requires that user resets the password using the forgot password workflow.

Design Traits

To learn more about these features, you can also read introduction article.

Security Models Independence

Most security frameworks have this limitation that they restrict you with using their specific security models – representing user, permission, session and so on. Often, corresponding tables are also automatically created based on the models and you have no control of the schema.

ASPSecurityKit is designed to free you from this limitation – ASK components work on model interfaces instead (for example, IUser<TId>, IAuthDetails, IPermit<TId>). The models implementing these interfaces live in your application project, which gives you ultimate flexibility to declare the model the way you want, with desired validation and other attributes on properties, for example.

Database and data access technology agnostic

ASPSecurityKit does not impose a limitation to work with a specific database (E.G. Sql Server) or to use a particular data access technology (E.G. EntityFramework or NHibernate). Just as with models, ASK abstracts away the calls to the database using repository interfaces (IUserRepository<TId>, IIdentityRepository, IPermitRepository<TId, TEntityId>, for example), the implementations of which reside in your application code and can be modified to work with any database/data access technology.

Testable and extensible Design Based On Dependency Injection And Inheritance

Every component used in the security pipeline is interface based, and these interfaces are wired-up via a dependency framework of your choice. You can thus easily replace any component. The extensibility doesn’t end just there – the implementations of these interfaces declare their methods and properties as virtual so you can easily change behavior of any member without having to implement the whole component yourself. This DI based design additionally serves a crucial goal of testability in component design, which aids in seamless automated testing.

Async Execution

ASPSecurityKit has a first-class support for both synchronous and async executions, so you aren’t forced to choose a particular one just because the other isn’t supported.

Source Packages Features

In the following sections, we’ll briefly go through a list of all the Features/components available in the highest (Premium) source package. However, there are other packages (with lesser features) available including Essential (free with ASK license) and Starter. Additionally, these category of packages are available separately for both API-based or MVC-based projects, with obvious differences related to these different platforms (E.G., no UI is in any API source package).
For full details and feature-by-feature comparison between these source packages, you should visit the source packages page.

Implied Permissions

ASPSecurityKit also introduces a new concept called implied permissions, which is more flexible than roles and completely eliminates a need for having roles as a separate construct. You can grant a permission for one operation or a set (represented by a higher-level permission implying permissions of operations in the set), with the same permit management infrastructure.

Check out the permit management operations.

User Hierarchy

All the real-world systems observe some kind of user hierarchy. For example, you always like to have an admin user in addition to regular members so that you can manage the system. In moderately complex web applications, you have hierarchy of 3 or more levels. Like super admin > admins > managers > executives etc. ASK supports this feature out of the box and you explicitly define the parent user as you create a new user. Parent user can then delegate all or a subset of permissions to its subordinate users and control their activities.

Check out the user management operations.

Web Operations

  • An operation or activity is an action in ASP.NET Mvc/Web API/ASP.NET Core or a request DTO/service method in ServiceStack.
  • Every operation in MVC source packages includes an end-to-end implementation of its workflow – including models, repositories/managers, controllers and views along with both server and client-side (unobtrusive)validation logic as applicable.
  • Operations in API source packages follow restful services design and have all the components as in MVC source package, except the UI layer.

User Registration

Includes validating new user registration input (field validations and whether specified username already exists), creating a new user account, sending a verification email if user verification is enabled, setting locale (culture and timeZone) information inheriting from the appContext.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

User Login

Includes validating user login input (field validations), checks and returning appropriate errors in case of invalid credentials, account suspended and password blocked. Upon successful validation of credentials, a session object is created (supporting sliding expiration). In case of an MVC application, if user’s email isn’t verified and verification is enabled, user is redirected to the verify prompt page.

Two-Factor Authentication (2FA)

An end-to-end implementation of 2FA workflow is provided, with email as the default delivery method for the 2FA security code. The same can be easily augmented with other methods like phone (sms/call), or TOTP. Once user turns on 2FA, access to the aplication remains restricted using ASPSecurityKit’s MFA feature.

Includes multiple operations:

  • Operation to send/resend 2FA code on the configured provider (email as of now)
  • operation to verify the 2FA code.
  • 2FA settings flow is available as part of the account settings operations.

Learn more about it in a MVC source package, including screenshots.

Email Verification

Source packages are configured to treat username as user’s email. Thus user is required to verify it; otherwise, access to most of the application remains restricted using verification check.

Includes multiple operations:

  • operation to verify user based on a unique token sent via email as link.
  • Operation to resend the verification email.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Forgot Password

A full-fledged forgot -> reset password workflow that includes:

  • Operation to raise forgot password request which sends a unique token via email as link that has an expiration.
  • Operation to reset password via the reset token.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Account Settings

Includes multiple operations:

  • Operation to change password by providing valid existing password.
  • Operation to change username by providing valid existing password.
  • Operation to update basic user details such as name/culture/timeZone (as applicable). Extend it by adding your business specific profile fields.
  • Operation to update two-factor (2FA) details (turn email-based 2FA on/off at the moment). Deny turning off 2FA if it’s enforced as per system policy.
  • Operation to update IP firewall status with a check that user must add at least one IP network to the white-list before turning the firewall on.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Manage IP Firewall Networks White-List

IP firewal management is provided at user-level hence status is managed via an account settings interface.

Firewall network rules are associated with entityUrn rather than userId so you can reuse the same firewall management infrastructure for exposing firewall at other levels as done in SuperFinance bank firewall.

Includes:

  • Operation to add a new white-listed network rule – includes validating input (field validations), checks to prevent duplicate rule, adding the rule.
  • Operation to edit an existing rule – includes validating input (field validations), checks to prevent duplicate rule, updating the rule.
  • Operation to delete the specified rule – includes checking if the rule exists and reporting error if it doesn’t.
  • Operation to list rules for the specified entityUrn with support for paging parameters.

Learn more about it in a MVC source package, including screenshots.

User Management

Includes multiple operations:

  • Operation to add a new user – includes validating new user input (field validations and whether specified username already exists), creating a new user account, sending a verification email if email verification is enabled, setting culture and timeZone information inheriting from the current user.
  • Operation to delete the specified user – includes checking if the user exists, deleting dependent permit/permitGroup records, handle deletion error and reporting.
  • Operations to suspend/activate the specified user – includes checking if the user exists and reporting if not.
  • Operation to change password of the specified user – includes checking if the user exists and reporting if not.
  • Operations to list direct child or all descendant users with support for paging parameters.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Managing User Permits

Includes multiple operations:

  • Operation to grant a permit – includes validating new permit input (field validations), checks to prevent duplicate permit, granting the permit.
  • Operation to revoke the specified permit – includes checking if the permit exists and reporting error if it doesn’t.
  • Operation to list user permits with support for paging parameters.
  • Operation to list permit data for the parent user so as to use this data on UI to aid in granting permits. The data includes permissions, implied permissions, entities (ids and names).

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Adopt (Transfer) User

Administrative function. Provides an ability to change the parent of a user thereby resetting that user permissions as per the new parent. This is very crucial in organizations where employee hierarchy keeps changing due to promotion, attrition and hiring. Thus the system remains in sync with changes in organizational structure.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Impersonate User

Administrative function. Provides interface to impersonation library feature.

Includes multiple operations:

  • Operation to impersonate the specified user.
  • Operation to stop impersonation if it’s in progress.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Organize Permissions

Administrative function. Provides an ability to manage permissions and their implied permissions.

Includes multiple operations:

  • Operations to list/add/delete/update permissions.
  • Operations to list/add/delete/update implied permissions.

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

Security Event Notifications By Email

Email notifications to the user via email component for the following events:

Learn more about it in a MVC or an API source package, including screenshots (MVC) or rest request/response examples (API).

[todo - this feature is currently under implementation - coming soon]

Handling Errors Professionally

MVC

The requirements for a complete, professional custom error (401/403/404/500) handling in Mvc are:

  • Execute a specific Mvc error controller’s action for each error so that you can display error page with layout (header/footer) matching your site layout.
  • You should be able to re-use layout.cshtml (the master theme definition file) for error views so you don’t repeat yourself (DRY).
  • You should not redirect to a different, error specific page just to display the error. Redirecting is bad for SEO and you also lose the context.
  • You must be able to return corresponding http status code (404/500) for the error occurred. This is necessary for SEO so that search engine do not index your error pages.
  • Your error pages (Mvc actions) aren’t accessible directly (and you get 404 if you invoke their URL.).
  • If an Mvc action is invoked as a json request, return the error as a json response and not as html error page.
  • At all times, do not return sensitive information on non-development environments.

You get a full-fledged, custom error handling flow implementing all of the above requirements out of the box!

Page not found 404 error page
Unauthorized 403 error page
API

You get a catch-all exception handler (as per the API framework) that handles exceptions as described in OpException so as to not reveal sensitive information, for AuthFailedException, OpException, validation and any other exceptions treated appropriately. Supporting development mode in which exception details are revealed.

Exceptions are written as a proper json response object with errorCode, message and other details if applicable. Proper HTTP status code is also set on the response as per the exception.

400 Bad Request Response

{
    "ErrorCode": "AlreadyExists",
    "Message": "An account with this email is already registered.",
    "Errors": []
}

403 Unauthorized Response

{
    "ErrorCode": "AlreadyExists",
    "Message": "An account with this email is already registered.",
    "Errors": []
}

500 Internal Server Error Response

{
    "ErrorCode": "InternalServerError",
    "Message": "We're experiencing some difficulties at this time,. Please try again later.",
    "Errors": []
}

Localization

Support for storing and updating culture and timeZone information as part of user model. ASPSecurityKit provides a localization component to perform the date time conversions.

MVC

MVC only: You get an out-of-the-box support for customizing time zone and culture information (date formats) for every user. Includes razor editor/display templates and json.net dateTime converters to automatically manage localization for any rendering scenario.

API

The APIs should only deal with dateTime in UTC and the client applications are responsible to do the conversions for display purposes. The APIs do provide methods to store and retrieve locale details per user.

Notable Components

Data Access and Transfer

Under data access you get implementation sources of security and other models, Entity Framework migrations and repositories.

Dependency Injection

Since security components in ASPSecurityKit are based on interfaces, the DI portion of the source packages gives you a ready-to-use implementations of not only IContainer and IContainerBuilder, but also includes DI registrations of components in ASPSecurityKit and source packages such as managers, repositories etc.

The DI logic includes support for request scope over async operations in all source packages. The DI provided is based on a popular AutoFac framework and of course you can change to some other framework you prefer.

Authorization

Under this, you get:

Managers

Managers make up the intermediate business layer that contains the business logic required to perform most of the web operations. These accept validated POCO objects as input and return similar objects in response. Managers talk with database, email and other services – these can be easily reused in background jobs without having to load the request context which would be necessary for controllers, for example.
For more information, check out managers on the source packages page.

Email utility and templates

Includes sources for an email utility (supporting multiple popular email service providers), branded basic html templates for forgot password, email verification, and a template builder utility to build a customized email message using variables.

App Context

Provides general information for the application such as its title, default timezone/culture, administrator/support/bot email etc. Also sets up the superadmin user as well.

Route or Body Model Binding (.NET Core/Web API only)

In both Web API and .NETCore API, the default model binding can only bind an action parameter either from body or from URL (route values/queryString) but not from both. In case of json request (which is the default input content type these days for APIs), if you have a model that binds from the body but has a property or two that should be bound from URL (say rest parameters), you don’t have an out-of-the-box support available in both of these frameworks. But as part of the source package, you get a working implementation of such a binder!

Scripts (MVC only)

You get custom scripts including:

  • A plugin of jTable that extends it with features such as automatically embedding anti-request forgery token to jTable’s ajax calls, defining custom row buttons etc.
  • A plugin that extends unobtrusive validation plugin of ASP.NET to show errors as popups. This also exposes a global errorProvider with methods to show success/error messages using the same popup for uniformity.

For more information, check out scripts on the source packages page.

UI (MVC only)

Includes sources of:

  • Razor views for web operations, layout template (header/footer – menus displayed based on user permits and localization display/editor templates.
  • css and images for the chosen theme (right now only one theme is available).