Click or drag to resize

Context of execution

Most of the AskiaPortalCmn API constructors require a context of execution (an instance of IContext).

This is extremely important for the API to have a context of execution in order to:

  • Identify the application that request the action

  • Identify the user who request the action

  • Determine if the user is allowed to do the action

  • Adapt the behavior of the API accordingly

  • Store the correct information in logs

  • etc...

Note Note

Most AskiaPortalCmn API methods will failed when the context of execution is not valid.

Use the Validate method of the IContext to evaluate if a method will fail for sure.

The context of execution is created by the ContextFactory methods.

Important note Important

Please use one context object per HTTP request (in web context), or per relevant action.

A context is not intended to be cached or use for the entire life-time of module application.

It's designed to have a short life-cycle and to be per request centric.

This topic contains the following sections:

Validation
Regular contexts

A context of execution is mainly focused around the notion of current user. All AskiaPortalCmn actions are done by a user account.

The current user is the instance of the IUser available through the property IContextUser.

The API provide some methods to create a regular context:

CreateByUserGuid(Guid, String)

Mostly used when there is no need of explicit authentication, when the user GUID is known and possibly hard-coded.

It's useful for system tasks/services using the super-administrator account.

CreateByUserEmail(String, String)

Mostly used when to send a reset password email or when the only information provided is the user email address.

CreateByLoginOrEmailAndPassword(String, String, String)

Used when an explicit authentication is require.

CreateBySessionKey(String, String)

Mostly used after an explicit authentication to manage user sessions.

This context take care of a session life-time and timeouts.

Use the method IContextBuildSessionKey to generate a session key based on a valid context.

Management of sessions

AskiaPortalCmn API provide a built-in basic management of user sessions:

Step 1. Authenticate the user explicitly
Copy
string login = Request.Params["login"];
string password = Request.Params["password"];
var context = ContextFactory.CreateByLoginOrEmailAndPassword(login, password);
Step 2. Build a session key for the next API request
Copy
var validation = context.Validate();
if (!validation.Success)
{
    throw validation.Exception;
}

var sessionKey = context.BuildSessionKey();
if (!sessionKey.Success)
{
    throw successKey.Exception;
}

var cookie = new HttpCookie("session", sessionKey.Value);
Response.Cookies.Add(cookie);
Step 3. Create a new context for the new request
Copy
var sessionKey = Request.Cookies["session"].Value;
var context = ContextFactory.CreateBySessionKey(sessionKey);
var validation = context.Validate();
if (!validation.Success)
{
    throw validation.Exception;
}

A full code example is available here

Special contexts

A context could be created for a specific usage, specially for the user account manipulation.

Normally the creation or the activation of user account require administrative privileges. But AskiaPortalCmn allow in certain condition the user to register and activate himself. For such reasons, AskiaPortalCmn provide some special contexts.

For super-administrator

This context is created using ContextFactoryCreateForSuperAdmin.

It create a valid context with the super administrator as a current user ( IContextUser).

This context doesn't have any restrictions, it's typically used for administrative tasks or server-side service processes.

For Registration

This context is created using ContextFactoryCreateForRegistration.

It create a valid context with a new user as a current user ( IContextUser).

This context is restricted to some actions:

For Activation

This context is created using ContextFactoryCreateByUserEncryptedKey with a key generated from IUserBuildEncryptedKey with EncryptedKeyActionActivateAccount.

The context will be invalid, if the key provided is invalid or if the user doesn't need to be activated anymore.

Otherwise a valid context will be created with the current user correctly initialized (IContextUser).

This context is restricted to some actions:

For Password Reset

This context is created using ContextFactoryCreateByUserEncryptedKey with a key generated from IUserBuildEncryptedKey with EncryptedKeyActionResetPassword.

The context will be invalid, if the key provided is invalid or if the user has changes since the creation of the key.

Otherwise a valid context will be created with the current user correctly initialized (IContextUser).

This context is restricted to some actions:

See Also