Configuring Your Application Manually

In this tutorial you will learn how to create a secured Web site where users need to provide user name and password to sign in.

Source Code

You can find the source code for this chapter in the Examples\VB\SAFormsVB (or Examples\CS\SAFormsCS) folder in the Secure Access installation folder.

		Source Code
You can find the source code for this chapter in the Examples\VB\SAFormsVB (or Examples\CS\SAFormsCS) folder in the Secure Access installation folder.

Create a new ASP.NET project or open an existing one.

Set proper authentication on the virtual directory in the Internet Information Services console (you can find it in the Control Panels, in the Administrative Tools folder): Locate your Web application in the tree and view its properties. Choose the "Directory Security" tab, click on the "Edit..." button and make sure that only "Anonymous access" box is checked and the "Digest authentication", "Basic authentication" and "Integrated Windows Authentication" boxes are unchecked.

Authentication settings of the Internet Information Services

Tip

Tip: You may prefer to leave the "Windows Authentication" box checked during the development phase so that you are allowed to debug your applications from the Visual Studio.NET environment.

Add reference to the Secure Access libraries into your project:
- Choose "Project" - "Add Reference..." item in the main menu.
- Choose the ".NET" tab on the "Add Reference" dialog and click "Browse...". Choose ARDataServices.dll, ARObjects.dll and SecureAccess.dll files in the "DLLs" subfolder in the installation folder. Click the "Select" button and then click the "OK" button.
  
  Adding reference to the Secure Access Libraries

		Tip
Tip: You may prefer to leave the "Windows Authentication" box checked during the development phase so that you are allowed to debug your applications from the Visual Studio.NET environment.

Add following lines in the "configuration" section of the Web.config file:


<appSettings>
		 <add key="SecureAccessConnectionString" value="data source=localhost;initial catalog=SecureAccess;user id=portsight;password=p0sight%.x" />		 
</appSettings>

Modify data source, initial catalog, user id and password to appropriate values.

What you did:

You added the default connection string for the PortSight Secure Access database.

Add following lines in the "system.web" section (or replace the same section if it already exists):


<authentication mode="Forms" > 
	<forms name="SecureAccessCookie" 
		   path="/" 
		   loginUrl="LogonForm.aspx"  
		   protection="All" 
		   timeout="60">
	</forms>
</authentication>

What you did:

You set up the ASP.NET security for the forms authentication with following parameters (these are standard ASP.NET configuration settings, you can find more details in the .NET Framework SDK documentation):

Name - name of the cookie that will be used to store user identity on the client side.
Path - describes the path (including subfolders) the authentication cookie is valid for.
LoginUrl - name of the page the users will be redirected to when they come not authenticated to your Web site.
Protection - method of cookie encryption.
Timeout - number of minutes until the authentication cookie expires. If user is inactive for specified period he/she must sign in again. If you use session variables for storing user information (user ticket) you should set this value to a smaller value than for the session time-out in the configuration/system.web/sessionState section.

Add or modify the "authorization" element in the "system.web" section so that it looks like this one:


<authorization>
		<deny users="?" />
</authorization>

What you did:

You denied access to your application for all users, unless they're authenticated. It applies to all aspx pages except the logon form.

Open your Global.asax file and add following lines at the beginning of its code-behind:

[Visual Basic]

Imports System.Web.Security
Imports System.Resources
Imports PortSight.SecureAccess.ARDataServices
Imports PortSight.SecureAccess.ARObjects
Imports System.Threading
Imports System.Globalization



[C#]

using System.Web.Security;
using System.Resources;
using PortSight.SecureAccess.ARDataServices;
using PortSight.SecureAccess.ARObjects;
using System.Threading;
using System.Globalization;

What you did:

You imported namespaces of Secure Access libraries, namespaces for globalization (these are required by the Secure Access user controls) and namespaces for ASP.NET.

Add following code to the Application_Start event in the Global.asax:

[Visual Basic]

'create resource manager and store it in the application variable
Dim assmbl As System.Reflection.Assembly = System.Reflection.Assembly.Load("SecureAccess")
Dim Resman As ResourceManager = New ResourceManager("SecureAccess.strings", assmbl)
Application("RM") = Resman



[C#]

//create resource manager and store it in the application variable
System.Reflection.Assembly assmbl = System.Reflection.Assembly.Load("SecureAccess");
ResourceManager Resman = new ResourceManager("SecureAccess.strings", assmbl);
Application["RM"] = Resman;

What you did:

You added code that creates resource manager and stores it in the application variable. This is necessary if you want to reuse the Secure Access user controls (*.ascx), such as ARUILogonForm.ascx, in your application.

Add following lines in the Session_Start event in the Global.asax:

[Visual Basic]

'create user ticket
Dim currentUser As ARUser
Dim arCN As ARConnection

If User.Identity.IsAuthenticated Then
    arCN = New ARConnection()
    arCN.ConnectToCatalog()

    currentUser = arCN.GetUserByLogin(User.Identity.Name)
    If currentUser Is Nothing Then
        'user was not found in the database
        arCN.Close()
        Response.Redirect("AccessDenied.aspx")
    Else
        If currentUser.IsLocked Then
            'account is locked -> access denied
            arCN.Close()
            Response.Redirect("AccessDenied.aspx")
        Else
            'account has been found and is not locked
            'create user ticket and store it in the session variable
            Session("ARUserTicket") = New ARUserTicket(currentUser)
            arCN.Close()
        End If
    End If
End If



[C#]

//create user ticket
ARUser currentUser;
ARConnection arCN;

if (User.Identity.IsAuthenticated) {			
	arCN = new ARConnection();
	arCN.ConnectToCatalog();

	currentUser = arCN.GetUserByLogin(User.Identity.Name);
	if (currentUser == null)  {
		// user was not found in the database
		arCN.Close();
		Response.Redirect("AccessDenied.aspx");
	}
	else {
		if (currentUser.IsLocked()) {
			//account is locked -> access denied
			arCN.Close();
			Response.Redirect("AccessDenied.aspx");
		}
		else {
			//account has been found and is not locked
			//create user ticket and store it in the session variable
			Session["ARUserTicket"] = new ARUserTicket(currentUser);
			arCN.Close();
		}
	}
}

What you did:

This code is duplicated with the logon form code. It's used if user chose the "Remember password" option on the logon form and didn't authenticate through the logon form.

The code creates user ticket and stores it in the session variable "ARUserTicket". The user ticket contains cached information about user, such as full name and membership in roles, user groups and organizational units.

Create the LogonForm.aspx page with logon form. Copy the following files from the Secure Access Web application (please note you only copy these files into your application's folder, you don't include them in the project!):

ARUILogonForm.ascx
ARUISendPassword.ascx
ARUISetPassword.ascx
ARUISignOut.ascx

Edit HTML source of the logon.aspx page and add following line on the second line (after the <%@ Page& directive):

<%@ Register TagPrefix="uc1" TagName="ARUILogonForm" Src="ARUILogonForm.ascx" %>

Put the following text somewhere inside the <form></form> tags:

<uc1:ARUILogonForm id="ARUILogonForm1" runat="server"></uc1:ARUILogonForm>

What you did:

You created LogonForm.aspx page and added the Secure Access logon control on it. This control ensures all that you need to authenticate user. It checks user's password and displays error messages when provided credentials are wrong or user account is locked. It also allows users to be sent with their password if they forget it and change their password if it expired. Please refer to the Appendix A - ASP.NET User Controls Reference to find detailed information about this control.

Create new page "default.aspx" and put the following code at the beginning of its HTML code:

<%@ Register TagPrefix="uc1" TagName="ARUISignOut" Src="ARUISignOut.ascx" %>

Put the following text somewhere inside the <form></form> tags:

<uc1:ARUISignOut id="ARUISignOut1" runat="server"></uc1:ARUISignOut>

What you did:

You created the "Sign out" button. The users can use it to sign out from your Web site.

Add following lines at the beginning of the default.aspx code-behind:

[Visual Basic]

Imports PortSight.SecureAccess.ARDataServices
Imports PortSight.SecureAccess.ARObjects



[C#]

using PortSight.SecureAccess.ARDataServices;
using PortSight.SecureAccess.ARObjects;

What you did:

You imported PortSight Secure Access namespaces to your code.

Add a new Label control on the default.aspx form and name it Label1. Add following code in the Page_Load method:

[Visual Basic]

Dim userTicket As ARUserTicket
userTicket = CType(Session("ARUserTicket"), ARUserTicket)
If Not userTicket Is Nothing Then
    Label1.Text = "Hi " & userTicket.ObjectName & ", welcome to the PortSight Secure Access demo."
End If



[C#]

ARUserTicket userTicket;
userTicket = (ARUserTicket) Session["ARUserTicket"];
if (userTicket != null) {
	Label1.Text = "Hi " + userTicket.ObjectName + ", welcome to the PortSight Secure Access demo.";
}

What you did:

You added code that takes user ticket stored in the session variable and displays welcome message.

Right-click the "default.aspx" page in the Solution Explorer and set it as a default. Compile and run your new Web application. You should see the log on form after the application starts:

Log on form

Enter your user name and password as you defined them in the Secure Access database and click the "Log on" button. You should see the welcome message now:

Welcome message for authenticated users

Click the "Sign out" button and you will be redirected back to the logon form.