Source Packages
About
ASPSecurityKit source packages are like libraries with fully functional components but installed as source code right in your project giving you crucial security components and web operations, commonly needed in all multi-user web applications, in a standard-compliant layered architecture. This doesn’t only get you started quickly with ASPSecurityKit, but also speeds up the development of your project as you can immediately start building the business features.
Whether you’re developing an MVC web application or an API service, ASPSecurityKit has a source package to get you started quickly.
Important note: The source code in all these packages is written in the CSharp (C#) programming language. Currently we don’t support any other programming language for source packages.
There are three grades of packages available in terms of included components and features, for each of the supported platforms:
1. Essential
An Essential source package gives you all the essential components required to get you started with ASPSecurityKit in a new or existing project including models, repositories, migrations, dependency injection. However, an Essential package doesn’t come with any commonly needed web operation and other functionalities such as graceful error handling etc. which are crucial if you’re developing a quality multi-user web application/service project. The Essential packages come as free-of-cost with all ASPSecurityKit plans. We highly recommend use of Essential package if you want to use ASPSecurityKit in an existing project – you can get started quickly introducing ASPSecurityKit gradually into the project.
2. Starter
In addition to components contained in Essential package, a starter source package gives you crucial web operations related to registration, login, forgot password, account settings along with error handling etc. The Starter packages come as free-of-cost with all ASPSecurityKit plans. You can use a Starter package if you’re developing a multi-user B2C web application/services for consumers (such as marketplaces) or you want to setup a quick prototype for a new idea without a need of user management and administration functionality.
3. Premium
A Premium source package contains all the web operations including two-factor authentication, IP firewall, user management, permit management, administration operations such as impersonation, adopt, features such as entity suspension, localization etc. It’s the highest grade and gives the complete features ASPSecurityKit has to offer as source. You should use a Premium package if users of your web application/services include businesses/enterprises. You get a Premium package included with all plans if you buy a license with three or more developers. Or, you can also buy a Premium package.
Trial
Additionally, trial source packages are also provided to let you evaluate ASPSecurityKit. However, being a trial package, a major portion of the source code is instead delivered as part of a demo binary (dll) assembly file.
Get Started
Visit getting started page for step-by-step walkthroughs.
Compare Packages
To learn more about a particular feature, click on the checked icon in the package cell. A feature may have additional components only for a particular package.
All Available Packages
Please choose a package above to see its features
Important Notes
- All features mentioned on this page for every source package (except for the trial ones) are installed as source code and hence you can freely extend/modify any functionality as needed.
- Term operation is used on this page to refer both action (ASP.NET) and request DTO (ServiceStack).
- For trial packages, a major portion of the source code is instead delivered as part of a demo binary (dll) assembly file.
Web Operations
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 email verification is enabled, setting culture and timeZone information inheriting from the appContext (if in package).
New users are created with parentId as null assuming that the registration creates a fresh root user (not an admin; just an independent user as on open membership based web applications).
Upon successful sign up, internal login flow is invoked and responded appropriately.
Request
curl -X POST "https://api-demo.ASPSecurityKit.net/sign-up"
-H "Content-Type: application/json"
-d "{\"name\":\"John Cook\",\"username\":\"[email protected]\",\"password\":\"p@ssw0rd\"}"
Response
{
"record": {
"sessionId": "56af80d984fa4f1dad1e352ff7e85213",
"secret": "ncGHa1U48O//ZXRzPsKdqaO4/mhFL5Ru60N2AzEnvD4=",
"verificationRequired": true,
"suspended": false,
"id": "0220f9af-7422-4260-98e5-898751d93863",
"name": "John Cook",
"username": "[email protected]",
"createdDate": "2020-11-05T10:11:52.5970999Z",
"timeZoneCode": "UTC",
"cultureCode": "en-US"
},
"succeeded": true
}
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 record is created.
In case of an MVC application, an authCookie is added to the response. If user’s email isn’t verified and verification feature is enabled, user is redirected to the verify page prompting user to verify.
Otherwise, if a returnUrl is specified, user is taken to that URL. If not, goes to the default user’s profile page.
In case of API, an object consisting of sessionId/secret of the newly created session along with other user details are returned.
Request
curl -X POST "https://api-demo.ASPSecurityKit.net/sign-in"
-H "Content-Type: application/json"
-d "{\"username\":\"[email protected]\",\"password\":\"p@ssw0rd\"}"
Response
{
"record": {
"sessionId": "56af80d984fa4f1dad1e352ff7e85213",
"secret": "ncGHa1U48O//ZXRzPsKdqaO4/mhFL5Ru60N2AzEnvD4=",
"verificationRequired": true,
"suspended": false,
"id": "0220f9af-7422-4260-98e5-898751d93863",
"name": "John Cook",
"username": "[email protected]",
"createdDate": "2020-11-05T10:11:52.5970999Z",
"timeZoneCode": "UTC",
"cultureCode": "en-US"
},
"succeeded": true
}
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:
- Operation to send/resend 2FA code on the configured provider (email as of now)
- operation to verify the 2FA code.
- checks such as 2FA already done or 2FA code is invalid and returning appropriate errors.
- 2FA settings flow is available as part of the account settings operations.
Send Two Factor Authentication Token Request
curl -X POST "https://api-demo.ASPSecurityKit.net/self/send-twofactor-authentication-token"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Resend Two Factor Authentication Token Request
curl -X POST "https://api-demo.ASPSecurityKit.net/self/send-twofactor-authentication-token"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"resendToken\":true}"
Response
{
"succeeded": true
}
Verify Two Factor Authentication Token Request
curl -X POST "https://api-demo.ASPSecurityKit.net/verify-twofactor-authentication-token"
-H "Content-Type: application/json"
-d "{\"token\":\"878473\"}"
Response
{
"succeeded": true
}
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 ASPSecurityKit’s verification feature.
Includes:
- operation to verify user based on a unique token sent via email as link.
- Operation to resend the verification email.
- checks such as user already verified or verification token is invalid and returning appropriate errors.
Resend Verification Email Request
curl -X POST "https://api-demo.ASPSecurityKit.net/self/verification-email"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Verify Request
curl -X POST "https://api-demo.ASPSecurityKit.net/verify"
-H "Content-Type: application/json"
-d "{\"token\":\"5d0498db-0c3d-4f51-bd8a-2ed7dc694bf6\"}"
Response
{
"succeeded": true
}
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.
- checks such as reset token is invalid/expired and returning appropriate errors.
- Intentionally ambiguous successful response to the forgot password request to protect it from miss-use to determine whether username exists.
Forgot Password Request
curl -X POST "https://api-demo.ASPSecurityKit.net/forgot-password"
-H "Content-Type: application/json"
-d "{\"username\":\"[email protected]\"}"
Response
{
"succeeded": true
}
Reset Password Request
curl -X POST "https://api-demo.ASPSecurityKit.net/reset-password"
-H "Content-Type: application/json"
-d "{\"token\":\"f80ec974-1376-4d52-9ef2-6a8593812884\",\"password\":\"p@ssw0rd\"}"
Response
{
"succeeded": true
}
Account Settings
Includes:
- 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).
- 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.
Change Username Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/self/username"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"username\":\"[email protected]\",\"password\":\"p@ssw0rd\"}"
Response
{
"succeeded": true
}
Change Password Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/self/password"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"oldPassword\":\"p@ssw0rd\",\"newPassword\":\"p@ssw0rd2020\"}"
Response
{
"succeeded": true
}
Update User Details Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/self/profile"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"name\":\"John Cook\",\"cultureCode\":\"en-US\",\"timeZoneId\":91}"
Response
{
"succeeded": true
}
Firewall Status Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/self/firewall-status"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"enabled\":true}"
Response
{
"succeeded": true
}
Two Factor Authentication Settings Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/self/twofactor-settings"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"enabled\":true}"
Response
{
"succeeded": true
}
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:
- For each operation in this feature, implicit authorization checks via ADA are performed to authorize whether current user is permitted to perform the specified operation and upon the specified ruleId or entityUrn (as applicable).
- 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.
Add IP Range Request
curl -X POST "https://api-demo.ASPSecurityKit.net/firewall"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"ipFrom\":\"127.0.0.1\",\"ipTo\":\"127.0.0.1\",\"name\":\"IPV4 Localhost\",\"entityUrn\":\"user:22a7f07c-3004-4528-ad95-0f82abc36823\"}"
Response
{
"record": {
"id": "344c8564-66c2-47c0-b391-dbed30e29cdc",
"ipFrom": "127.0.0.1",
"ipTo": "127.0.0.1",
"name":"IPV4 Localhost",
"entityUrn":"user:22a7f07c-3004-4528-ad95-0f82abc36823"
},
"succeeded": true
}
Update IP Range Request
curl -X PUT "https://api-demo.ASPSecurityKit.net/firewall/344c8564-66c2-47c0-b391-dbed30e29cdc"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"ipFrom\":\"136.12.1.1\",\"ipTo\":\"136.12.255.255\",\"name\":\"IPV4 Home Office\",\"entityUrn\":\"user:22a7f07c-3004-4528-ad95-0f82abc36823\"}"
Response
{
"record": {
"id": "344c8564-66c2-47c0-b391-dbed30e29cdc",
"ipFrom": "136.12.1.1",
"ipTo": "136.12.255.255",
"name":"IPV4 Home Office",
"entityUrn":"user:22a7f07c-3004-4528-ad95-0f82abc36823"
},
"succeeded": true
}
Delete IP Range Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/firewall/344c8564-66c2-47c0-b391-dbed30e29cdc"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Get IP Ranges Request
curl -X GET "https://api-demo.ASPSecurityKit.net/firewall?entityUrn=user:22a7f07c-3004-4528-ad95-0f82abc36823"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"id": "344c8564-66c2-47c0-b391-dbed30e29cdc",
"ipFrom": "136.12.1.1",
"ipTo": "136.12.255.255",
"name":"IPV4 Home Office",
"entityUrn":"user:22a7f07c-3004-4528-ad95-0f82abc36823"
}
],
"totalCount": 1,
"succeeded": true
}
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. You get this feature supported out of the box in which you 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.
User Management
Includes:
- For each operation in this feature, implicit authorization checks via ADA are performed to authorize whether current user is permitted to perform the specified operation and upon the specified userId (if provided).
- Operation to add a new user – includes validating new user input (field validations and whether specified username already exists), creating a new user account (with random expired password if password isn’t specified), sending a verification email if email verification is enabled, setting culture and timeZone information inheriting from the current user. New users are added with parentId as the current user’s id.
- 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.
- Operations to block password of 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.
Add New User Request
curl -X POST "https://api-demo.ASPSecurityKit.net/users"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"name\":\"Amit Kohli\",\"username\":\"[email protected]\",\"password\":\"p@ssw0rd\"}"
Response
{
"record": {
"id": "f2a57536-a483-4f36-9c08-b23195952acb",
"name": "Amit Kohli",
"username": "[email protected]",
"createdDate": "2020-11-05T10:07:28.69839",
"parentId": "6f3f2e97-6932-4c52-b4ef-18cf667722fa",
"suspended": false,
"timeZoneId": 91,
"cultureCode": "en-US"
},
"succeeded": true
}
Suspend User Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/suspend"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"suspended\":true,\"reason\":\"User is not active\"}"
Response
{
"succeeded": true
}
Set User Password Request
curl -X PATCH "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/password"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"password\":\"p@ssw0rd\"}"
Response
{
"succeeded": true
}
Delete User Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Direct Child Users Request
curl -X GET "https://api-demo.ASPSecurityKit.net/users?onlyChildren=true"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"id": "6f3f2e97-6932-4c52-b4ef-18cf667722fa",
"name": "John Cook",
"username": "[email protected]",
"createdDate": "2020-11-05T10:07:28.69839",
"suspended": false
}
],
"totalCount": 1,
"succeeded": true
}
All Descendant Users Request
curl -X GET "https://api-demo.ASPSecurityKit.net/users?onlyChildren=false"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"id": "88112283-b406-4511-ab28-780f7fa68a47",
"name": "Amily Wirth",
"username": "[email protected]",
"CreatedDate": "2020-11-03T16:57:38.9663104",
"suspended": false,
"parentName": "John Cook",
"parentId": "6f3f2e97-6932-4c52-b4ef-18cf667722fa"
},
{
"id": "fa222692-3131-4212-982a-dd243aba8191",
"name": "Amit Kohli",
"username": "[email protected]",
"createdDate": "2020-11-03T16:56:23.4528881",
"suspended": false,
"parentName": "John Cook",
"parentId": "6f3f2e97-6932-4c52-b4ef-18cf667722fa"
},
{
"id": "2eec34ab-a885-43b5-8750-d90d6c3ba77a",
"name": "Harry Kane",
"username": "[email protected]",
"createdDate": "2020-11-03T16:56:59.2590196",
"suspended": false,
"parentName": "John Cook",
"parentId": "6f3f2e97-6932-4c52-b4ef-18cf667722fa"
},
{
"id": "6f3f2e97-6932-4c52-b4ef-18cf667722fa",
"name": "John Cook",
"username": "[email protected]",
"createdDate": "2020-11-05T10:07:28.69839",
"suspended": false
}
],
"totalCount": 4,
"succeeded": true
}
Managing User Permits
Includes:
- For each operation in this feature, implicit authorization checks via ADA are performed to authorize whether current user is permitted to perform the specified operation and upon the specified UserPermitId/userId (if provided)
- 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).
Grant Permit Request
curl -X POST "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/permits"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"permissionCode\":\"AddUser\"}"
Response
{
"record": {
"id": "344c8564-66c2-47c0-b391-dbed30e29cdc",
"userPermitGroupId": "8348c9c9-b99f-4ea0-a5b1-2b24d271c60e",
"permissionCode": "AddUser"
},
"succeeded": true
}
Revoke Permit Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/permits/3553386d-f3e3-4312-8609-a570e6c26587"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Get User Permits Request
curl -X GET "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/permits"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"id": "344c8564-66c2-47c0-b391-dbed30e29cdc",
"userPermitGroupId": "8348c9c9-b99f-4ea0-a5b1-2b24d271c60e",
"permissionCode": "AddUser"
},
{
"id": "3553386d-f3e3-4312-8609-a570e6c26587",
"userPermitGroupId": "8348c9c9-b99f-4ea0-a5b1-2b24d271c60e",
"permissionCode": "Adopt"
},
{
"id": "e634636b-d5d0-4f35-a168-cc53782792fb",
"userPermitGroupId": "8348c9c9-b99f-4ea0-a5b1-2b24d271c60e",
"permissionCode": "Impersonate"
}
],
"totalCount": 3,
"succeeded": true
}
Get Permits Data Request
curl -X GET "https://api-demo.ASPSecurityKit.net/users/f2a57536-a483-4f36-9c08-b23195952acb/permit-data"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"userId": "fa222692-3131-4212-982a-dd243aba8191",
"userFullName": "Amit Kohli",
"entities": [
{
"id": "6f3f2e97-6932-4c52-b4ef-18cf667722fa",
"name": "John Cook",
"entityTypeCode": "ADMINUSER"
},
{
"id": "6f3f2e97-6932-4c52-b4ef-18cf667722fa",
"name": "John Cook",
"entityTypeCode": "USER"
},
{
"id": "88112283-b406-4511-ab28-780f7fa68a47",
"name": "Amily Wirth",
"entityTypeCode": "ADMINUSER"
},
{
"id": "88112283-b406-4511-ab28-780f7fa68a47",
"name": "Amily Wirth",
"entityTypeCode": "USER"
},
{
"id": "2eec34ab-a885-43b5-8750-d90d6c3ba77a",
"name": "Harry Kane",
"entityTypeCode": "ADMINUSER"
},
{
"id": "2eec34ab-a885-43b5-8750-d90d6c3ba77a",
"name": "Harry Kane",
"entityTypeCode": "USER"
},
{
"id": "fa222692-3131-4212-982a-dd243aba8191",
"name": "Amit Kohli",
"entityTypeCode": "ADMINUSER"
},
{
"id": "fa222692-3131-4212-982a-dd243aba8191",
"name": "Amit Kohli",
"entityTypeCode": "USER"
},
{
"id": "ffc6bf9a-a797-495b-a4f6-dd6b0a984862",
"name": "Administrator",
"entityTypeCode": "ADMINUSER"
},
{
"id": "ffc6bf9a-a797-495b-a4f6-dd6b0a984862",
"name": "Administrator",
"entityTypeCode": "USER"
}
],
"parentPermits": [
{
"permissionCode": "AddUser"
},
{
"permissionCode": "Adopt"
},
{
"permissionCode": "DrillDown"
},
{
"permissionCode": "Impersonate"
},
{
"permissionCode": "IndexAdmin"
},
{
"permissionCode": "OrganizePermissions"
},
{
"permissionCode": "RenderPermissions"
},
{
"permissionCode": "SuperAdmin"
}
],
"permissions": [
{
"permissionCode": "AddUser",
"entityTypeCode": "USER",
"kind": 0,
"description": "Add new users"
},
{
"permissionCode": "Adopt",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Change User parent"
},
{
"permissionCode": "DrillDown",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Drill Down Permissions"
},
{
"permissionCode": "Impersonate",
"entityTypeCode": "ADMINUSER",
"kind": 2,
"description": "Impersonate User"
},
{
"permissionCode": "IndexAdmin",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Access Admin Area"
},
{
"permissionCode": "OrganizePermissions",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Organize Permissions"
},
{
"permissionCode": "RenderPermissions",
"entityTypeCode": "ADMINUSER",
"kind": 2,
"description": "Render User's Permissions"
},
{
"permissionCode": "SuperAdmin",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Super administrator permission"
}
],
"impliedPermissions": [
{
"permissionCode": "Adopt",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "DrillDown",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "Impersonate",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "OrganizePermissions",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "RenderPermissions",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "AddUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "Adopt"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "DeleteUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "DrillDown"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "EditUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "Impersonate"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "IndexUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "ManageUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "OrganizePermissions"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "RenderPermissions"
}
],
"succeeded": true
}
Administration
The administrative operations let admins perform administrative, management and monitoring functions. All these operations are only permitted to [super admin] by default which can be delegated via grant permit operation.
For each operation in this feature, implicit authorization checks via ADA are performed to authorize whether current user is permitted to perform the specified operation and upon the specified EntityId (if provided)
Adopt (Transfer) User
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.
Includes validating adopt input (field validations and whether the child and adopter user exist), checks to disallow adoption of super admin, ancestor, self and reporting appropriate error if any of these checks fails.
Request
curl -X POST "https://api-demo.ASPSecurityKit.net/adopt"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"childUsername\":\"[email protected]\",\"adopterUsername\":\"[email protected]\"}"
Response
{
"succeeded": true
}
Impersonation
Provides interface to ASPSecurityKit’s impersonation feature. Includes
- Operation to impersonate the specified user.
- Operation to stop impersonation if it’s in progress.
Impersonation Request
curl -X POST "https://api-demo.ASPSecurityKit.net/impersonate"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"username\":\"[email protected]\"}"
Response
{
"record": {
"verificationRequired": true,
"suspended": false,
"id": "fa222692-3131-4212-982a-dd243aba8191",
"name": "Amit Kohli",
"username": "[email protected]",
"createdDate": "2020-11-03T16:56:23.4528881",
"timeZoneCode": "UTC",
"cultureCode": "en-US"
},
"succeeded": true
}
Stop Impersonation Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/impersonate"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Organize Permissions
Provides an ability to manage permissions and their implied permissions (an important unique concept explained here useful for managing permits).
Includes:
- Operations to list/add/delete/update permissions.
- Operations to list/add/delete/update implied permissions.
Get Permissions Request
curl -X GET "https://api-demo.ASPSecurityKit.net/permissions"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"permissionCode": "AddUser",
"entityTypeCode": "USER",
"kind": 0,
"description": "Add new users"
},
{
"permissionCode": "Adopt",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Change User parent"
},
{
"permissionCode": "DeleteUser",
"entityTypeCode": "USER",
"kind": 1,
"description": "Delete User"
},
{
"permissionCode": "DrillDown",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Drill Down Permissions"
},
{
"permissionCode": "EditUser",
"entityTypeCode": "USER",
"kind": 1,
"description": "Modify User – permissions/password/suspension"
},
{
"permissionCode": "Impersonate",
"entityTypeCode": "ADMINUSER",
"kind": 2,
"description": "Impersonate User"
},
{
"permissionCode": "IndexAdmin",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Access Admin Area"
},
{
"permissionCode": "IndexUser",
"entityTypeCode": "USER",
"kind": 1,
"description": "View User"
},
{
"permissionCode": "ManageUser",
"entityTypeCode": "USER",
"kind": 1,
"description": "Manage User"
},
{
"permissionCode": "OrganizePermissions",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Organize Permissions"
},
{
"permissionCode": "RenderPermissions",
"entityTypeCode": "ADMINUSER",
"kind": 2,
"description": "Render User's Permissions"
},
{
"permissionCode": "SuperAdmin",
"entityTypeCode": "ADMIN",
"kind": 0,
"description": "Super administrator permission"
}
],
"totalCount": 12,
"succeeded": true
}
Add Permission Request
curl -X POST "https://api-demo.ASPSecurityKit.net/permissions"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"permissionCode\":\"ManageUser\",\"entityTypeCode\":\"USER\",\"kind\":0,\"description\":\"Manage User\"}"
Response
{
"record": {
"permissionCode": "ManageUser",
"entityTypeCode": "USER",
"kind": 0,
"description": "Manage User"
},
"succeeded": true
}
Edit Permission Request
curl -X PUT "https://api-demo.ASPSecurityKit.net/permissions/ManageUser"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"entityTypeCode\":\"USER\",\"kind\":0,\"description\":\"Manage User Info\"}"
Response
{
"record": {
"permissionCode": "ManageUser",
"entityTypeCode": "USER",
"kind": 0,
"description": "Manage User Info"
},
"succeeded": true
}
Delete Permission Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/permissions/ManageUser"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"succeeded": true
}
Get Implied Permissions Request
curl -X GET "https://api-demo.ASPSecurityKit.net/implied-permissions"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
Response
{
"records": [
{
"permissionCode": "Adopt",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "DrillDown",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "Impersonate",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "OrganizePermissions",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "RenderPermissions",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "AddUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "Adopt"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "DeleteUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "DrillDown"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "EditUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "Impersonate"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "IndexAdmin"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "IndexUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "ManageUser"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "OrganizePermissions"
},
{
"permissionCode": "SuperAdmin",
"impliedPermissionCode": "RenderPermissions"
}
],
"totalCount": 16,
"succeeded": true
}
Add Implied Permission Request
curl -X POST "https://api-demo.ASPSecurityKit.net/implied-permissions"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"permissionCode\":\"ManageUser\",\"impliedPermissionCode\":\"EditUser\"}"
Response
{
"record": {
"permissionCode": "ManageUser",
"impliedPermissionCode": "EditUser"
},
"succeeded": true
}
Delete Implied Permission Request
curl -X DELETE "https://api-demo.ASPSecurityKit.net/implied-permissions"
-H "Authorization: ask-hmac $HMAC_SIGNATURE"
-H "Content-Type: application/json"
-d "{\"permissionCode\":\"ManageUser\",\"impliedPermissionCode\":\"EditUser\"}"
Response
{
"succeeded": true
}
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.
Entity Suspension
Entity suspension lets you implement a rules-based suspension on any arbitrary entity in your domain model, which would then allow only a particular set of operations on the suspended entity, and that too depending on the reason of suspension and possession of a permission that you specify as part of the exclusion rules.
As part of this feature, you get implementation of ISuspensionService, data models and their migrations for exclusion rule and suspended entity.
Graceful handling of unhandled exceptions and Custom error views
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! (Also, have a look at response utilities.)
Graceful handling of unhandled exceptions
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. (Also, have a look at response utilities.)
400 Bad Request Response
{
"succeeded": false,
"errorDetail": {
"errorCode": "AlreadyExists",
"message": "An account with this email is already registered.",
"errors": []
}
}
403 Unauthorized Response
{
"succeeded": false,
"errorDetail": {
"errorCode": "Unauthorized",
"message": "You do not possess a permission to execute this API.",
"errors": null
}
}
500 Internal Server Error Response
{
"succeeded": false,
"errorDetail": {
"errorCode": "InternalServerError",
"message": "We're experiencing some difficulties at this time,. Please try again later.",
"errors": null
}
}
Response utilities
Special response types to return single record, list (with pagination) and error responses as JSON in a consistent manner.
return Json(ApiResponse.List(result.ThisPage, result.Total));
return Json(ApiResponse.Single(mapper.Map<Contact>(entity)));
return Json(ApiResponse.Success());
return Json(ApiResponse.Error(Messages.CannotAddDuplicateRecord));
Base controllers that provide:
- Short and quick redirect routines with ability to post success or failure messages on the page redirected to
return RedirectWithMessage("Verify", Messages.AccountVerificationFailed, OpResult.SomeError);
...
return RedirectWithMessage("Index", Messages.AccountVerifiedSuccessfully, OpResult.Success);
...
if (QueryStringContains("verificationRequired"))
{
SetMessage(Messages.VerifyYourEmailNow, OpResult.Success);
}
return View();
- A secure and proper way to respond to JSON requests – including responding properly for unhandled errors, business rule failures and model validation.
return await SecureJsonAction(async () =>
{
if (ModelState.IsValid)
{
....
}
throw new OpException(OpResult.InvalidInput);
});
...
return await SecureJsonAction(async () =>
{
var entity = await this.dbContext.Interactions.FindAsync(id);
if (entity == null)
throw new OpException(OpResult.DoNotExist, "Interaction not found.");
...
});
Special response types to return single record, multiple records with pagination, identifiers, empty success and error responses (with field-level details) as JSON in a consistent manner.
return BaseResponse .Page(result.ThisPage, result.Total);
return BaseResponse.Single(mapper.Map<Contact>(entity));
return BaseResponse.Success();
return BaseResponse.Error(OpResult.InvalidInput, Messages.CannotAddDuplicateRecord);
return BaseResponse.Id(entity.Id);
Base controller that provides Ok and Error routines leveraging BaseResponse types mentioned above for ModelState validation errors/business rule failures/paging/single record/etc. response scenarios
return Ok();
return Ok(mapper.Map<Contact>(entity));
return Ok(result.ThisPage, result.Total);
// Captures the validation errors in ModelState to return them as proper json.
return Error();
return Error(OpResult.DoNotExist, "Contact not found.");
Base service that provides Ok and Error routines leveraging BaseResponse types mentioned above for business rule failures/paging/single record/etc. response scenarios
return Ok();
return Ok(mapper.Map<Contact>(entity));
return Ok(result.ThisPage, result.Total);
return Error(OpResult.DoNotExist, "Contact not found.");
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.
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.
The APIs should only deal with dateTime in UTC and the client applications are responsible to do the conversions for display purposes.
Authorization Components
Under this, you get:
- Completing implementation of ReferencesProviderBase<TIdMemberReference,TIdReference> and related types, including implementation of multiple loader methods for EntityIds such as UserPermitId, UserPermitsId and Username, as explained in obtaining related references.
- AuthDefinition types including for grant permit (if the feature is in package).
Validators
For each applicable web operation, you get a fluent validator type to validate request input.
Route or Body Model Binding
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!
Data Access and Transfer
Under data access you get sources of security models, Entity Framework migrations and repositories.
You can freely extend models by adding more properties, dictating the validation logic and controlling exactly how the corresponding tables are created in the data storage of your choice.
The corresponding Sql Server database can be created within seconds by executing EF migrations.
Finally, repositories provide the data access logic for security models to ASPSecurityKit components.
So as you can see, the entire data representation and access stack lives as source files in your project and you can modify them to fit to your preferred data access and data storage technologies.
Models
Includes sources of:
- EntityFramework code first POCO Data models (with validation) for such security entities as IUser<TId>, IPermit<TId>, Permission, ImpliedPermission, session, TimeZone/Culture, etc. as well as DbContext.
- View models/DTOs for included web operations.
Migrations and T-Sql Scripts
Includes sources of:
- EF migrations for code first models part of the package.
- T-SQL scripts consisting of stored procedures, functions and triggers implemented for certain features such as for loading user permits for login, parent user’s permit data for permit management, revoking orphaned permits when user is adopted, implying all new permissions to [super admin] and so on.
After installation, by executing update-database command in Package Manager Console, you immediately have a full-fledged Sql Server database ready to support storage needs of ASPSecurityKit features.
Repositories
Includes source implementations of repositories required by ASPSecurityKit components.
| Repository | Description |
|---|---|
| IdentityRepository | Implements IIdentityRepository required for data operations related to auth tokens and session. |
| PermitRepository | Implements IPermitRepository<TId, TEntityId> required for data operations related to permit object. |
| UserRepository | Implements IUserRepository<TId> required for data operations related to user object. |
Dependency Injection
Since security components in ASPSecurityKit are based on interfaces to realize a fundamental design goal of extensibility, 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.
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 (or ServiceStack services).
Difference between repositories and managers: while repositories represent data operations – these are only concerned dealing with the database (moving data in and out), managers represent business operations each of which may involve multiple database operations as well as communication with other services such as sending emails etc.
Includes sources of:
| Manager | Description |
|---|---|
| LocaleManager | For loading timeZone and culture data. |
| PermissionConfigurationManager | Implements logic related to organize permissions. |
| PermitManager | Implements logic related to permit management. |
| UserManager | Implements logic for operations related to user account. |
Scripts
UI for web operations like user management, permit management and organize permissions utilize jTable to implement grid interfaces. The library itself is installed as a NuGet package. Additionally, you get an extension script (jquery.jtable.ask.js) which extends jTable to implement features we found necessary such as specifying anti-request forgery token to embed automatically in jTable’s json calls, adding custom row buttons etc.
There’s also a jquery.validate.unobtrusive.plugin.js script implemented to extend 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.
Lastly, there’s a permission.js script that implements complex javascript logic to handle permission and implied permission flow for organize permissions and permit management UIs.
Email utility and templates
Includes sources for:
- An email utility supporting multiple popular email service providers (MailGun/SendGrid/Gmail/Yahoo/Hotmail) – specify username and password for the mail provider of your choice in the configuration file (web.config/appsettings.json) and get the utility up and running. You can also configure any other SMTP based service including Amazon SES by additionally specifying the SMTP host and other details in the configuration.
- Branded basic html templates for forgot password, email verification.
- A template builder utility that can inject values for placeholders within the email template to build a customized message.
- The builder sanitizes the dynamic content before injection to protect against cross-site scripting (XSS).
Since the entire templating and mailing code comes as source files, you can extend it to more providers and customize it as per your needs.
UI
Includes sources of:
- Razor views for web operations, layout template (header/footer – menus displayed based on user permits and localization display/editor templates (if in package).
- css and images for the chosen theme (right now only one theme is available).
Other Types
Including but not limited to:
- AppContext: Provides general information for the application such as its title, default timezone/culture, administrator/support/bot email etc. The AppService sets up the superadmin user as well.
- ASPSecurityKitConfiguration: Encapsulates web-framework specific configuration logic executed on startup including but not limited to initializing ASPSecurityKit and your project DI, security settings, middlewares (such as exception handler/CachedAuthSessionProvider), licensing etc.
- CachedAuthSessionProvider: Extends AuthSessionProvider to add caching capability required for sessions. The DI is by default configured to use InMemoryCacheClient but you can implement an external cache client easily.
- Config: Implements IConfig required by ASK libraries for reading config values (as in SecuritySettings).
- Logger: Implements ILogger required by ASK libraries for logging diagnostic information. It just writes to Trace class; You should modify it to work with your preferred logging framework.