Summary

By default, ASU.Web.Auth assembly will block unauthenticated access to all ASP.NET pages by redirecting the user to the login page. It also handles automatic authorization of users that log in using information from EDNA, LDAP or the EPM and optionally a user database containing roles specific to the web application.

Important Note: The ASU.Web.Auth assembly will NOT by default block access to pages not registered to be handled by ASP.NET (e.g html, htm and php pages, and image files). To protect such resources, they must be mapped to ASP.NET through IIS administration. This article ( http://aspnet.4guysfromrolla.com/articles/020404-1.aspx ) shows how to do this. Note that this will probably result in a significant performance hit.

Current production version is 2.6.0.0, and is available for checkout from:
The entire project can be checked out from: https://svn.asu.edu/svn/webcommune/.net/asu.web.auth/2.6.0.0/tags/prod-12-11-2007
Check out just the assembly from: https://svn.asu.edu/svn/webcommune/.net/asu.web.auth/2.6.0.0/tags/prod-12-11-2007/Auth/bin/Release/ASU.Web.Auth.dll

If you wish to expand on the ASU.Web.Auth assembly please check it out from: https://svn.asu.edu/svn/webcommune/.net/asu.web.auth/2.6.0.0/trunk/

You must be a member of the ASU Web Developer Commune group to get access to this project.

Here are the list of changes that have been made to the 2.6.0.0 version of the ASU.Web.Auth assembly:

1. Added code to do EDNA CheckAccess calls so that you can use EDNA to manage the authorization for your application. See below for the new AppSettings properties for EDNA CheckAccess calls.
2. Changed the Data Warehouse connection from the DIRECTORY_SERVICES database on Enterprise 1 which was fed information from the legacy HR and SIS systems to the DIRECTORY_SERVICES database on OraProd1 which is fed data from the PeopleSoft implementation.

See the following article for information on installing the ASU.Web.Auth assembly. If you want this assembly to appear in the Add Reference dialog box, simply place a copy of the assembly in the following folder C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\PublicAssemblies.

Configuration

All configuration options for ASU.Web.Auth assembly reside inside your web application's web.config file. Here is a listing of all configuration properties:

• <appSettings>
• <add key="ApplicationName" value="myApplication" />
• <add key="WebAuthVersion" value="0" />
• <add key="NoWebAuthPages" value="/trace.axd" />
• <add key="GuestWebAuthPages" value="/contactus.aspx" />
• <add key="LogoutRedirectUrl" value="http://www.asu.edu/" />
• -
• <add key="GuestAsuriteID" value="DEFAULT=webauthguest" />
• <add key="GuestRole" value="DEFAULT=guest" />
• <add key="GuestFirstName" value="DEFAULT=Guest" />
• <add key="GuestLastName" value="" />
• -
• <add key="AddEdnaAuthorizationRoles" value="true|false"/>
• <add key="EdnaClientCertificateName" value="example_app"/>
• <add key="EdnaAuthQueryType" value="xml|odbc|sql_storedprocedure"/>
• <add key="EdnaServiceNodePrefix" value="DEFAULT=application"/>
• <add key="EdnaRolesPrefix" value="DEFAULT=edna"/>
• <add key="EdnaUrl" value="DEFAULT=https://edna.asu.edu/edna-ws/services/privileged/"/>
• <add key="EdnaCheckAccessPath" value="DEFAULT=checkAccess/v1.0"/>
• <add key="EdnaAuthQuery" value="select roles from crazy"/>
• <add key="EdnaXmlFilePath" value="DEFAULT=/xml/edna.xml"/>
• -
• <add key="AddWebAuthRoles" value="true|false"/>
• <add key="WebAuthRolesPrefix" value="DEFAULT=webauth"/>
• -
• <add key="AddLocalAuthorizationRoles" value="true|flase"/>
• <add key="LocalAuthDatabaseType" value="odbc|sql_storedprocedure" />
• <add key="LocalAuthDatabaseQueryString" value="select roles from crazy where asurite_id = ?" />
• <add key="LocalAuthorizationRolesPrefix" value="DEFAULT=localauth"/>
• -
• <add key="AddActiveDirectoryGroups" value="true|false" />
• <add key="ActiveDirectoryRolesPrefix" value="DEFAULT=ad" />
• </appSettings>

• <connectionStrings>
• <add name="LdapPath" connectionString="LDAP://ds.asu.edu:389/ou=People,o=asu.edu" />
• <add name="LdapUsername" connectionString="<USERNAME>,ou=Readonly,o=asu.edu" />
• <add name="LdapPassword" connectionString="<PASSWORD>" />
• -
• <add name="EPMConnectionString" connectionString="" providerName="System.Data.ODBC" />
• -
• <add name="LocalAuthDatabaseConnectionString" connectionString="" provider="" />
• </connectionStrings>

General Properties

ApplicationName (required)
Set this to the name of your application (must be unique if you are running multiple web apps with webauth)

WebAuthVersion (required)
There are three valid values for this property:

• 0 = Workstation mode: Unauthenticated users are redirected to a local login page, which allows them to login with any user name, and assign any roles they want to themselves. This is for testing and development purposes only. See the "Workstation Login" below for more details.
• 1 = Webauth V1: Normal webauth operation, for ASU WEBAUTH Version 1.
• 2 = Webauth V2: Normal webauth operation, for ASU WEBAUTH Version 2.

NoWebAuthPages (optional)
Set this to a comma-separated list of URLs which will NOT require authentication, the ASU.Web.Auth assembly will not restrict access to them. You can also use '*' to indicate all URLs with a particular path are to be exempt from authentication. The following example indicates that /trace.axd is exempt and so are all URLs with the path of /Exempt/:

• <add key="NoWebAuthPages" value="/trace.axd,/Exempt/*" />

GuestWebAuthPages (optional)
Set this to a comma-separated list of URLs which allow 'guests' to visit them where 'guests' are users that have not logged in through ASU WebAuth. Under this situation, ASU.Web.Auth assembly will

• assign the user an asurite id of GuestAsuriteId (see below)
• assign the user a role(s) of LocalAuthorizationRolesPrefix.GuestRole, WebAuthRolesPrefix.GuestRole, EdnaRolesPrefix.GuestRole, and/or ActiveDirectoryRolesPrefix.GuestRole depending on which authorization options you have enabled for you application.

If a user has already logged in through ASU WebAuth and you have the AddWebAuthRoles configuration property set to 'true', he/she is automatically assigned the WebAuthRolesPrefix.GuestRole (by default 'webauth.guest') role so they can access any page that 'guest' users can access. You can also use '*' to indicate all URLs with a particular path are to allow guest access. The following example indicates that the home page for the application is to allow guest access along with all of the URLs under the support folder:

• <add key="GuestWebAuthPages" value="/default.aspx,/Support/*" />

LogoutRedirectUrl (optional)
Set this to the full URL of the page you want the user to be redirected to when they log out. If this property is not set, the user will be redirected to the default page of the root directory of the application.

Guest User Configuration

GuestAsuriteId (optional, default = "webauthguest")
The ASURITE ID that will be used if the user is logged in as a 'guest'.

GuestFirstName, GuestLastName (optional, default = "Guest", no last name)
The first and last name of the 'guest' user.

GuestRole (optional, default = "guest")
A role that is given to users logged in as 'guest'.

Authorization Options

There are several different authorization options that can be used with the ASU.Web.Auth assembly, and you can use multiple authorization options at the same time, however the encrypted cookie that stores this information has a size limit of 4k, if the combined information that needs to be stored goes over this 4k limit then the cookie will not be created. The ASU.Web.Auth assembly will still function in this situation however all authentication processes will be run for every post back, which can cause a performance hit depending on which options you have enabled. In general it appears to take about 200 roles to put the cookie over this limit.

EDNA Authorization

AddEdnaAuthorizationRoles, EdnaClientCertificateName, EdnaAuthQueryType, EdnaServiceNodePrefix, EdnaRolesPrefix, EdnaUrl, EdnaCheckAccessPath, EdnaAuthQuery, EdnaXmlFilePath (optional)
Set these properties in the appSettings section of the web.config file to allow EDNA to be used to populate the roles object in the principal object (the AsuritePrincipal object is attached to the user's HttpContext). Not all of these properties need to be populated in order for the EDNA checkAccess calls to work.

AddEdnaAuthorizationRoles (optional, default = "false")
This configuration property needs to be set to 'true' in order for the ASU.Web.Auth assembly to attempt to make the EDNA checkAccess calls.

EdnaClientCertificateName (optional, required for EDNA Authorization to function)
This configuration property needs to be set to the name of the client certificate that will be used for the mutual SSL authentication process that EDNA employs to secure its web services. See the Creating and Installing Client Certificate on a Windows Machine for EDNA or OGATE document for information about getting a client certificate.

• <add key="EdnaClientCertificateName" value="example_app" />

EdnaAuthQueryType (optional, required for EDNA Authorization to function)
This configuration property is required for the EDNA checkAccess calls to succeed. The ASU.Web.Auth assembly needs to know what service nodes you want to do EDNA checkAccess calls on, there are three valid values for this property:

• "xml" : Specifies that an XML file should be used to retrieve the service nodes to call checkAccess against.
• "odbc" : Specifies that the EdnaAuthQuery property will contain a TSQL statement to be used to query the LocalAuthDatabaseConnectionString database to retireve the service nodes to call checkAccess against.
• "sql_storedprocedure" : Specifies that the EdnaAuthQuery property will contain a stored procedure name that will be used to query the LocalAuthDatabaseConnectionString database to retireve the service nodes to call checkAccess against.

EdnaServiceNodePrefix (optional, default = "application")
This configuration property needs to be set to the value of the primary EDNA service node that will be used by your application, this value is prepended to all service nodes retrieved from the EdnaAuthQueryType call whether that be an XML file or a database query. This property in conjunction with the EdnaRolesPrefix property will allow you to develop your application using a different set of EDNA service nodes while you wait for the service nodes for the application to be created.

• <add key="EdnaServiceNodePrefix" value="ExampleNode" />

EdnaRolesPrefix (optional, default = "edna")
Set this property to a string which will be used as a prefix to all checkAccess calls that result in a "true" response. A period '.' will separate the prefix from the role name.

EdnaUrl (optional, default = "https://edna.asu.edu/edna-ws/services/priviledged/")
This configuration property only needs to be set if you are attempting to access non-production EDNA web services.

EdnaCheckAccessPath (optional, default = "checkAccess/v1.0")
This configuration property only needs to be set if you are attempting to access a different version of the EDNA checkAccess web service, as of the time of writing this is the only version available.

EdnaAuthQuery (optional, required if EdnaAuthQueryType is set to 'odbc' or 'sql_storedprocedure')
This configuration property tells the ASU.Web.Auth assembly how to get the list of service nodes to make EDNA checkAccess calls against. If the EdnaAuthQueryType property is set to 'odbc' then the EdnaAuthQuery property should look something like this:

• <add key="EdnaAuthQueryType" value="select nodes from edna" />

If the EdnaAuthQueryType property is set to 'sql_storedprocedure' then the EdnaAuthQuery property should look something like this:

• <add key="EdnaAuthQueryType" value="EdnaNodes_Get" />

EdnaXmlFilePath (optional, default = "/xml/edna.xml")
This configuration property tells the ASU.Web.Auth assembly where it will find the XML file that contains the service nodes that it should preform EDNA checkAccess calls against. If the EdnaAuthQueryType property is set to 'xml' then you need to provide an XML file of the service nodes in your application, by default the ASU.Web.Auth assembly will look in the directory 'xml' for a file called 'edna.xml'. The contents of the XML file should look like this:

• <?xml version="1.0" encoding="utf-8" ?>
• <edna>
• <node>currentStudent</node>
• <node>eAdvisor</node>
• <node>undergraduate</node>
• <node>graduate</node>
• <node>freshman</node>
• <node>sophomore</node>
• <node>junior</node>
• <node>senior</node>
• <node>admin</node>
• <node>admin.manage</node>
• </edna>

WebAuth Authorization

AddWebAuthRoles(optional, default = "false")
Set this property to "true" to have the ASU.Web.Auth assembly parse the WebAuth return string to add roles to the principal object.

WebauthRolesPrefix(optional, default = "webauth")
Set this property to a string which will be used as a prefix to all roles parsed from the WebAuth return string. A period '.' will separate the prefix from the role name.

Local Database Authorization

AddLocalAuthorizationRoles (optional, default = "false")
Set this to "true" to have the module gather additional roles from the local authorization database specified by the UserDatabase* propertys.

LocalAuthDatabaseConnectionString (optional)
Set this to the connection string to your web application's user database, which contains the assigned roles for each user.

LocalAuthDatabaseType and LocalAuthDatabaseQueryString (optional)
There are two valid values for this property:

• "odbc" : The UserDatabaseQueryString_ property contains a SQL SELECT query with a single parameter (indicated by a question mark). For getting the roles list from the database, Webauth will execute this query.
• "sql_storedprocedure" : The UserDatabaseQueryString_ property contains the name of a stored procedure. Webauth will execute the stored procedure to get the roles list from the database.

LocalAuthorizationRolesPrefix (optional, default = "localauth")
Set this property to a string which will be used as a prefix to all roles returned from the LocalAuthDatabaseQuery query. A period '.' will separate the prefix from the role name.

Active Directory Authorization

AddActiveDirectoryGroups (optional, default = "false")
Set this to "true" to have the module use the user's ID as an Active Directory user name, and gather that user's group memberships as user roles.

ActiveDirectoryRolesPrefix (optional, default = "ad")
Set this property to a string which will be used as a prefix to all groups returned from the AD query. A period '.' will separate the prefix from the group name.

Using ASU.Web.Auth in your application

By gathering user information while authenticating via the configured databases, the ASU.Web.Auth assembly can manage authorization as well as authentication. There are two ways to use these features in your applications:

Using <authorization> in web.config
Roles assigned to the user during authentication can be checked against declaratively through the web.config file. Simply add sections of the following form:

• <location path="StudentAccounts">
• <system.web>
• <authorization>
• <allow roles="professional studies.advisor, myCLAS.superuser"/>
• <deny users="*"/>
• </authorization>
• </system.web>
• </location>

For more information on how to use sections, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/gngrfauthorizationsection.asp

Giving Guest Access
To give guest access in your application, follow these steps:
1) Indicate which pages allow guest access using the following key in web.config:

• <add key="GuestWebAuthPages" value="/FAR/default.aspx,/FAR/Support/*" />

2) Grant access to the guest role in web.config using 'webauth.guest' like the following:

• <location path="Support">
• <system.web>
• <authorization>
• <allow roles="webauth.guest"/>
• <deny users="*"/>
• </authorization>
• </system.web>
• </location>

Using the AsuritePrincipal

Your ASP.NET pages will have in their disposal an IPrincipal object in Application.Context.User. Handling the object as an IPrincipal will not allow you to use the additional properties that exist in the object.
To be able to reference and use AsuritePrincipal:

• Add an Assembly Reference to ASU.Web.Auth.dll to your web application project.
• Simply cast the IPrincipal object to AsuritePrincipal:

• ASU.Web.Auth.AsuritePrincipal pr = (AsuritePrincipal) Application.Context.User; //(ASP.NET 1.1)
• // or
• ASU.Web.Auth.AsuritePrincipal pr = (AsuritePrincipal) HttpContext.Current.User; //(ASP.NET 2.0)

Populating the AsuritePrincipal object

There are two different methods that can be used to populate the AsuritePrincipal object, they are LDAP and EPM. If both the LDAP information and EPMConnectionString information are supplied, then the ASU.Web.Auth assembly will first try to lookup the user in LDAP and if the AffiliateId property is null, then it will try to lookup the user in the EPM.

LDAP

LdapPath, LdapUsername, LdapPassword (optional)
Set these three properties in the connectionStrings section of the web.config file to allow LDAP to be used to fill in the principal object (the AsuritePrincipal object is attached to the user's HttpContext). All three need to be supplied to be able to perform the LDAP lookup.

• <add name="LdapPath" connectionString="LDAP://ds.asu.edu:389/ou=People,o=asu.edu">
• <add name="LdapUsername" connectionString="<USERNAME>,ou=Readonly,o=asu.edu">
• <add name="LdapPassword" connectionString="<PASSWORD>">

EPM

EPMConnectionString (optional)
Set this to the complete ODBC connection string to the EPM. If this is set, it will be used to fill in the principal object (the AsuritePrincipal object attached to the user's HttpContext) using this query:

• SELECT PERSON_ID, ASU_AFFIL_DESCR, CAMPUS_ID, ASU_BUILDING, ASU_CAMPUS_AFFIL, ACAD_PROG_LD,
  ACAD_PROG, DEPT_LD, DEPT_ID, NAME_DISPLAY, ASU_DIRECTORY_ADDR, FIRST_NAME, LAST_NAME,
  ASU_MAIL_CODE, ACAD_PLAN_LD, ACAD_PLAN, PHONE, ASU_PRIMARY_AFFIL, ASU_ROOM, TITLE
  FROM CMSC.PS_ASU_DIRECT_SRVC
  WHERE ASU_ASURITE_ID = ?

Where the '?' is filled in with the ASURITE ID of the user. Please see 'Using Webauth in your Application' for information on how to access that information through your web application.

Properties

AsuritePrincipal has the following public properties:

• AffiliateID (String) - Holds the Affiliate ID number of the user.
• Affiliation Description (String) - Holds the Affiliate Description of the user.
• AsuID (String) - Holds the ASU ID number of the user.
• AsuriteID (String) - Holds the true ASURITE ID of the user or the ASURITE ID or the user being impersonated.
• BuildingName (String) - Holds the Building Name of the user.
• CampusAffiliation (String) - Holds the Campus Affiliation of the user.
• College (String) - Holds the College of the user.
• CollegeCode (String) - Holds the College Code of the user.
• DepartmentCode (String) - Holds the Department Code of the user.
• DepartmentName (String) - Holds the Department Name of the user.
• EmailAddress (String) - Holds the Email Address of the user.
• FirstName (String) - Holds the First Name of the user.
• IsImpersonating (Boolean) - Returns whether the current user is trying to impersonate someone else.
• LastName (String) - Holds the Last Name of the user.
• LastValidated (DateTime) - Holds the Last Validated DateTime of the User.
• MailCode (String) - Holds the Mail Code of the user.
• Major (String) - Holds the Major of the user.
• MajorCode (String) - Holds the Major Code of the user.
• Name (String) - Holds the Display Name of the user.
• PhoneNumber (String) - Holds the Phone Number of the user.
• RoomNumber (String) - Holds the Room Number of the user.
• Title (String) - Holds the Title of the user.
• TrueAsuriteID (String) - Holds the True ASURITE ID of the user.

AsuritePrincipal has the following public methods:

• AddRoles (ArrayList) - Appends new roles to the principal's role list for the given request.
• GetActiveDirectoryGroups (ArrayList) - Gets an array of active directory groups the user belongs to
• GetApplications (ArrayList) - Gets an array of applications the user has roles for in the local authorization database
• IsInActiveDirectoryGroup (Boolean) - Checks to see if the user belongs to an active directory group.
• IsInAllRoles (Boolean) - Checks whether the user has all of the specified roles.
• IsInAnyRoles (Boolean) - Checks whether the user is in any of the specified set of roles.
• IsInApplication (Boolean) - Checks to see if the user has a role that starts with the applicationName. Role naming convention is "e;application name.role name"e;.
• IsInRole (Boolean) - Checks to see if the user is in the specified role.