Features

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.

• Libraries: Provide a comprehensive Security Pipeline to enforce identity and access rules on web requests. These are installed as NuGet Packages.
• Source Packages: Provide end-to-end implementation (models, controllers, services, UIs) of functionality – such as account management (register/login/account settings, account recovery and verification), two-factor authentication, IP firewall, user management, administration, security event notifications – that every multi-user project needs, in a standard-compliant source code that installs right into your project. To help you jump straight into developing the business features of the project. Available for all supported platforms – for both API and MVC web applications.

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.

Following the assume breach by default tenet of the Zero Trust approach, all the security checks are enforced by default and you explicitly opt out certain checks from one or more operations as needed.

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.

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.

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 the first 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 follows the least privilege access tenet of the Zero Trust model wherein only GET operations (for read-only access) are permitted by default.

You can override the default rule and indicate which operations are allowed during impersonation either by explicitly indicating every such operation or implicitly with a set of rules.

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.

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 an MVC, a Web API or a ServiceStack 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.

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

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 an MVC, a Web API or a ServiceStack source package, including screenshots (MVC) or rest request/response examples (API).

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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack source package, including screenshots (MVC) or rest request/response examples (API).

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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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 an MVC, a Web API or a ServiceStack 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:

• When user’s password is changed by the admin.
• When user herself changes username.
• When user herself changes password.
• When user disables 2FA.
• When user turns off IP firewall.
• When user changes IP firewall white-list.
• When user resets password via forgot password workflow.
• When access is denied by the IP firewall.

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

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!

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

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

{
    "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.

Notable Components