UserService<TId,TEntityId,TUser>

Members

Namespace: ASPSecurityKit
Assembly: ASPSecurityKit.dll

Summary

Implements IUserService<TId,TEntityId,TUser> and provides logic for authenticating, authorizing and managing user identities to consuming application.

Generic Types
Name Description
TId The type of key identifier used in the application.
TEntityId The type of entityId property for IPermit<TId>.
TUser The concrete type of the user model that implements IUser<TId>.

Constructors

#ctor(session,userRepository,permitRepository,identityRepository,permitManager,hashService,settings,logger)

Summary

Initializes a new instance of the UserService<TId,TEntityId,TUser> class.

Parameters
Name Type Description
session ASPSecurityKit.ISessionService An implementation of ISessionService that provides session management capability.
userRepository ASPSecurityKit.IUserRepository<TId> An implementation of IUserRepository<TId> that provides CRUD capability for user models against a persistent data store.
permitRepository ASPSecurityKit.IPermitRepository<TId,TEntityId> An implementation of IPermitRepository<TId,TEntityId> that provides CRUD capability for permit models against a persistent data store.
identityRepository ASPSecurityKit.IIdentityRepository An implementation of IIdentityRepository that provides CRUD capability for identity tokens against a persistent data store.
permitManager ASPSecurityKit.IPermitManager<TId> An implementation of IPermitManager<TId> to manage permission set.
hashService ASPSecurityKit.IHashService An implementation of IHashService for password hashing.
settings ASPSecurityKit.ISecuritySettings An instance of SecuritySettings.
logger ASPSecurityKit.ILogger An implementation of ILogger to log diagnostic information.

Properties

HashService

Summary

Gets the hash service for password hashing.

Value

The hash service for password hashing.

PermitManager

Summary

Gets the permit manager.

Value

The permit manager.

Session

Summary

Gets the session service.

Value

The session service.

Logger

Summary

Gets the logger.

Value

The logger.

UserRepository

Summary

Gets the user repository.

Value

The user repository.

PermitRepository

Summary

Gets the permit repository.

Value

The permit repository.

IdentityRepository

Summary

Gets the identity repository.

Value

The identity repository.

Settings

Summary

Gets the Security settings.

Value

The Security settings.

AuthUrn

Summary

Gets or sets the token urn for the current identity.

Value

The token urn for the current identity.

PermitGroupId

Summary

Gets or sets the permit group identifier representing the permits granted to the current identity. Null indicates all permits related to the user are to be loaded instead.

Value

The permit group identifier representing the permits granted to the current identity. null indicates that all permits related to the user are to be loaded instead.

IsBoundImpersonatedSession

Summary

Gets or sets a value indicating whether the current user session is a bound impersonated session.

Value

true if the current user session is a bound impersonated session; otherwise, false.

RecentAccessWithMFAAt

Summary

Gets or sets the latest recorded time a request verified with multi-factor was made on the current session. Null in cases it isn’t required/supported.

Value

The latest recorded time a request verified with multi-factor was made on the current session. null in cases it isn’t required/supported.

MFAValidUntilSessionExpired

Summary

Gets or sets a value indicating whether multi-factor verification is valid for the duration of the associated session.

Value

true if multi-factor verification is valid for the duration of the associated session; otherwise, false.

CurrentUser

Summary

Gets the TUser model for the current user.

Value

The TUser model for the current user.

CurrentUserId

Summary

Gets the current user id.

Value

The current user id.

CurrentUsername

Summary

Gets the username of the current user.

Value

The username of the current user.

CurrentUserFullName

Summary

Gets the full name of the current user.

Value

The full name of the current user.

IsAuthenticated

Summary

Gets a value indicating whether current user is authenticated.

Value

true if current user is authenticated; otherwise, false.

Remarks

The default implementation returns true if CurrentUser isn’t null and permits have been initialized; otherwise, false. Override it to change behavior.

IsImpersonating

Summary

Gets a value indicating whether current user is an impersonation.

Value

true if current user is an impersonation; otherwise, false.

ImpersonatingUser

Summary

Gets the TUser model for the user who is impersonating CurrentUser.

Value

The TUser model for the user who is impersonating CurrentUser.

IsVerified

Summary

Gets a value indicating whether current user is verified.

Value

true if current user is verified; otherwise, false.

HasPasswordExpired

Summary

Gets a value indicating whether password of current user has expired.

Value

true if password of current user has expired; otherwise, false.

Methods

IsMFAEnforcedOnUser(auth)

Summary

Determines whether or not multi factor authentication is to be enforced on user.

Returns

true if multi factor authentication is to be enforced on user; otherwise, false.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails Optional. The identity token details object associated with the current user.
Remarks

Current implementation returns true if MFANotRequired is false and MFAEnforced returns true.

IsMFAVerified()

Summary

Gets a value indicating if user is marked verified with MFA for this session. See remarks for more details.

Returns

true if user is marked verified with MFA for this session; otherwise, false.

Parameters

This method has no parameters.

Remarks

MFA verification can be valid either for the lifetime of the session (you should provide a checkbox for users to indicate that on the MFA prompt) or it’s only valid for specified duration (say 30 minutes which is default). This validity interval is based on slid expiration which simply means it’s calculated as a difference between last activity recorded time and now. The said time isn’t updated until at least one minute has passed after the last update so as to avoid database call on every request. This method calls SetMFAVerified to update RecentAccessWithMFAAt. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. Use SetMFAVerified for this purpose.

SetMFAVerified()

Summary

Marks user as verified for MFA for the current session. It calls SetMFAVerified with validUntilSessionExpired argument as null.

Parameters

This method has no parameters.

SetMFAVerified(validUntilSessionExpired)

Summary

Marks user as verified for MFA for the current session. Optionally if validUntilSessionExpired is true, the MFA verification is considered valid as long as the associated session is valid. Otherwise, the verification will be subject to a validity as defined by MFAAliveForMinutes.

Parameters
Name Type Description
validUntilSessionExpired System.Nullable<Boolean> Indicates if MFA verification is valid for the lifetime of the associated session. If you just pass null it would just slide MFA verification validity.
Exceptions
Type Description
System.InvalidOperationException When either not authenticated or authUrn is empty.
Remarks

Call this method from actions that verify MFA. After that to slide expiration you should rather use IsMFAVerified. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. This method helps in saving them.

ChangePassword(username,currentPassword,newPassword)

Summary

Changes password for a user that has the specified username.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the username is not valid.)

Parameters
Name Type Description
username System.String A valid username.
currentPassword System.String The current password.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When username/current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePassword(userId,currentPassword,newPassword)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
currentPassword System.String The current password.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePasswordInternal(currentPassword,newPassword,userId,username)

Summary

Changes the password for the user identified by either userId or username.

Returns

true if the password changed successfully; otherwise, false.

Parameters
Name Type Description
currentPassword System.String The current password.
newPassword System.String The new password.
userId System.Nullable<TId> The user identifier.
username System.String The username.

ChangePassword(userId,newPassword)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
newPassword System.String The new password.
Exceptions
Type Description
System.InvalidOperationException When parameter userId is the same as CurrentUserId. |
System.ArgumentNullException When userId is null or default, or new password is null or whitespace.
Remarks

Use this method for admins/managers to allow them to reset password for their subordinates without needing to verify their existing password. A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user.

ChangeUsername(username,password,newUsername)

Summary

Changes username of a user that has the specified username.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
username System.String The current username that needs to be changed.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
Exceptions
Type Description
System.ArgumentNullException When username,password or newUsername is null or whitespace.

ChangeUsername(userId,password,newUsername)

Summary

Changes username of a user that has the specified id.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
userId TId A valid user identifier.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or password or newUsername is null or whitespace.

SetSuspensionStatus(userId,suspended,reason)

Summary

Sets the suspension status of a user.

Returns

true if suspension status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose suspension status is to be updated.
suspended System.Boolean Specifies suspension status . True means user is suspended while false means user is activated.
reason System.String Optional. Reason of suspension.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates Suspended with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets SuspensionReason and SuspensionDate. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user so as to enforce suspension immediately.

SetPasswordBlocked(userId,passwordBlocked,reason)

Summary

Sets the passwordBlocked status of a user.

Returns

true if passwordBlocked status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose passwordBlocked status is to be updated.
passwordBlocked System.Boolean Specifies passwordBlocked status .
reason System.String Reason of blocking password.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates PasswordBlocked with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets PasswordBlockedReason and PasswordBlockedDate.

Impersonate(username)

Summary

Impersonates a user that has the specified username. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
username System.String The username to impersonate.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When Username doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

Impersonate(userId)

Summary

Impersonates a user that has the specified userId. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
userId TId A valid user identifier.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When UserId doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

StopImpersonating()

Summary

Stops the impersonation if it is active and loads the original user details who logged in for this session.

Parameters

This method has no parameters.

Exceptions
Type Description
System.InvalidOperationException When the current session is a bound impersonated session (initialized with ImpersonatedUserId). |

ImpersonateInternal(username,userId)

Summary

Impersonates the user identified by either userId or username.

Parameters
Name Type Description
username System.String The username.
userId System.Nullable<TId> The user identifier.
Exceptions
Type Description
System.InvalidOperationException When user to impersonate couldn’t be loaded.

GetStorageData()

Summary

Gets the data in session related to the current identity.

Returns

The data in session related to the current identity.

Parameters

This method has no parameters.

Remarks

Override this method and return any other data you’ve added directly onto the ISessionService for the current user. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or SetStorageData as it’d be automatically managed.

SetStorageData(details)

Summary

Overrides the existing data in session related to the current identity.

Parameters
Name Type Description
details ASPSecurityKit.UserServiceSessionDetails<TId, TUser> Object containing session data to override.
Exceptions
Type Description
System.ArgumentNullException When details is null.
Remarks

Override this method and set any other data you’ve captured previously with GetStorageData. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or GetStorageData as it’d be automatically managed.

VerifyAccount(token)

Summary

Sets Verified to true for the user that has the specified token.

Returns

true if a user with the token is found and verification status updated successfully. otherwise false.

Parameters
Name Type Description
token System.String A valid verification token generated during registration for example.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

NewUser(username,password,name)

Summary

creates a new user model instance.

Returns

A new user model instance.

Parameters
Name Type Description
username System.String The login username; must be unique.
password System.String The password.
name System.String The name of the user.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Use this method in conjunction with CreateAccount during sign up/add new user process. First call this method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

CreateAccount(model)

Summary

Completes the new user registration process.

Returns

true if user model is saved successfully; otherwise false.

Parameters
Name Type Description
model TUser The user model.
Exceptions
Type Description
System.ArgumentNullException When model is null.
Remarks

Use this method in conjunction with NewUser during sign up/add new user process. First call NewUser method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

GeneratePasswordResetToken(username)

Summary

Generates the password reset token for the specified username.

Returns

If a user with the specified username exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GeneratePasswordResetToken(userId)

Summary

Generates the password reset token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GenerateVerificationToken(username,resetVerification)

Summary

Generates the verification token for the specified username.

Returns

If a user with the specified username exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GenerateVerificationToken(userId,resetVerification)

Summary

Generates the verification token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GenerateVerificationTokenInternal(username,userId,resetVerification)

Summary

Generates the verification token for the user identified by either userId or username.

Returns

The generated token or null if user not found.

Parameters
Name Type Description
username System.String The username.
userId System.Nullable<TId> The user identifier.
resetVerification System.Boolean Indicates whether to reset the user’s verification status to false.

IsPasswordResetTokenValid(token)

Summary

Determines whether specified token exists and is valid for password reset.

Returns

true if specified token exists and is valid for password reset; otherwise, false.

Parameters
Name Type Description
token System.String The token previously generated by calling GeneratePasswordResetToken.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

Login(username,password,persist,letSuspended)

Summary

Authenticates the user; if successful, creates an appropriate mechanism (cookie or otherwise) for long-term session if persistence is specified. Additionally, if Suspended is true, you can specify whether or not to allow suspended user to login.

Returns

Success if login was successful; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
persist System.Boolean If set to true a long-lived persistent session is to be created with expiration value as returned by RememberMeTimeoutInMinutes; otherwise, a limited duration session is to be created.
letSuspended System.Boolean If set to true a suspended user is permitted to login; otherwise login is denied.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Login may fail for many reasons. However, you must show a generic message in most cases for security reasons. The returned value of type OpResult contains the exact reason of login failure. Possible reasons are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : User’s credentials were successfully validated; however, user is suspended and suspended users are not allowed to login. You can set letSuspended to true to let suspended user login.

  • PasswordBlocked : User’s credentials were successfully validated; however, user’s password is marked as blocked. Therefore, login is denied.

ValidateCredentials(username,password,letSuspended)

Summary

Validate Authentication credentials for the user.

Returns

Success if credentials are valid and user isn’t suspended; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
letSuspended System.Boolean If set to true suspension check is skipped.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Possible Results of failure are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : Credentials were successfully validated; however, user is in suspended state.

  • PasswordBlocked : Credentials were successfully validated; however, user’s password is marked as blocked.

ValidateCredentials(model,username,password,logWarnings,letSuspended)

Summary

Validates the credentials.

Returns

An OpResult value indicating whether the validation succeeded or failed (with cause of the failure). See the ValidateCredentials to learn more.

Parameters
Name Type Description
model TUser The model.
username System.String The username.
password System.String The password.
logWarnings System.Boolean if set to true logs failures as warnings.
letSuspended System.Boolean If set to true suspension check is skipped.

Logout()

Summary

Clears the session data related to the current authenticated user (including impersonation).

Parameters

This method has no parameters.

ResetPassword(token,newPassword)

Summary

Changes the password for the user that has the specified password reset token.

Returns

true if password is reset successfully; otherwise false.

Parameters
Name Type Description
token System.String The password reset token generated previously with a call to GeneratePasswordResetToken.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When password reset token or new password is null or whitespace.
Remarks

A successful call also resets password expiration to the value determined by GetPasswordExpirationIntervalInDays, and password blocked related properties to their default values. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session (if any).

UserExists(username)

Summary

Determines if user exists with the specified username.

Returns

true if user with the specified username exists; otherwise false.

Parameters
Name Type Description
username System.String The username to check.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

IsAuthorized(permissionCode)

Summary

Determines whether the current user is authorized for the specified permission.

Returns

true if the current user is authorized for the specified permission; otherwise, false.

Parameters
Name Type Description
permissionCode System.String A permission code representing an action on an entity type – case-insensitive.
Exceptions
Type Description
System.ArgumentNullException When permissionCode is null or whitespace.
Remarks

IsAuthorized(permissionCode,entityId)

Summary

Determines whether the current user is authorized for the specified permission on an entity instance represented by the specified id (optional).

Returns

true if the current user is authorized for the specified permission; otherwise, false.

Parameters
Name Type Description
permissionCode System.String A permission code representing an action on an entity type– case-insensitive.
entityId System.String Optional. The entity instance id.
Exceptions
Type Description
System.ArgumentNullException When permissionCode is null or whitespace.
Remarks

This method skips check for entity instance if user has a general permission for this permissionCode. This way, you can actually grant “editPost” permission to a special set of users (say moderators) on all entity instances of type post.

IsAuthorized(permissionCode,entityId)

Summary

Determines whether the current user is authorized for the specified permission on an entity instance represented by the specified id.

Returns

true if the current user is authorized for the specified permission; otherwise, false.

Parameters
Name Type Description
permissionCode System.String A permission code representing an action on an entity type– case-insensitive.
entityId TEntityId The entity instance id.
Exceptions
Type Description
System.ArgumentNullException When permissionCode is null or whitespace.
Remarks

This method skips check for entity instance if user has a general permission for this permissionCode. This way, you can actually grant “editPost” permission to a special set of users (say moderators) on all entity instances of type post.

GetAuthorizedEntities(permissionCode)

Summary

Gets the keys (ids) of entity instances on which current user is authorized for the specified permission.

Returns

The keys (ids) of entity instances on which current user is authorized for the specified permission.

Parameters
Name Type Description
permissionCode System.String A permission code representing an action on an entity type– case-insensitive.
Exceptions
Type Description
System.ArgumentNullException When permissionCode is null or whitespace.
Remarks

You should use this method for listing pages where a set of entities needs to be loaded and displayed. The return keys of this method can be passed as a parameter to a database call to retrieve only those entities for which user has authorization. Therefore it reduces database traffic and increases speed of your application.

GetLoadedPermissions()

Summary

Gets the permissions loaded for this user.

Returns

Permissions loaded for this user.

Parameters

This method has no parameters.

PossessesPermission(permissionCode)

Summary

Determines whether there exists at least a single authorization record with the specified permissionCode for current user.

Returns

true if at least one authorization record exists with the specified permission code for current user; otherwise false

Parameters
Name Type Description
permissionCode System.String A permission code representing an action on an entity type– case-insensitive.
Exceptions
Type Description
System.ArgumentNullException When permissionCode is null or whitespace.
Remarks

This method returns true for cases if user possesses an authorization for a permissionCode (regardless of whether that permission is an instance permission or a general permission). While the IsAuthorized returns true for general permissions only. This method is useful when you only need to know whether user has a permission for a particular action; you yet don’t need to validate that action for a specific entity. For example, to show/hide menu options.

Grant(permit)

Summary

Grants a permit to a user.

Returns

Success if permit is successfully granted; otherwise, AlreadyExists if the specified permit already exists for this user or Unauthorized if current user itself lacks the privilege to grant the specified permit.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents the permit to be granted to the specified user.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

This method first verifies whether the current user itself has an authorization for the permit before it could grant the same to a subordinate. If verification fails, it returns Unauthorized. Set default(T) for EntityId if you are granting a general permit.

Revoke(permit)

Summary

revokes a permit from a user.

Returns

true if permit is revoked; if no such authorization exists, returns false.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents a permit to be revoked from the specified user.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

Set default(T) for EntityId if you are granting a general permission.

RefreshPermissions()

Summary

Reloads permissions for current user (or permitGroup) from the database.

Parameters

This method has no parameters.

Load(username)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Parameters
Name Type Description
username System.String The logged in username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When user couldn’t be loaded – likely because username doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

Load(userId)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Parameters
Name Type Description
userId TId The logged in userId.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When user couldn’t be loaded – likely because userId doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

Load(username,letSuspended)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
username System.String The logged in username.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
Remarks

Call this method on session_start if the user is already authenticated.

Load(userId,letSuspended)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
userId TId A valid user identifier.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

Call this method on session_start if the user is already authenticated.

Load(auth,letSuspended)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified identity token.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> An identity token details object.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When auth returns both userId and permitGroupId as null. Or when specified userId doesn’t exist or is marked suspended.
Remarks

Call this method when you’ve already established the authentication (via some identity token protocol, for example). It reads authUrn, userId, permitGroupId and impersonatedUserId from auth details and load data accordingly. For instance, if permitGroupId is present, ensures that permissions are only loaded for that group and not whole of userId’s permits. In case of null userId, it considers that the identity token being loaded has no associated user so just need to load permissions for the specified permitGroupId along with a fake user. If impersonatedUserId is present, it considers that the identity token being loaded is a bound impersonated session (which exists only for impersonation; doesn’t allow stop/changing impersonation); therefore, it starts impersonation by calling Impersonate immediately after loading the user.

LoadInternal(user,letSuspended,permitGroupId,clearAll)

Summary

Loads the specified user instance.

Returns

An OpResult value indicating whether the load succeeded or failed (with cause of the failure). See the Load to learn more.

Parameters
Name Type Description
user TUser The user.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
permitGroupId System.Nullable<TId> The permit group identifier.
clearAll System.Boolean if set to true clears the additional models like impersonation and session becomes like a new, empty session.

SetAuthDetails(auth)

Summary

Initializes values for the current identity.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> Details related to the current identity.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When the supplied authUrn is different from the already known authUrn (not when the current authUrn is not set).
Remarks

Current implementation only captures AuthUrn and PermitGroupId. If PermitGroupId is different from the internal one, RefreshPermissions will be called. A use case of this method is post login to initialize authUrn related to the newly initialized session. Login calls this for the same purpose. If you want to initialize completely new identity, you should use Load instead. You can also use this method to change permit context post login if you give such an option to the user.

GetUser(username)

Summary

Gets the TUser model for the user that has the specified username.

Returns

The TUser model for the user that has the specified username.

Parameters
Name Type Description
username System.String The username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GetUser(userId)

Summary

Gets the TUser model for the user that has the specified userId.

Returns

The TUser model for the user that has the specified userId.

Parameters
Name Type Description
userId TId The user id.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

LogIf(conditional,msg,args)

Summary

Logs the specified message if the conditional is true.

Parameters
Name Type Description
conditional System.Boolean Indicates whether to log.
msg System.String The message.
args System.Object[] The arguments.

ClearSessionData(clearImpersonation)

Summary

Clears the session data before loading a new user. Note: this only clears known keys related to currentUser/ImpersonatingUser/UserData/Permits; to clear anything else you’ve added directly on the session store, override this method.

Parameters
Name Type Description
clearImpersonation System.Boolean If true also clears the impersonating user (if there’s one) and session becomes empty to start a new fresh session.

GetUtcNow()

Summary

Gets the current time in UTC.

Returns

The current time in UTC.

Parameters

This method has no parameters.

SetPasswordExpiration(user)

Summary

Updates PasswordExpiredAt on the given instance based on the interval value returned by GetPasswordExpirationIntervalInDays. If interval is null, PasswordExpiredAt is also set to null (no expiration).

Parameters
Name Type Description
user `2 The user instance .

GetData<TOut>(key)

Summary

Gets the value of type TOut associated with the specified key from the current user’s session store.

Returns

The value associated with the specified key from the current user’s session store. If the specified key is not found, it throws a KeyNotFoundException.

Parameters
Name Type Description
key System.String The key of the value to get.
Generic Types
Name Description
TOut The type of the returned value.
Exceptions
Type Description
System.ArgumentNullException When key is null or whitespace.
System.Collections.Generic.KeyNotFoundException When key does not exist in the session store.
Remarks

This method doesn’t check whether key exists in the storage. Therefore you should always call ContainsKey to see if the key exists before calling this method. Or, you can use TryGetData<TValue> instead.

PutData(key,value)

Summary

Adds or overrides the specified value in the current user’s session store against the specified key.

Parameters
Name Type Description
key System.String Key to add.
value System.Object Value associated with key.
Exceptions
Type Description
System.ArgumentNullException When key is null or whitespace.

RemoveData(key)

Summary

Removes the data associated with the key from the current user’s session store.

Parameters
Name Type Description
key System.String The key of the data to remove.
Exceptions
Type Description
System.ArgumentNullException When key is null or whitespace.
Remarks

If the key doesn’t exist, does nothing

ContainsKey(key)

Summary

Determines whether the current user’s session store contains the specified key.

Returns

true if the current user’s session store contains an element with the specified key; otherwise, false.

Parameters
Name Type Description
key System.String The key to locate.
Exceptions
Type Description
System.ArgumentNullException When key is null or whitespace.

TryGetData<TValue>(key)

Summary

Attempts to retrieve a value associated with the specified key from the current user’s session store. Handles both key not found and value not convertible to TValue failures by returning as false.

Returns

A TryOperationResult<TValue> with Succeeded as true and Value populated with data if key is found and is successfully casted to TValue; otherwise, Succeeded as false.

Parameters
Name Type Description
key System.String The key of the value to get.
Generic Types
Name Description
TValue The type of the returned value.
Exceptions
Type Description
System.ArgumentNullException When key is null or whitespace.

IsMFAEnforcedOnUserAsync(auth)

Summary

Determines whether or not multi factor authentication is to be enforced on user.

Returns

true if multi factor authentication is to be enforced on user; otherwise, false.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails Optional. The identity token details object associated with the current user.
Remarks

Current implementation returns true if MFANotRequired is false and MFAEnforced returns true.

IsMFAEnforcedOnUserAsync(auth,cancellationToken)

Summary

Determines whether or not multi factor authentication is to be enforced on user.

Returns

true if multi factor authentication is to be enforced on user; otherwise, false.

Parameters
Name Type Description
auth System.Threading.CancellationToken Optional. The identity token details object associated with the current user.
cancellationToken ASPSecurityKit.IAuthDetails The cancellation token.
Remarks

Current implementation returns true if MFANotRequired is false and MFAEnforced returns true.

IsMFAVerifiedAsync()

Summary

Gets a value indicating if user is marked verified with MFA for this session. See remarks for more details.

Returns

true if user is marked verified with MFA for this session; otherwise, false.

Parameters

This method has no parameters.

Remarks

MFA verification can be valid either for the lifetime of the session (you should provide a checkbox for users to indicate that on the MFA prompt) or it’s only valid for specified duration (say 30 minutes which is default). This validity interval is based on slid expiration which simply means it’s calculated as a difference between last activity recorded time and now. The said time isn’t updated until at least one minute has passed after the last update so as to avoid database call on every request. This method calls SetMFAVerified to update RecentAccessWithMFAAt. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. Use SetMFAVerified for this purpose.

IsMFAVerifiedAsync(cancellationToken)

Summary

Gets a value indicating if user is marked verified with MFA for this session. See remarks for more details.

Returns

true if user is marked verified with MFA for this session; otherwise, false.

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.
Remarks

MFA verification can be valid either for the lifetime of the session (you should provide a checkbox for users to indicate that on the MFA prompt) or it’s only valid for specified duration (say 30 minutes which is default). This validity interval is based on slid expiration which simply means it’s calculated as a difference between last activity recorded time and now. The said time isn’t updated until at least one minute has passed after the last update so as to avoid database call on every request. This method calls SetMFAVerified to update RecentAccessWithMFAAt. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. Use SetMFAVerified for this purpose.

SetMFAVerifiedAsync()

Summary

Marks user as verified for MFA for the current session. It calls SetMFAVerified with validUntilSessionExpired argument as null.

Parameters

This method has no parameters.

SetMFAVerifiedAsync(cancellationToken)

Summary

Marks user as verified for MFA for the current session. It calls SetMFAVerified with validUntilSessionExpired argument as null.

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.

SetMFAVerifiedAsync(validUntilSessionExpired)

Summary

Marks user as verified for MFA for the current session. Optionally if validUntilSessionExpired is true, the MFA verification is considered valid as long as the associated session is valid. Otherwise, the verification will be subject to a validity as defined by MFAAliveForMinutes.

Parameters
Name Type Description
validUntilSessionExpired System.Nullable<Boolean> Indicates if MFA verification is valid for the lifetime of the associated session. If you just pass null it would just slide MFA verification validity.
Exceptions
Type Description
System.InvalidOperationException When either not authenticated or authUrn is empty.
Remarks

Call this method from actions that verify MFA. After that to slide expiration you should rather use IsMFAVerified. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. This method helps in saving them.

SetMFAVerifiedAsync(validUntilSessionExpired,cancellationToken)

Summary

Marks user as verified for MFA for the current session. Optionally if validUntilSessionExpired is true, the MFA verification is considered valid as long as the associated session is valid. Otherwise, the verification will be subject to a validity as defined by MFAAliveForMinutes.

Parameters
Name Type Description
validUntilSessionExpired System.Nullable<Boolean> Indicates if MFA verification is valid for the lifetime of the associated session. If you just pass null it would just slide MFA verification validity.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.InvalidOperationException When either not authenticated or authUrn is empty.
Remarks

Call this method from actions that verify MFA. After that to slide expiration you should rather use IsMFAVerified. Use Login which generates auth token. Subsequent calls should call Load with the same session when needing to reload. You should be saving the session details in db along with MFA verification status - basically two fields RecentAccessWithMFAAt and MFAValidUntilSessionExpired. This method helps in saving them.

ChangePasswordAsync(username,currentPassword,newPassword)

Summary

Changes password for a user that has the specified username.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the username is not valid.)

Parameters
Name Type Description
username System.String A valid username.
currentPassword System.String The current password.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When username/current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePasswordAsync(username,currentPassword,newPassword,cancellationToken)

Summary

Changes password for a user that has the specified username.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the username is not valid.)

Parameters
Name Type Description
username System.String A valid username.
currentPassword System.String The current password.
newPassword System.String The new password.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username/current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePasswordAsync(userId,currentPassword,newPassword)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
currentPassword System.String The current password.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePasswordAsync(userId,currentPassword,newPassword,cancellationToken)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which may mean that either the currentPassword or the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
currentPassword System.String The current password.
newPassword System.String The new password.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or current/new password is null or whitespace.
Remarks

A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session.

ChangePasswordInternalAsync(currentPassword,newPassword,userId,username)

Summary

Changes the password for the user identified by either userId or username.

Returns

true if the password changed successfully; otherwise, false.

Parameters
Name Type Description
currentPassword System.String The current password.
newPassword System.String The new password.
userId System.Nullable<TId> The user identifier.
username System.String The username.

ChangePasswordInternalAsync(currentPassword,newPassword,cancellationToken,userId,username)

Summary

Changes the password for the user identified by either userId or username.

Returns

true if the password changed successfully; otherwise, false.

Parameters
Name Type Description
currentPassword System.String The current password.
newPassword System.String The new password.
cancellationToken System.Threading.CancellationToken The cancellation token.
userId System.Nullable<TId> The user identifier.
username System.String The username.

ChangePasswordAsync(userId,newPassword)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
newPassword System.String The new password.
Exceptions
Type Description
System.InvalidOperationException When parameter userId is the same as CurrentUserId. |
System.ArgumentNullException When userId is null or default, or new password is null or whitespace.
Remarks

Use this method for admins/managers to allow them to reset password for their subordinates without needing to verify their existing password. A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user.

ChangePasswordAsync(userId,newPassword,cancellationToken)

Summary

Changes password for a user that has the specified id.

Returns

true if password is changed; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId A valid user identifier.
newPassword System.String The new password.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.InvalidOperationException When parameter userId is the same as CurrentUserId. |
System.ArgumentNullException When userId is null or default, or new password is null or whitespace.
Remarks

Use this method for admins/managers to allow them to reset password for their subordinates without needing to verify their existing password. A successful call also resets PasswordExpiredAt to the value determined by GetPasswordExpirationIntervalInDays. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user.

ChangeUsernameAsync(username,password,newUsername)

Summary

Changes username of a user that has the specified username.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
username System.String The current username that needs to be changed.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
Exceptions
Type Description
System.ArgumentNullException When username,password or newUsername is null or whitespace.

ChangeUsernameAsync(username,password,newUsername,cancellationToken)

Summary

Changes username of a user that has the specified username.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
username System.String The current username that needs to be changed.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username,password or newUsername is null or whitespace.

ChangeUsernameAsync(userId,password,newUsername)

Summary

Changes username of a user that has the specified id.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
userId TId A valid user identifier.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or password or newUsername is null or whitespace.

ChangeUsernameAsync(userId,password,newUsername,cancellationToken)

Summary

Changes username of a user that has the specified id.

Returns

Success if new username is successfully changed; otherwise, DoNotExist if username doesn’t exist, InvalidPassword if the password did not match or AlreadyExists if the new username already belongs to some other user.

Parameters
Name Type Description
userId TId A valid user identifier.
password System.String Password associated with the specified username to authorize the change.
newUsername System.String The username to change with.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default, or password or newUsername is null or whitespace.

SetSuspensionStatusAsync(userId,suspended,reason)

Summary

Sets the suspension status of a user.

Returns

true if suspension status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose suspension status is to be updated.
suspended System.Boolean Specifies suspension status . True means user is suspended while false means user is activated.
reason System.String Optional. Reason of suspension.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates Suspended with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets SuspensionReason and SuspensionDate. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user so as to enforce suspension immediately.

SetSuspensionStatusAsync(userId,suspended,cancellationToken,reason)

Summary

Sets the suspension status of a user.

Returns

true if suspension status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose suspension status is to be updated.
suspended System.Boolean Specifies suspension status . True means user is suspended while false means user is activated.
cancellationToken System.Threading.CancellationToken The cancellation token.
reason System.String Optional. Reason of suspension.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates Suspended with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets SuspensionReason and SuspensionDate. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user so as to enforce suspension immediately.

SetPasswordBlockedAsync(userId,passwordBlocked,reason)

Summary

Sets the passwordBlocked status of a user.

Returns

true if passwordBlocked status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose passwordBlocked status is to be updated.
passwordBlocked System.Boolean Specifies passwordBlocked status .
reason System.String Reason of blocking password.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates PasswordBlocked with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets PasswordBlockedReason and PasswordBlockedDate.

SetPasswordBlockedAsync(userId,passwordBlocked,reason,cancellationToken)

Summary

Sets the passwordBlocked status of a user.

Returns

true if passwordBlocked status is updated; otherwise false (which means the userId is not valid.)

Parameters
Name Type Description
userId TId Identifier of the user whose passwordBlocked status is to be updated.
passwordBlocked System.Boolean Specifies passwordBlocked status .
reason System.String Reason of blocking password.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

This method updates PasswordBlocked with the value you provide for the user that has the specified user id. Depending on the status value, it also sets or resets PasswordBlockedReason and PasswordBlockedDate.

ImpersonateAsync(username)

Summary

Impersonates a user that has the specified username. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
username System.String The username to impersonate.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When Username doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

ImpersonateAsync(username,cancellationToken)

Summary

Impersonates a user that has the specified username. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
username System.String The username to impersonate.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When Username doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

ImpersonateAsync(userId)

Summary

Impersonates a user that has the specified userId. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
userId TId A valid user identifier.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When UserId doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

ImpersonateAsync(userId,cancellationToken)

Summary

Impersonates a user that has the specified userId. As such, the current user transforms into this new user; actions are verified against this new user’s permissions.

Parameters
Name Type Description
userId TId A valid user identifier.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When UserId doesn’t exist or the current session is a bound impersonated session (initialized with ImpersonatedUserId). |
Remarks

If impersonation is already active, the identity of the ImpersonatingUser is still maintained and impersonation only switches to next user to be impersonated. Suspension check is skipped for the user being impersonated. Note: this should be an admin-level privilege and should be protected from being miss use.

StopImpersonatingAsync()

Summary

Stops the impersonation if it is active and loads the original user details who logged in for this session.

Parameters

This method has no parameters.

Exceptions
Type Description
System.InvalidOperationException When the current session is a bound impersonated session (initialized with ImpersonatedUserId). |

StopImpersonatingAsync(cancellationToken)

Summary

Stops the impersonation if it is active and loads the original user details who logged in for this session.

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.InvalidOperationException When the current session is a bound impersonated session (initialized with ImpersonatedUserId). |

ImpersonateInternalAsync(username,userId)

Summary

Impersonates the user identified by either userId or username.

Parameters
Name Type Description
username System.String The username.
userId System.Nullable<TId> The user identifier.
Exceptions
Type Description
System.InvalidOperationException When user to impersonate couldn’t be loaded.

ImpersonateInternalAsync(username,cancellationToken,userId)

Summary

Impersonates the user identified by either userId or username.

Parameters
Name Type Description
username System.Threading.CancellationToken The username.
cancellationToken System.String The cancellation token.
userId System.Nullable<TId> The user identifier.
Exceptions
Type Description
System.InvalidOperationException When user to impersonate couldn’t be loaded.

GetStorageDataAsync()

Summary

Gets the data in session related to the current identity.

Returns

The data in session related to the current identity.

Parameters

This method has no parameters.

Remarks

Override this method and return any other data you’ve added directly onto the ISessionService for the current user. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or SetStorageData as it’d be automatically managed.

GetStorageDataAsync(cancellationToken)

Summary

Gets the data in session related to the current identity.

Returns

The data in session related to the current identity.

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.
Remarks

Override this method and return any other data you’ve added directly onto the ISessionService for the current user. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or SetStorageData as it’d be automatically managed.

SetStorageDataAsync(details)

Summary

Overrides the existing data in session related to the current identity.

Parameters
Name Type Description
details ASPSecurityKit.UserServiceSessionDetails<TId, TUser> Object containing session data to override.
Exceptions
Type Description
System.ArgumentNullException When details is null.
Remarks

Override this method and set any other data you’ve captured previously with GetStorageData. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or GetStorageData as it’d be automatically managed.

SetStorageDataAsync(details,cancellationToken)

Summary

Overrides the existing data in session related to the current identity.

Parameters
Name Type Description
details ASPSecurityKit.UserServiceSessionDetails<TId, TUser> Object containing session data to override.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When details is null.
Remarks

Override this method and set any other data you’ve captured previously with GetStorageData. It is however advised to manage additional data on the user data store available with methods like PutData. In which case you don’t need to override this or GetStorageData as it’d be automatically managed.

VerifyAccountAsync(token)

Summary

Sets Verified to true for the user that has the specified token.

Returns

true if a user with the token is found and verification status updated successfully. otherwise false.

Parameters
Name Type Description
token System.String A valid verification token generated during registration for example.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

VerifyAccountAsync(token,cancellationToken)

Summary

Sets Verified to true for the user that has the specified token.

Returns

true if a user with the token is found and verification status updated successfully. otherwise false.

Parameters
Name Type Description
token System.String A valid verification token generated during registration for example.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

NewUserAsync(username,password,name)

Summary

creates a new user model instance.

Returns

A new user model instance.

Parameters
Name Type Description
username System.String The login username; must be unique.
password System.String The password.
name System.String The name of the user.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Use this method in conjunction with CreateAccount during sign up/add new user process. First call this method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

NewUserAsync(username,password,name,cancellationToken)

Summary

creates a new user model instance.

Returns

A new user model instance.

Parameters
Name Type Description
username System.String The login username; must be unique.
password System.String The password.
name System.String The name of the user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Use this method in conjunction with CreateAccount during sign up/add new user process. First call this method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

CreateAccountAsync(model)

Summary

Completes the new user registration process.

Returns

true if user model is saved successfully; otherwise false.

Parameters
Name Type Description
model TUser The user model.
Exceptions
Type Description
System.ArgumentNullException When model is null.
Remarks

Use this method in conjunction with NewUser during sign up/add new user process. First call NewUser method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

CreateAccountAsync(model,cancellationToken)

Summary

Completes the new user registration process.

Returns

true if user model is saved successfully; otherwise false.

Parameters
Name Type Description
model TUser The user model.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When model is null.
Remarks

Use this method in conjunction with NewUser during sign up/add new user process. First call NewUser method and set any property you want on the returned TUser model. After that, call the CreateAccount method passing the model.

GeneratePasswordResetTokenAsync(username)

Summary

Generates the password reset token for the specified username.

Returns

If a user with the specified username exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GeneratePasswordResetTokenAsync(username,cancellationToken)

Summary

Generates the password reset token for the specified username.

Returns

If a user with the specified username exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GeneratePasswordResetTokenAsync(userId)

Summary

Generates the password reset token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GeneratePasswordResetTokenAsync(userId,cancellationToken)

Summary

Generates the password reset token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated password reset token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GenerateVerificationTokenAsync(username,resetVerification)

Summary

Generates the verification token for the specified username.

Returns

If a user with the specified username exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GenerateVerificationTokenAsync(username,cancellationToken,resetVerification)

Summary

Generates the verification token for the specified username.

Returns

If a user with the specified username exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
username System.String A valid username.
cancellationToken System.Threading.CancellationToken The cancellation token.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GenerateVerificationTokenAsync(userId,resetVerification)

Summary

Generates the verification token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GenerateVerificationTokenAsync(userId,cancellationToken,resetVerification)

Summary

Generates the verification token for the specified userId.

Returns

If a user with the specified userId exists, returns the Generated verification token that can be safely embedded as a part of a URL, otherwise, returns null.

Parameters
Name Type Description
userId TId A valid user identifier.
cancellationToken System.Threading.CancellationToken The cancellation token.
resetVerification System.Boolean Tells whether to reset Verified property to false. The default is true (user state is changed to “unverified”.)
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GenerateVerificationTokenInternalAsync(username,userId,resetVerification)

Summary

Generates the verification token for the user identified by either userId or username.

Returns

The generated token or null if user not found.

Parameters
Name Type Description
username System.String The username.
userId System.Nullable<TId> The user identifier.
resetVerification System.Boolean Indicates whether to reset the user’s verification status to false.

GenerateVerificationTokenInternalAsync(username,cancellationToken,userId,resetVerification)

Summary

Generates the verification token for the user identified by either userId or username.

Returns

The generated token or null if user not found.

Parameters
Name Type Description
username System.Threading.CancellationToken The username.
cancellationToken System.String The cancellation token.
userId System.Nullable<TId> The user identifier.
resetVerification System.Boolean Indicates whether to reset the user’s verification status to false.

IsPasswordResetTokenValidAsync(token)

Summary

Determines whether specified token exists and is valid for password reset.

Returns

true if specified token exists and is valid for password reset; otherwise, false.

Parameters
Name Type Description
token System.String The token previously generated by calling GeneratePasswordResetToken.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

IsPasswordResetTokenValidAsync(token,cancellationToken)

Summary

Determines whether specified token exists and is valid for password reset.

Returns

true if specified token exists and is valid for password reset; otherwise, false.

Parameters
Name Type Description
token System.String The token previously generated by calling GeneratePasswordResetToken.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When token is null or whitespace.

LoginAsync(username,password,persist,letSuspended)

Summary

Authenticates the user; if successful, creates an appropriate mechanism (cookie or otherwise) for long-term session if persistence is specified. Additionally, if Suspended is true, you can specify whether or not to allow suspended user to login.

Returns

Success if login was successful; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
persist System.Boolean If set to true a long-lived persistent session is to be created with expiration value as returned by RememberMeTimeoutInMinutes; otherwise, a limited duration session is to be created.
letSuspended System.Boolean If set to true a suspended user is permitted to login; otherwise login is denied.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Login may fail for many reasons. However, you must show a generic message in most cases for security reasons. The returned value of type OpResult contains the exact reason of login failure. Possible reasons are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : User’s credentials were successfully validated; however, user is suspended and suspended users are not allowed to login. You can set letSuspended to true to let suspended user login.

  • PasswordBlocked : User’s credentials were successfully validated; however, user’s password is marked as blocked. Therefore, login is denied.

LoginAsync(username,password,cancellationToken,persist,letSuspended)

Summary

Authenticates the user; if successful, creates an appropriate mechanism (cookie or otherwise) for long-term session if persistence is specified. Additionally, if Suspended is true, you can specify whether or not to allow suspended user to login.

Returns

Success if login was successful; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
cancellationToken System.Threading.CancellationToken The cancellation token.
persist System.Boolean If set to true a long-lived persistent session is to be created with expiration value as returned by RememberMeTimeoutInMinutes; otherwise, a limited duration session is to be created.
letSuspended System.Boolean If set to true a suspended user is permitted to login; otherwise login is denied.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Login may fail for many reasons. However, you must show a generic message in most cases for security reasons. The returned value of type OpResult contains the exact reason of login failure. Possible reasons are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : User’s credentials were successfully validated; however, user is suspended and suspended users are not allowed to login. You can set letSuspended to true to let suspended user login.

  • PasswordBlocked : User’s credentials were successfully validated; however, user’s password is marked as blocked. Therefore, login is denied.

ValidateCredentialsAsync(username,password,letSuspended)

Summary

Validate Authentication credentials for the user.

Returns

Success if credentials are valid and user isn’t suspended; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
letSuspended System.Boolean If set to true suspension check is skipped.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Possible Results of failure are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : Credentials were successfully validated; however, user is in suspended state.

  • PasswordBlocked : Credentials were successfully validated; however, user’s password is marked as blocked.

ValidateCredentialsAsync(username,password,cancellationToken,letSuspended)

Summary

Validate Authentication credentials for the user.

Returns

Success if credentials are valid and user isn’t suspended; otherwise a reason of type OpResult. See remarks for more details.

Parameters
Name Type Description
username System.String The login username.
password System.String The login password.
cancellationToken System.Threading.CancellationToken The cancellation token.
letSuspended System.Boolean If set to true suspension check is skipped.
Exceptions
Type Description
System.ArgumentNullException When username or password is null or whitespace.
Remarks

Possible Results of failure are:

  • DoNotExist : No user exists with the specified username.

  • InvalidPassword : Specified password is incorrect.

  • Suspended : Credentials were successfully validated; however, user is in suspended state.

  • PasswordBlocked : Credentials were successfully validated; however, user’s password is marked as blocked.

ValidateCredentialsAsync(model,username,password,logWarnings,letSuspended)

Summary

Validates the credentials.

Returns

An OpResult value indicating whether the validation succeeded or failed (with cause of the failure). See the ValidateCredentials to learn more.

Parameters
Name Type Description
model TUser The model.
username System.String The username.
password System.String The password.
logWarnings System.Boolean if set to true logs failures as warnings.
letSuspended System.Boolean If set to true suspension check is skipped.

ValidateCredentialsAsync(model,username,password,logWarnings,letSuspended,cancellationToken)

Summary

Validates the credentials.

Returns

An OpResult value indicating whether the validation succeeded or failed (with cause of the failure). See the ValidateCredentials to learn more.

Parameters
Name Type Description
model TUser The model.
username System.String The username.
password System.String The password.
logWarnings System.Boolean if set to true logs failures as warnings.
letSuspended System.Boolean If set to true suspension check is skipped.
cancellationToken System.Threading.CancellationToken The cancellation token.

LogoutAsync()

Summary

Clears the session data related to the current authenticated user (including impersonation).

Parameters

This method has no parameters.

LogoutAsync(cancellationToken)

Summary

Clears the session data related to the current authenticated user (including impersonation).

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.

ResetPasswordAsync(token,newPassword)

Summary

Changes the password for the user that has the specified password reset token.

Returns

true if password is reset successfully; otherwise false.

Parameters
Name Type Description
token System.String The password reset token generated previously with a call to GeneratePasswordResetToken.
newPassword System.String The new password.
Exceptions
Type Description
System.ArgumentNullException When password reset token or new password is null or whitespace.
Remarks

A successful call also resets password expiration to the value determined by GetPasswordExpirationIntervalInDays, and password blocked related properties to their default values. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session (if any).

ResetPasswordAsync(token,newPassword,cancellationToken)

Summary

Changes the password for the user that has the specified password reset token.

Returns

true if password is reset successfully; otherwise false.

Parameters
Name Type Description
token System.String The password reset token generated previously with a call to GeneratePasswordResetToken.
newPassword System.String The new password.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When password reset token or new password is null or whitespace.
Remarks

A successful call also resets password expiration to the value determined by GetPasswordExpirationIntervalInDays, and password blocked related properties to their default values. Additionally, it makes call to ExpireUserSessions to expire all active sessions related to the user other than the current session (if any).

UserExistsAsync(username)

Summary

Determines if user exists with the specified username.

Returns

true if user with the specified username exists; otherwise false.

Parameters
Name Type Description
username System.String The username to check.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

UserExistsAsync(username,cancellationToken)

Summary

Determines if user exists with the specified username.

Returns

true if user with the specified username exists; otherwise false.

Parameters
Name Type Description
username System.String The username to check.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GrantAsync(permit)

Summary

Grants a permit to a user.

Returns

Success if permit is successfully granted; otherwise, AlreadyExists if the specified permit already exists for this user or Unauthorized if current user itself lacks the privilege to grant the specified permit.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents the permit to be granted to the specified user.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

This method first verifies whether the current user itself has an authorization for the permit before it could grant the same to a subordinate. If verification fails, it returns Unauthorized. Set default(T) for EntityId if you are granting a general permit.

GrantAsync(permit,cancellationToken)

Summary

Grants a permit to a user.

Returns

Success if permit is successfully granted; otherwise, AlreadyExists if the specified permit already exists for this user or Unauthorized if current user itself lacks the privilege to grant the specified permit.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents the permit to be granted to the specified user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

This method first verifies whether the current user itself has an authorization for the permit before it could grant the same to a subordinate. If verification fails, it returns Unauthorized. Set default(T) for EntityId if you are granting a general permit.

RevokeAsync(permit)

Summary

revokes a permit from a user.

Returns

true if permit is revoked; if no such authorization exists, returns false.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents a permit to be revoked from the specified user.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

Set default(T) for EntityId if you are granting a general permission.

RevokeAsync(permit,cancellationToken)

Summary

revokes a permit from a user.

Returns

true if permit is revoked; if no such authorization exists, returns false.

Parameters
Name Type Description
permit ASPSecurityKit.IPermit The IPermit object that represents a permit to be revoked from the specified user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When permit is null.
Remarks

Set default(T) for EntityId if you are granting a general permission.

RefreshPermissionsAsync()

Summary

Reloads permissions for current user (or permitGroup) from the database.

Parameters

This method has no parameters.

RefreshPermissionsAsync(cancellationToken)

Summary

Reloads permissions for current user (or permitGroup) from the database.

Parameters
Name Type Description
cancellationToken System.Threading.CancellationToken The cancellation token.

LoadAsync(username)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Parameters
Name Type Description
username System.String The logged in username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When user couldn’t be loaded – likely because username doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(username,cancellationToken)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Parameters
Name Type Description
username System.String The logged in username.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
System.InvalidOperationException When user couldn’t be loaded – likely because username doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(userId)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Parameters
Name Type Description
userId TId The logged in userId.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When user couldn’t be loaded – likely because userId doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(userId,cancellationToken)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Parameters
Name Type Description
userId TId The logged in userId.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
System.InvalidOperationException When user couldn’t be loaded – likely because userId doesn’t exist or is marked suspended.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(username,letSuspended)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
username System.String The logged in username.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(username,letSuspended,cancellationToken)

Summary

Loads the user data into memory – IUser model and permissions for the specified username.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
username System.String The logged in username.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(userId,letSuspended)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
userId TId A valid user identifier.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(userId,letSuspended,cancellationToken)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified userId.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
userId TId A valid user identifier.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.
Remarks

Call this method on session_start if the user is already authenticated.

LoadAsync(auth,letSuspended)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified identity token.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> An identity token details object.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When auth returns both userId and permitGroupId as null. Or when specified userId doesn’t exist or is marked suspended.
Remarks

Call this method when you’ve already established the authentication (via some identity token protocol, for example). It reads authUrn, userId, permitGroupId and impersonatedUserId from auth details and load data accordingly. For instance, if permitGroupId is present, ensures that permissions are only loaded for that group and not whole of userId’s permits. In case of null userId, it considers that the identity token being loaded has no associated user so just need to load permissions for the specified permitGroupId along with a fake user. If impersonatedUserId is present, it considers that the identity token being loaded is a bound impersonated session (which exists only for impersonation; doesn’t allow stop/changing impersonation); therefore, it starts impersonation by calling Impersonate immediately after loading the user.

LoadAsync(auth,letSuspended,cancellationToken)

Summary

Loads the user data into memory – IUser<TId> model and permissions for the specified identity token.

Returns

DoNotExist if user not found. Suspended if user is suspended and letSuspended is false; otherwise, Success.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> An identity token details object.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When auth returns both userId and permitGroupId as null. Or when specified userId doesn’t exist or is marked suspended.
Remarks

Call this method when you’ve already established the authentication (via some identity token protocol, for example). It reads authUrn, userId, permitGroupId and impersonatedUserId from auth details and load data accordingly. For instance, if permitGroupId is present, ensures that permissions are only loaded for that group and not whole of userId’s permits. In case of null userId, it considers that the identity token being loaded has no associated user so just need to load permissions for the specified permitGroupId along with a fake user. If impersonatedUserId is present, it considers that the identity token being loaded is a bound impersonated session (which exists only for impersonation; doesn’t allow stop/changing impersonation); therefore, it starts impersonation by calling Impersonate immediately after loading the user.

LoadInternalAsync(user,letSuspended,permitGroupId,clearAll)

Summary

Loads the specified user instance.

Returns

An OpResult value indicating whether the load succeeded or failed (with cause of the failure). See the Load to learn more.

Parameters
Name Type Description
user TUser The user.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
permitGroupId System.Nullable<TId> The permit group identifier.
clearAll System.Boolean if set to true clears the additional models like impersonation and session becomes like a new, empty session.

LoadInternalAsync(user,letSuspended,cancellationToken,permitGroupId,clearAll)

Summary

Loads the specified user instance.

Returns

An OpResult value indicating whether the load succeeded or failed (with cause of the failure). See the Load to learn more.

Parameters
Name Type Description
user TUser The user.
letSuspended System.Boolean If set to false and the specified user is found suspended, forbids loading and returns Suspended; otherwise, loads the user.
cancellationToken System.Threading.CancellationToken The cancellation token.
permitGroupId System.Nullable<TId> The permit group identifier.
clearAll System.Boolean if set to true clears the additional models like impersonation and session becomes like a new, empty session.

SetAuthDetailsAsync(auth)

Summary

Initializes values for the current identity.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> Details related to the current identity.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When the supplied authUrn is different from the already known authUrn (not when the current authUrn is not set).
Remarks

Current implementation only captures AuthUrn and PermitGroupId. If PermitGroupId is different from the internal one, RefreshPermissions will be called. A use case of this method is post login to initialize authUrn related to the newly initialized session. Login calls this for the same purpose. If you want to initialize completely new identity, you should use Load instead. You can also use this method to change permit context post login if you give such an option to the user.

SetAuthDetailsAsync(auth,cancellationToken)

Summary

Initializes values for the current identity.

Parameters
Name Type Description
auth ASPSecurityKit.IAuthDetails<TId> Details related to the current identity.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When auth is null.
System.InvalidOperationException When the supplied authUrn is different from the already known authUrn (not when the current authUrn is not set).
Remarks

Current implementation only captures AuthUrn and PermitGroupId. If PermitGroupId is different from the internal one, RefreshPermissions will be called. A use case of this method is post login to initialize authUrn related to the newly initialized session. Login calls this for the same purpose. If you want to initialize completely new identity, you should use Load instead. You can also use this method to change permit context post login if you give such an option to the user.

GetUserAsync(username)

Summary

Gets the TUser model for the user that has the specified username.

Returns

The TUser model for the user that has the specified username.

Parameters
Name Type Description
username System.String The username.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GetUserAsync(username,cancellationToken)

Summary

Gets the TUser model for the user that has the specified username.

Returns

The TUser model for the user that has the specified username.

Parameters
Name Type Description
username System.String The username.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When username is null or whitespace.

GetUserAsync(userId)

Summary

Gets the TUser model for the user that has the specified userId.

Returns

The TUser model for the user that has the specified userId.

Parameters
Name Type Description
userId TId The user id.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

GetUserAsync(userId,cancellationToken)

Summary

Gets the TUser model for the user that has the specified userId.

Returns

The TUser model for the user that has the specified userId.

Parameters
Name Type Description
userId TId The user id.
cancellationToken System.Threading.CancellationToken The cancellation token.
Exceptions
Type Description
System.ArgumentNullException When userId is null or default.

SetPasswordExpirationAsync(user)

Summary

Updates PasswordExpiredAt on the given instance based on the interval value returned by GetPasswordExpirationIntervalInDays. If interval is null, PasswordExpiredAt is also set to null (no expiration).

Parameters
Name Type Description
user `2 The user instance .

SetPasswordExpirationAsync(user,cancellationToken)

Summary

Updates PasswordExpiredAt on the given instance based on the interval value returned by GetPasswordExpirationIntervalInDays. If interval is null, PasswordExpiredAt is also set to null (no expiration).

Parameters
Name Type Description
user `2 The user instance .
cancellationToken System.Threading.CancellationToken The cancellation token.