Key Concepts

Permission, permit and permit group

A permission is a security entity consisting of a PermissionCode which is the unique key for the permissions set, EntityTypeCode which specifies the type of entity this permission can be granted against (the EntityId), and Kind which specifies whether it can be used for a general, instance or both kinds of permits. A permission is likely to be logically associated with one or more operations to represent such operations in the access control management (authorization).

A permit is a security entity that associates a user with a permission. It also consists of an EntityId which tells on which data the permission has been granted to the user. Depending upon whether or not EntityId has a value, there are two kinds of permits:

1. General (EntityId is null): a general permit grants the permission without any restriction of the data. The null EntityId value is interpreted as ‘all’ and therefore, it’s the most privileged way of granting a permit, which should be restricted to only admins, or operations that do not operate on sensitive existing data such as create operations related to master entities.
2. Instance (EntityId has a value): An instance permit grants the permission only on the specified data. If user tries to perform the associated operation with EntityId other than the permit specifies, the authorization fails.

A permitGroup represents a collection of permits and is associated with a user or some security identity. Permit groups make It possible to create special-purpose permit sets for such things as API keys. There are two kinds of permit groups:

1. Primary – A primary group should be a superset of all the permits available to the user. Thus there should be only one primary permit group per user.
2. Auxiliary – An auxiliary group represents an arbitrary subset of permits such as for feature keys.

You get implementation of these types as EntityFramework data models along with repositories and T-SQL procedures to manage data for them in all ASPSecurityKit’s source packages.

Read the guide on activity-based, data-aware authorization to learn more about these concepts.

EntityId and EntityURN

EntityId is referred to the key column or attribute of a table or entity that uniquely identifies a record amongst the entire set. It can also be used to indicate a unique value of such a column. In RDBMS like SQL databases, columns representing primary or unique keys of tables are examples of EntityIds

AN EntityURN (Uniform Resource Name) encodes both the name of an entity (entity type) and a particular EntityId value (entity instance) as a string value. For example, ‘account:cf2d27fg-12cf’. Here ‘cf2d27fg-12cf’ is an EntityId (a particular account record key/identifier) and ‘account’ is the name of the entity or table the key belongs to.

While EntityId uniquely identifies a record within a table, Entity URNs help in creating a universal unique EntityId or key across all tables within a database. EntityURNS are especially helpful in representing the EntityId value in permits, because different permits can be granted on records belonging to different type of entities.

Operation

An operation is an action in ASP.NET Mvc/Web API/ASP.NET Core or a request DTO/service method in ServiceStack.

Identity and identity token

In security parlance, identity represents a set of attributes by which a caller is definitively recognized and it’s permits (access privileges) are determined. User is the core identity in any multi-user system. 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.

An identity token is just the key value that distinctly represents an identity record amongst many. For example, UserId, UserSessionId, APIKeyId.

An identity token type specifies the type of the identity the token represents. ASPSecurityKit supports both APIKey and UserSession identity types and it’s easy to add support for others.

IAuthDetails is a common interface to represent identity details related to any token.

API key

There are three types of recognized API keys represented by the KeyType enumeration (you can add support for more if needed):

Site key

Site keys are for long-term access to protected data (back office or site-to-site integration). Site keys should have a permit group that determines the permits associated with that key. Usually, site keys give access to most, if not all, operations permitted to the associated user/organization.

Feature key

Feature keys are 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 accounts 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.

Public key

Public keys are 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). As stated in the security pipeline article, public API keys can only be used to access operations marked as RequestFeature.Public.

User session

A user session object represents a temporary identity that’s created when the user logs in with credentials (username and password). The identity is valid until the user logs out or it’s auto-expired. ASPSecurityKit supports sliding expiration and both short and long term expirations for sessions. You get a full implementation out-of-the-box in source packages.

AuthUrn

An AuthUrn represents an identity URN – the type of the identity and its key (identity token) – in the format identityTokenType:identityToken (or simply type:key). The IdentityTokenType class provides methods to build and inspect URNs.

Auth token

An auth token represents the complete value sent for the authentication scheme. It can consist of authUrn, signature, timestamp etc. We can use just the term ‘token’ when used in conjunction with the name of token types – such as HMAC token – or when referring to such a specific token.

Authentication scheme

An authentication scheme represents the protocol that identifies the type of token being used to authenticate. While we may use both the terms – scheme and token – interchangeably, but ‘scheme’ mostly represents the type of the auth token while auth token represents its value (the actual token string).

Sliding expiration

Sliding expiration is the process of extending the expiration of an identity automatically usually every time a request is made using the associated identity token. AuthSessionProvider makes call to SlideExpiration which slides expiration on the identity if applicable. You get a full implementation of the required logic out-of-the-box in models and repositories in all source packages.

Sliding expiration isn’t limited to sessions – it’s perfectly fine and supported without any change to have API key supports sliding expiration. At the end of the day, these are just different identity tokens represented by authUrn and the IIdentityRepository implementation in your project decides about what are the features supported by a specific identity type.