Up The Login process

On the client

Last modified on August 15, 2012 17:20

The process of logging in a user involves a handshake between the client application and the Entity Server.  Here we'll discuss what you need to do on the client to authenticate a user.

Authentication begins on the client, when Login is called.  Until a Login successfully completes, an EntityManager may not communicate with the EntityServer for data or services.


At its simplest, gather user credentials into an ILoginCredential and call the Authenticator Login  or LoginAsync  method (only the asynchronous version is available to Silverlight applications):

IAuthenticationContext Login(ILoginCredential credential, LoginOptions options);

LoginOperation LoginAsync(ILoginCredential credential, LoginOptions options, Action<LoginOperation> userCallback, object userState);
Function Login(credential As ILoginCredential, options As LoginOptions) As IAuthenticationContext

Function LoginAsync(credential As ILoginCredential, options As LoginOptions, userCallback As Action(Of LoginOperation), userState As Object) As LoginOperation
It's worth noting that the credential is passed in clear text.  Use a secure channel (such as SSL) or provide your own encryption of the credential data if secure communications are required.  

DevForce provides two implementations of the ILoginCredential: the LoginCredential and FormsAuthenticationLoginCredential. If necessary, you can sub-type one of these, or create your own implementation too.

The Authenticator class was introduced in release 6.1.6.  In earlier versions the Login and Logout methods on the EntityManager should be used.

What if you don't have a credential?  For example, you're using Windows credentials, or allow guest access, or you're using ASP.NET security with Windows authentication or a persistent or ambient authentication ticket.  In these cases, calling the Login method without a supplied credential indicates that the EntityServer will determine how to handle the login request.  When using ASP.NET security, the built-in implementation will try to use the current user information from the HttpContext.

After the login completes successfully you can use the returned IAuthenticationContext to set the DefaultAuthenticationContext for the application, or set the AuthenticationContext for a specific EntityManager.  If using LoginAsync, the IAuthenticationContext is returned in the LoginOperation when the operation completes.

When the DefaultAuthenticationContext is set, by default all EntityManagers are considered "logged in" and may communicate with an EntityServer.  The Principal property indicates the logged in user identity and roles.

If the Login failed, a LoginException is returned.  When called synchronously the exception is thrown; when called asynchronously the exception is available in the LoginOperation.Error property.


The LoginOptions  can be passed with a login call to indicate information about the EntityServer which will perform the authentication.  You can specify the data source extension, composition context, and other information, to tell the Authenticator which EntityServer to use.  If you don't specify the LoginOptions, by default an EntityServer without a data source extension or composition context is used.  Note that if you login with a deprecated login method on an EntityManager, the LoginOptions used will reflect the settings of that EntityManager.


The Logout method performs another handshake with the EntityServer, telling it to remove session information for the user.  Further requests to the server from a "logged out" EntityManager are disallowed until it again logs in.  

void Logout(IAuthenticationContext context);
Sub Logout(context As IAuthenticationContext)

Many applications do not explicitly call Logout, and it's not strictly necessary.  The user session information on the server will expire after a period of inactivity.  If your application is available on public computers it's generally a good idea to logout either by user request or when the application closes.  

Note that the user session information stored on the server has a very small footprint.  It's simply a bundle containing encrypted credentials and a few additional fields tracking last activity; no other data is stored.

Single sign-on / sign-off

As of version 6.1.6, DevForce implements single sign-on/sign-off by default.  Every EntityManager by default uses a shared "authentication context", the Authenticator.DefaultAuthenticationContext .  The DefaultAuthenticationContext can be set in two ways: 1) directly by the application using the results of a Login or LoginAsync call on the Authenticator singleton; or 2) by calling Login or LoginAsync on an EntityManager whose Options.UseDefaultAuthenticationContext setting is true, which it is by default.

Setting the DefaultAuthenticationContext explicitly:

// With a sync login:
var cred = new LoginCredential("max", "headroom", string.Empty);
Authenticator.Instance.DefaultAuthenticationContext = Authenticator.Instance.Login(cred);

// Or async login:
var cred = new LoginCredential("max", "headroom", string.Empty);
var op = Authenticator.Instance.LoginAsync(cred);
op.Completed += (s, args) => {
 if (!args.HasError)
    Authenticator.Instance.DefaultAuthenticationContext = args.AuthenticationContext;

Setting the DefaultAuthenticationContext implicitly:

var mgr = new EntityManager();
bool usesDefault = mgr.Options.UseDefaultAuthenticationContext;
var cred = new LoginCredential("walter", "cronkite", string.Empty);
// If usesDefault is true, DefaultAuthenticationContext has been set.

An EntityManager can opt out of this shared context by setting its Options.UseDefaultAuthenticationContext to false, and then logging in.  EntityManagers can also share a non-default AuthenticationContext:  by using the copy constructor, by calling LinkForAuthentication, or by setting the AuthenticationContext on the EntityManager.  See below for more information. 

When an AuthenticationContext is logged out, any EntityManager using that context is logged out.

Authenticate without logging in

Now that we've covered the mechanics of client login, it's time to cover other ways in which an EntityManager can be authenticated.

There are several ways, and they're all based on sharing an existing AuthenticationContext .  Remember that by default, an EntityManager will use the Authenticator.DefaultAuthenticationContext.

  1. Create an EntityManager via the copy constructor
  var newEntityManager = new EntityManager(anotherEntityManager);
 Dim newEntityManager = New EntityManager(anotherEntityManager)

The new EntityManager will have the same connection state, and share the user credentials from the other EntityManager.

2. Set the EntityManager.AuthenticationContext

You can share an AuthenticationContext among EntityManagers by setting the EntityManager.AuthenticationContext property.

var authContext = Authenticator.Instance.Login();
var entityManager = new EntityManager();
entityManager.AuthenticationContext = authContext;

3. Use EntityManager.LinkForAuthentication  (Deprecated)

var entityManager = new EntityManager();
Dim entityManager = New EntityManager()

4. Use IAuthenticationManager.LinkAuthentication (Deprecated)

bool LinkAuthentication(EntityManager targetEM);
Boolean LinkAuthentication(EntityManager targetEM)

DevForce will automatically search for an implementation of IdeaBlade.EntityModel.IAuthenticationProvider when login credentials are needed.  This provider returns your custom IAuthenticationManager.  DevForce will call the IAuthenticationManager.LinkAuthentication method to allow you to set credentials on the EntityManager.  This interface has been deprecated as of the 6.1.6 release.


Tags: Security
Created by DevForce on March 08, 2012 11:25

This wiki is licensed under a Creative Commons 2.0 license. XWiki Enterprise 3.2 - Documentation. Copyright © 2015 IdeaBlade